Home

Awesome

Editor

Source code editor in pure Go.

screenshot

screenshot

screenshot

screenshot

About

Features

Installation

Instalation with git

Get with git the latest from the default master branch:

git clone https://github.com/jmigpin/editor

Build and run:

cd ./editor
go build
./editor

Windows platform compilation alternatives:

go build				# shows one console window (will be hidden, but makes a flash)
go build -ldflags -H=windowsgui		# hides the console window, but cmds will popup consoles
go build -tags=xproto 			# (not native, needs an x11 server to run)

Instalation with go tooling to be used as a library

go get -u github.com/jmigpin/editor

Please take care to distinguish between versions and ensure "go get" is actually getting the version you want.

This project is not using "vX" named directories. So version 3 is not in the directory "v3", nor is it named "*/v3" in imports. Versions are being updated using the same import path. The downside of this is that go websites (ex: pkg.go.dev) don't recognize versions tagged as 3 and above of this project.

Currently a release will be tagged with two tags that refer to the same version (ex: 3.3.0 and 1.3.3 is the same version).

Feel free to file an issue if you know of a better solution that doesn't require to use an import path of a directory that might not exist (case of using "vX" import paths).

Usage

<!--__usageSectionStart__--> 
Usage of editor:
  -carriagereturnrune int
    	replacement rune for carriage return (default 9834)
  -colortheme string
    	available: light, acme, lightInverted, acmeInverted (default "light")
  -commentscolor int
    	Colorize comments. Can be set to 0x1 to not colorize. Ex: 0xff0000=red.
  -cpuprofile string
    	profile cpu filename
  -dpi float
    	monitor dots per inch (default 72)
  -font string
    	font: regular, medium, mono, or a filename (default "regular")
  -fonthinting string
    	font hinting: none, vertical, full (default "full")
  -fontsize float
    	 (default 12)
  -lsproto value
    	Language-server-protocol register options. Can be specified multiple times.
    	Format: language,fileExtensions,network{tcp|tcpclient|stdio},command,optional{stderr,nogotoimpl}
    	Format notes:
    		if network is tcp, the command runs in a template with vars: {{.Addr}}.
    		if network is tcpclient, the command should be an ipaddress.
    	Examples:
    		go,.go,stdio,"gopls serve"
    		go,.go,tcp,"gopls serve -listen={{.Addr}}"
    		cpp,".c .h .cpp .hpp .cc",stdio,"clangd"
    		python,.py,stdio,pylsp
    		python,.py,tcpclient,127.0.0.1:9000
    		python,.py,stdio,pylsp,"stderr nogotoimpl"
  -plugins string
    	comma separated string of plugin filenames
  -presavehook value
    	Run program before saving a file. Uses stdin/stdout. Can be specified multiple times. By default, a "goimports" entry is auto added if no entry is defined for the "go" language.
    	Format: language,fileExtensions,cmd
    	Examples:
    		go,.go,goimports
    		cpp,".cpp .hpp","\"clang-format --style={'opt1':1,'opt2':2}\""
    		python,.py,python_formatter
  -scrollbarleft
    	set scrollbars on the left side (default true)
  -scrollbarwidth int
    	Textarea scrollbar width in pixels. A value of 0 takes 3/4 of the font size.
  -sessionname string
    	open existing session
  -shadows
    	shadow effects on some elements (default true)
  -sn string
    	open existing session
  -stringscolor int
    	Colorize strings. Can be set to 0x1 to not colorize. Ex: 0xff0000=red.
  -tabwidth int
    	 (default 8)
  -usemultikey
    	use multi-key to compose characters (Ex: [multi-key, ~, a] = ã)
  -version
    	output version and exit
  -wraplinerune int
    	code for wrap line rune, can be set to zero (default 8592)
  -zipsessionsfile
    	Save sessions in a zip. Useful for 100+ sessions. Does not delete the plain file. Beware that the file might not be easily editable as in a plain file.
<!--__usageSectionEnd__-->

The editor has no configuration file. Use it within a script with your preferences (example editor.sh):

#!/bin/sh
exec ~/path/editor \
--dpi=143 \
--fontsize=9 \
--colortheme=acme \
--commentscolor=0x008b00 \
--stringscolor=0x8b3100 \
--lsproto=go,.go,stdio,"gopls serve" \
--lsproto="cpp,\".c .h .cpp .hpp .cc\",stdio,clangd" \
--presavehook=go,.go,goimports \
--presavehook="cpp,\".c .h .cpp .hpp\",\"clang-format --someoption\"" \
"$@"

Basic Layout

The editor has a top toolbar and columns. Columns have rows. Rows have a toolbar and a textarea.

These row toolbars are also textareas where clicking (buttonRight) on the text will run that text as a command.

The row toolbar has a square showing the state of the row.

Toolbar usage examples

Commands in toolbars are separated by "|" (not to be confused with the shell pipe). If a shell pipe is needed it should be escaped with a backslash.

All internal commands start with an Uppercase letter. Otherwise it tries to run an existent external program.

Examples:

Commands

Toolbar commands

Row toolbar commands

These commands run on a row toolbar, or on the top toolbar with the active-row.

Row name at the toolbar (usually the filename)

Textarea commands

Commands: GoDebug

Output of GoDebug -help:

<!--__godebugUsageSectionStart__--> 
Usage:
	GoDebug <command> [arguments]
The commands are:
	run		build and run program with godebug data
	test		test packages compiled with godebug data
	build 	build binary with godebug data (allows remote debug)
	connect	connect to a binary built with godebug data (allows remote debug)
Env variables:
	GODEBUG_BUILD_FLAGS	comma separated flags for build
Examples:
	GoDebug run
	GoDebug run -help
	GoDebug run main.go -arg1 -arg2
	GoDebug run -paths=dir1,file2.go,dir3 main.go -arg1 -arg2
	GoDebug run -tags=xproto main.go
	GoDebug run -env=GODEBUG_BUILD_FLAGS=-cover main.go
	GoDebug run -network=ws -startexec=false -env=GOOS=js:GOARCH=wasm -o=static/main.wasm client/main.go
	GoDebug test
	GoDebug test -help
	GoDebug test -run=mytest -v
	GoDebug test a_test.go -test.run=mytest -test.v -test.count 5
	GoDebug build -help
	GoDebug build -addr=:8078 main.go
	GoDebug build -network=ws -addr=:8078 -env=GOOS=js:GOARCH=wasm -o=static/main.wasm client/main.go
	GoDebug connect -help
	GoDebug connect -addr=:8078
	GoDebug connect -network=ws -addr=:8078
	GoDebug connect -network=auto --continueserving
<!--__godebugUsageSectionEnd__-->

Output of GoDebug run -help:

<!--__godebugRunUsageSectionStart__--> 
Usage of GoDebug run:
  -addr string
    	address to transmit debug data
  -editorisserver
    	run editor side as server instead of client (default true)
  -env string
    	string with env variables (ex: "a=1:b=2:...")
  -network string
    	protocol to use to transmit debug data: [tcp, ws, unix, auto]. Option 'auto' detects a tcp client request to auto upgrade to http/websocket. Ex: useful to alternate between a debug session for a server (tcp) and a brower (websocket), without restarting the godebug cmd (use with -continueserving).
  -nodebugmsg
    	omit debug messages
  -o string
    	output filename
  -paths string
    	comma-separated string of dirs/files to annotate (also see the "//godebug:annotate*" source code directives to set files to be annotated)
  -sbr
    	Stringify bytes/runes as string (ex: [97 98 99] outputs as "abc") (default true)
  -srclines
    	add src reference lines to the compilation such that in case of panics, the stack refers to the original src file (default true)
  -startexec
    	start executable; useful to set to false in the case of compiling for js/wasm where the browser is the one starting the compiled file (default true)
  -syncsend
    	Don't send msgs in chunks (slow). Useful to get msgs before a crash.
  -toolexec string
    	a program to invoke before the program argument. Useful to run a tool with the output file (ex: wine)
  -usepkglinks
    	Use symbolic links to some pkgs directories to build the godebug binary. Helps solving new behaviour introduced by go1.19.x. that fails when an overlaid file depends on a new external module. (default true)
  -verbose
    	print extra godebug build info
  -work
    	print workdir and don't cleanup on exit
<!--__godebugRunUsageSectionEnd__-->

Internal variables

Environment variables set available to external commands

Row states

Plugins

Plugins allow extra functionality to be added to the editor without changing the binary.

A plugin can be compiled and run with (will output a *.so):

go build -buildmode=plugin plugin1.go
go build -buildmode=plugin plugin2.go
editor --plugins plugin1.so,plugin2.so

Functions that can be implemented by a plugin are (subject to changes - work-in-progress ):

func OnLoad(ed *core.Editor)
func AutoComplete(ctx context.Context, ed *core.Editor, cfb *ui.ContextFloatBox) (err error, handled bool) // error` is only considered if `handled` is true
func ToolbarCmd(ed *core.Editor, erow *core.ERow, part *toolbarparser.Part) bool

Note that plugins might need to be recompiled everytime there are changes in the libraries provided by the editor.

Editor events currently implemented (subject to changes - work-in-progress ):

PostNewERowEEventId // on erow creation
PostFileSaveEEventId // after a file is saved
PreRowCloseEEventId // before a row is closed
RowStateChangeEEventId // on row state change (duplicate rows also emit).

Plugins located at: ./plugins.

Key/button shortcuts

Global key/button shortcuts

Column key/button shortcuts

Row key/button shortcuts

Textarea key/button shortcuts

Row placement algorithm

When a new row is created, it is placed either below the current row (measuring available space), or in a "good position".

The "good position" measures the available space between all rows, and uses the position with the most space.

The measuring of space is done as follows:

  1. if the cursor is visible, measure space after visible cursor to the end of the textarea and use it if not smaller than two lines in height, otherwise use 2)
  2. about 2/3 of the textarea

Notes

Releases