README.md
1
2
3 [](https://goreportcard.com/report/github.com/xyproto/o) [](https://raw.githubusercontent.com/xyproto/o/main/LICENSE)
4
5`o` is a text editor.
6
7It might be a good fit for:
8
9* Editing git commit messages (using `EDITOR=o git commit`).
10* Editing `README.md` and `TODO.md` files.
11* Write Markdown files and then export to PDF.
12* Learning programming languages, like Rust or Zig.
13* Editing files deep within larger Go or C++ projects.
14* Solving Advent of Code tasks.
15* Writing and maintaining to-do lists and project documentation in Markdown.
16* Testing if your favorite package manager can handle one-letter package names.
17
18For a more feature complete editor that is also written in Go, check out [micro](https://github.com/zyedidia/micro).
19
20## Screenshot
21
22Screenshot of the VTE GUI application that can be found in the `ko` directory, running the `o` editor:
23
24
25
26## Packaging status
27
28[](https://repology.org/project/o-editor/versions) [](https://repology.org/project/o/versions)
29
30## Quick start
31
32With Go 1.17 or later, `o` can be installed like this:
33
34 go install github.com/xyproto/o@latest
35
36Alternatively, download and install a [release version](https://github.com/xyproto/o/releases). For example, for Raspberry Pi 2, 3 or 4 running Linux:
37
38 curl -sL 'https://github.com/xyproto/o/releases/download/2.45.0/o-2.45.0-rpi.tar.xz' | tar JxC /tmp && sudo install -Dm755 /tmp/o-2.45.0-rpi/o /usr/bin/o && sudo install -Dm644 /tmp/o-2.45.0-rpi/o.1.gz /usr/share/man/man1/o.1.gz
39
40* Remember to use `tar zxC` if the release file for your platform ends with `.tar.gz`.
41* The `sudo install` commands may be slightly different for FreeBSD and NetBSD.
42
43## Setting `o` as the default editor for `git`
44
45To set:
46
47 git config --global core.editor o
48
49To unset:
50
51 git config --global --unset core.editor
52
53## Viewing man pages
54
55By setting the `MANPAGER` environment variable, it's possible to use `o` for viewing man pages:
56
57 export MANPAGER=o
58
59An alternative to viewing man pages in `o` is to use `less`:
60
61 export MANPAGER='less -s -M +Gg'
62
63## Unique features
64
65These features are unique to `o`, as far as I am aware:
66
67* Smart cursor movement, trying to maintain the X position when moving up and down, across short and long lines.
68* Press `ctrl-v` once to paste one line, press `ctrl-v` again to paste the rest.
69* Press `ctrl-c` once to copy one line, press `ctrl-c` again to copy the rest (until a blank line).
70* Open or close a portal with `ctrl-r`. When a portal is open, copy lines across files (or within the same file) with `ctrl-v`.
71* Build code with `ctrl-space` and format code with `ctrl-w`, for a wide range of programming languages.
72* Cycle git rebase keywords with `ctrl-r`, when an interactive git rebase session is in progress.
73* Jump to a line with `ctrl-l`. Either enter a number to jump to a line or just press `return` to jump to the top. Press `ctrl-l` and `return` again to jump to the bottom.
74* All text will be red if the loaded file is read-only.
75* If tab completion in the terminal went wrong and you are trying to open a `main.` file that does not exist, but `main.cpp` and `main.o` does exists, then `main.cpp` will be opened.
76* For C-like languages, missing parentheses are added to statements like `if`, `for` and `while` when return is pressed.
77
78## Other features and limitations
79
80* The syntax highlighting is instant.
81* Can compile `"Hello, World"` in many popular programming languages simply by pressing `ctrl-space`.
82* Configuration-free, for better and for worse.
83* `ctrl-t` can jump between a C++ header and source file.
84* Provides syntax highlighting for Go, C++, Markdown, Bash and several other languages. There is generic syntax highlighting built-in.
85* Will jump to the last visited line when opening a recent file.
86* Is provided as a single self-contained executable.
87* Loads faster than both `vim` and `emacs`, for small files.
88* Can render text to PDF.
89* Tested with `alacritty`, `st`, `urxvt`, `konsole`, `zutty` and `xfce4-terminal`.
90* Tested on Arch Linux, Debian and FreeBSD.
91* Never asks before saving or quitting. Be careful!
92* The [`NO_COLOR`](https://no-color.org) environment variable can be set to disable all colors.
93* Rainbow parentheses makes lines with many parentheses easier to read.
94* Limited to VT100, so hotkeys like `ctrl-a` and `ctrl-e` must be used instead of `Home` and `End`.
95* Compiles with either `go` or `gccgo`.
96* Will strip trailing whitespace whenever it can.
97* Must be given a filename at start.
98* May provide smart indentation.
99* Requires that `/dev/tty` is available.
100* `xclip` (for X) or `wl-clipboard` (for Wayland) must be installed if the system clipboard should be used.
101* May take a line number as the second argument, with an optional `+` or `:` prefix.
102* If the filename is `COMMIT_EDITMSG`, the look and feel will be adjusted for git commit messages.
103* Supports `UTF-8`, but some runes may be displayed incorrectly.
104* Only UNIX-style line endings are supported (`\n`).
105* Will convert DOS/Windows line endings (`\r\n`) to UNIX line endings (just `\n`), whenever possible.
106* Will replace non-breaking space (`0xc2 0xa0`) with a regular space (`0x20`) whenever possible.
107* If interactive rebase is launched with `git rebase -i`, then either `ctrl-w` or `ctrl-r` will cycle the keywords for the current line (`fixup`, `drop`, `edit` etc).
108* If the editor executable is renamed to a word starting with `r` (or have a symlink with that name), the default theme will be red/black.
109* If the editor executable is renamed to a word starting with `l` (or have a symlink with that name), the default theme will be suitable for light backgrounds.
110* Want to quickly convert Markdown to PDF and have pandoc installed? Try `o filename.md`, press `ctrl-space` and quit with `ctrl-q`.
111* Press `ctrl-w` to toggle the check mark in `- [ ] TODO item` boxes in Markdown.
112* `o` is written mostly in `o`, with some use of NeoVim for the initial development.
113* The default syntax highlighting theme aims to be as pretty as possible with less than 16 colors, but it mainly aims for clarity. It should be easy to spot a keyword, number, string or a stray parenthesis.
114
115## Known bugs
116
117* Using `tmux` and resizing the terminal emulator window may trigger text rendering issues. Try pressing `esc` to redraw the text.
118* For some terminal emulators, if `o` is busy performing an operation, pressing `ctrl-s` may lock the terminal. Some terminal emulators, like `konsole`, can be configured to turn off this behavior. Press `ctrl-q` to unlock the terminal again (together with the unfortunate risk of quitting `o`). You can also use the `ctrl-o` menu for saving and quitting.
119* Some unicode runes may disrupt the text flow. This is generally not a problem for editing code and configuration files, but may be an issue when editing files that contains text in many languages.
120* `o` may have issues with large files (of several MB+). For normal text files or source code files, this is a non-issue.
121* Using backspace near the end of lines that are longer than the terminal width may cause the cursor to jump.
122* Middle-click pasting (instead of pasting with `ctrl-v`) may only paste the first character.
123* The smart indentation is not always smart.
124
125## Hotkeys
126
127* `ctrl-s` - Save.
128* `ctrl-q` - Quit.
129* `ctrl-r` - Open or close a portal. Text can be pasted from the portal into another file with `ctrl-v`.
130 For "git interactive rebase" mode (`git rebase -i`), this will cycle the rebase keywords.
131* `ctrl-w` - Format the current file (see the table below).
132* `ctrl-a` - Go to start of text, then start of line and then to the previous line.
133* `ctrl-e` - Go to end of line and then to the next line.
134* `ctrl-p` - Scroll up 10 lines, or go to the previous match if a search is active.
135* `ctrl-n` - Scroll down 10 lines, or go to the next match if a search is active.
136* `ctrl-k` - Delete characters to the end of the line, then delete the line.
137* `ctrl-g` - Toggle a status line at the bottom for displaying: filename, line, column, Unicode number and word count.
138* `ctrl-d` - Delete a single character.
139* `ctrl-t` - For C and C++: jump between the current header and source file. For other file types, render the current document to a PDF file.
140* `ctrl-o` - Open a command menu with actions that can be performed. The first menu item is always `Save and quit`.
141* `ctrl-x` - Cut the current line. Press twice to cut a block of text (to the next blank line).
142* `ctrl-c` - Copy one line. Press twice to copy a block of text.
143* `ctrl-v` - Paste one trimmed line. Press twice to paste multiple untrimmed lines.
144* `ctrl-space` - Build (see table below)
145* `ctrl-j` - Join lines (or jump to the bookmark, if set).
146* `ctrl-u` - Undo (`ctrl-z` is also possible, but may background the application).
147* `ctrl-l` - Jump to a specific line number. Follows by `return` to jump to the top. If at the top, press `return` to jump to the bottom.
148* `ctrl-f` - Search for a string. The search wraps around and is case sensitive. Press tab instead of return to search and replace.
149* `esc` - Redraw the screen and clear the last search.
150* `ctrl-b` - Toggle a bookmark for the current line, or if set: jump to a bookmark on a different line.
151* `ctrl-\` - Comment in or out a block of code.
152* `ctrl-~` - Jump to a matching parenthesis.
153
154## Updating PKGBUILD files
155
156When editing `PKGBUILD` files, it is possible to press `ctrl-o` and select `Call Guessica` to update the `pkgver=` and `source=` fields, by a combination of guesswork and online searching.
157
158* The Guessica package update utility is available here: [`guessica`](https://github.com/xyproto/guessica).
159
160## Build and format
161
162* At the press of `ctrl-space`, `o` will try to build or export the current file.
163* At the press of `ctrl-w`, `o` will try to format the current file, in an opinionated way. If the current file is empty, template text may be inserted.
164
165| Programming language | File extensions | Jump to error | Build command | Format command ($filename is a temporary file) |
166|-------------------------------------------------|-----------------------------------------------------------|---------------|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
167| Go | `.go` | yes | `go build` | `goimports -w -- $filename` |
168| C++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp`, `.c++`, `.h++`, `.c` | yes | `cxx` | `clang-format -fallback-style=WebKit -style=file -i -- $filename` |
169| Rust | `.rs` | yes | `rustc $filename` | `rustfmt $filename` |
170| Rust, if `Cargo.toml` or `../Cargo.toml` exists | `.rs` | yes | `cargo build` | `rustfmt $filename` |
171| Zig | `.zig` | yes | `zig build-exe -lc $filename` | `zig fmt $filename` |
172| V | `.v` | yes | `v build` | `v fmt $filename` |
173| Haskell | `.hs` | yes | `ghc -dynamic $filename` | `brittany --write-mode=inplace $filename` |
174| Python | `.py` | yes | `python -m py_compile $filename` | `autopep8 -i --maxline-length 120 $filename` |
175| Crystal | `.cr` | yes | `crystal build --no-color $filename` | `crystal tool format $filename` |
176| Kotlin | `.kt` | yes | `kotlinc $filename -include-runtime -d` | `ktlint` |
177| Kotlin, if `kotlinc-native` is installed | `.kt` | yes | `kotlinc-native -nowarn -opt -Xallocator=mimalloc -produce program -linker-option '--as-needed' $filename` | `ktlint` |
178| Java | `.java` | yes | `javac` + `jar`, see details below | `google-java-format -i $filename` |
179| Scala | `.scala` | yes | `scalac` + `jar`, see details below | WIP |
180| Lua | `.lua` | yes | `luac` | `lua-format -i --no-keep-simple-function-one-line --column-limit=120 --indent-width=2 --no-use-tab $filename` |
181| Object Pascal | `.pas`, `.pp`, `.lpr` | yes | `fpc` | WIP |
182| Nim | `.nim` | WIP | `nim c` | WIP |
183| Odin | `.odin` | yes | `odin build` | N/A |
184| C# | `.cs` | yes | `csc -nologo -unsafe $filename` | `astyle -mode=cs main.cs` |
185| JavaScript | `.js` | WIP | | `prettier --tab-width 4 -w $filename` |
186| TypeScript | `.ts` | WIP | | WIP |
187| D | `.d` | yes | `gdc` | WIP |
188| Clojure | `.clj`, `.cljs`, `.clojure` | WIP | `lein uberjar` | WIP |
189| Standard ML | `.sml` | yes | `mlton` | WIP |
190| OCaml | `.ml` | WIP | `ocamlopt -o $executable $filename` | WIP |
191
192`/etc/fstab` files are also supported, and can be formatted with `ctrl-w` if [`fstabfmt`](https://github.com/xyproto/fstabfmt) is installed.
193
194| Markup language | File extensions | Jump to error | Format command ($filename is a temporary file) |
195|----|----|----|----|
196| HTML | `.htm`, `.html` | no | `tidy -w 120 -q -i -utf8 --show-errors 0 --show-warnings no --tidy-mark no --force-output yes -ashtml -omit no -xml no -m -c` |
197
198* `o` will try to jump to the location where the error is and otherwise display `Success`.
199* For regular text files, `ctrl-w` will word wrap the lines to a length of 99.
200* If `kotlinc-native` is not available, this build command will be used instead: `kotlinc $filename -include-runtime -d $name.jar`
201
202CXX can be downloaded here: [GitHub project page for CXX](https://github.com/xyproto/cxx).
203
204| File type | File extensions | Build or export command |
205|-----------|------------------|-------------------------------------------------------------------|
206| AsciiDoc | `.adoc` | `asciidoctor -b manpage` (writes to `out.1`) |
207| scdoc | `.scd`, `.scdoc` | `scdoc` (writes to `out.1`) |
208| Markdown | `.md` | `pandoc -N --toc -V geometry:a4paper` (writes to `$filename.pdf`) |
209
210## Manual installation
211
212On Linux:
213
214 git clone https://github.com/xyproto/o
215 cd o
216 go build -mod=vendor
217 sudo install -Dm755 o /usr/bin/o
218 gzip o.1
219 sudo install -Dm644 o.1.gz /usr/share/man/man1/o.1.gz
220
221## Dependencies
222
223C++
224
225* For building code with `ctrl-space`, [`cxx`](https://github.com/xyproto/cxx) must be installed.
226* For formatting code with `ctrl-w`, `clang-format` must be installed.
227
228Go
229
230* For building code with `ctrl-space`, The `go` compiler must be installed.
231* For formatting code with `ctrl-w`, [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports) must be installed.
232
233Zig
234
235* For building and formatting Zig code, only the `zig` command is needed.
236
237V
238
239* For building and formatting V code, only the `v` command is needed.
240
241Rust
242
243* For building code with `ctrl-space`, `Cargo.toml` must exist and `cargo` must be installed.
244* For formatting code with `ctrl-w`, `rustfmt` must be installed.
245
246Haskell
247
248* For building the current file with `ctrl-space`, the `ghc` compiler must be installed.
249* For formatting code with `ctrl-w`, [`brittany`](https://github.com/lspitzner/brittany) must be installed.
250
251Python
252
253* `ctrl-space` only checks the syntax, without executing. This only requires `python` to be available.
254* For formatting the code with `ctrl-w`, `autopep8` must be installed.
255
256Crystal
257
258* For building and formatting Crystal code, only the `crystal` command is needed.
259
260Kotlin
261
262* For building code with `ctrl-space`, `kotlinc` must be installed. A `.jar` file is created if the compilation succeeded.
263* For formatting code with `ctrl-w`, `ktlint` must be installed.
264
265Java
266
267* For building code with `ctrl-space`, `javac` and `jar` must be installed. A `.jar` file is created if the compilation succeeded.
268* For formatting code with `ctrl-w`, `google-java-format` must be installed.
269
270Scala
271
272* For building code with `ctrl-space`, `scalac` and `jar` must be installed. A `.jar` file is created if the compilation succeeded.
273* The jar file can be executed with `java -jar main.jar`. Use `scalac -d main.jar MyFile.scala` if you want to produce a jar that can be executed with `scala main.jar`.
274* For formatting code with `ctrl-w`, `scalafmt` must be installed.
275
276D
277
278* For building code with `ctrl-space`, `gdc` must be available.
279
280JSON
281
282* The JSON formatter is built-in. Note that for some files it may reorganize items in an undesirable order, so don't save the file if the result is unexpected.
283
284fstab
285
286* For formatting `fstab` files (usually `/etc/fstab`) with `ctrl-w`, [`fstabfmt`](https://github.com/xyproto/fstabfmt) must be installed.
287
288JavaScript
289
290* For formatting JavaScript code with , `prettier` must be installed.
291
292## A note on Java and Scala
293
294Since `kotlinc $filename -include-runtime -d` builds to a `.jar`, I though I should do the same for Java. The idea is to easily compile a single or a small collection of `.java` files, where one of the file has a `main` function.
295
296If you know about an easier way to build a `.jar` file from `*.java`, without using something like gradle, please let me know by submitting a pull request. This is pretty verbose...
297
298```sh
299javaFiles=$(find . -type f -name '*.java')
300for f in $javaFiles; do
301 grep -q 'static void main' "$f" && mainJavaFile="$f"
302done
303className=$(grep -oP '(?<=class )[A-Z]+[a-z,A-Z,0-9]*' "$mainJavaFile" | head -1)
304packageName=$(grep -oP '(?<=package )[a-z,A-Z,0-9,.]*' "$mainJavaFile" | head -1)
305if [[ $packageName != "" ]]; then
306 packageName="$packageName."
307fi
308mkdir -p _o_build/META-INF
309javac -d _o_build $javaFiles
310cd _o_build
311echo "Main-Class: $packageName$className" > META-INF/MANIFEST.MF
312classFiles=$(find . -type f -name '*.class')
313jar cmf META-INF/MANIFEST.MF ../main.jar $classFiles
314cd ..
315rm -rf _o_build
316```
317
318For Scala, I'm using this code, to produce a `main.jar` file that can be run directly with `java -jar main.jar`:
319
320```sh
321#!/bin/sh
322scalaFiles=$(find . -type f -name '*.scala')
323for f in $scalaFiles; do
324 grep -q 'def main' "$f" && mainScalaFile="$f"
325 grep -q ' extends App ' "$f" && mainScalaFile="$f"
326done
327objectName=$(grep -oP '(?<=object )[A-Z]+[a-z,A-Z,0-9]*' "$mainScalaFile" | head -1);
328packageName=$(grep -oP '(?<=package )[a-z,A-Z,0-9,.]*' "$mainScalaFile" | head -1);
329if [[ $packageName != "" ]]; then
330 packageName="$packageName."
331fi
332mkdir -p _o_build/META-INF
333scalac -d _o_build $scalaFiles
334cd _o_build
335echo -e "Main-Class: $packageName$objectName\nClass-Path: /usr/share/scala/lib/scala-library.jar" > META-INF/MANIFEST.MF
336classFiles=$(find . -type f -name '*.class')
337jar cmf META-INF/MANIFEST.MF ../main.jar $classFiles
338cd ..
339rm -rf _o_build
340```
341
342If `/usr/share/scala/lib/scala-library.jar` is not found `scalac -d run_with_scala.jar` is used instead. This file can only be run with the `scala` command.
343
344## List of optional runtime dependencies
345
346* `asciidoctor` - for writing man pages
347* `astyle` - for formatting C# code
348* `autopep8` - for formatting Python code
349* `brittany` - for formatting Haskell code
350* `cargo` - for compiling Rust
351* `clang` - for formatting C++ code with `clang-format`
352* `clojure` - for compiling Clojure
353* `crystal` - for compiling Crystal
354* [`cxx`](https://github.com/xyproto/cxx) - for compiling C++
355* `fpc` - for compiling Object Pascal
356* [`fstabfmt`](https://github.com/xyproto/fstabfmt) - for formatting `/etc/fstab`
357* `g++` - for compiling C++ code
358* `gdc` - for compiling D code
359* `ghc` - for compiling Haskell code
360* `go` - for compiling Go code
361* `go-tools` - for formatting Go code and handling imports with `goimports`
362* `google-java-format` - for formatting Java code
363* `java-environment` - for compiling Java code and creating `.jar` files with `javac` and `jar`
364* `kotlin` - for compiling Kotlin
365* `ktlint` - for formatting Kotlin code
366* `lua` - for compiling Lua to bytecode
367* `lua-format` - for formatting Lua code
368* `mlton` - for compiling Standard ML
369* `mono` - for compiling C# code
370* `ocaml` - for compiling and formatting OCaml code
371* `odin` - for compiling Odin
372* `pandoc` - for exporting Markdown to PDF
373* `prettier` - for formatting JavaScript, TypeScript and CSS
374* `python` - for compiling Python to bytecode
375* `rustc` - for compiling Rust
376* `rustfmt` - for formatting Rust
377* `scala` - for compiling Scala
378* `sdoc` - for writing man pages
379* `tidy` - for formatting HTML
380* `v` - for compiling and formatting V code
381* `zig` - for compiling and formatting Zig code
382
383## Size
384
385* The `o` executable is only **989k** when built with GCC 11.1.0 (for 64-bit Linux) and compressed with `upx`.
386* This isn't as small as [e3](https://sites.google.com/site/e3editor/), an editor written in assembly (which is **234k**), but it's reasonably lean.
387
388One way of building with `gccgo` and `upx`:
389
390 go build -mod=vendor -gccgoflags '-Os -s' && upx o
391
392It's **9.5M** when built with Go 1.17 and no particular build flags are given.
393
394## Jumping to a specific line when opening a file
395
396These four ways of opening `file.txt` at line `7` are supported:
397
398* `o file.txt 7`
399* `o file.txt +7`
400* `o file.txt:7`
401* `o file.txt+7`
402
403This also means that filenames containing `+` or `:`, and then followed by a number, are not supported.
404
405## Spinner
406
407When loading files that are large or from a slow disk, an animated spinner will appear. The loading operation can be interrupted by pressing `esc`, `q` or `ctrl-q`.
408
409
410
411## Find and open
412
413This shell function works in `zsh` and `bash` and may be useful for both searching for and opening a file at the given line number (works best if there is only one matching file, if not it will open several files in succession):
414
415```bash
416fo() { find . -type f -wholename "*$1" -exec /usr/bin/o {} $2 \;; }
417```
418
419Take care not to use too general terms.
420
421Example use:
422
423```sh
424fo somefile.cpp 123
425```
426
427## Pandoc
428
429When using `pandoc` to export from Markdown to PDF:
430
431* If the `PAPERSIZE` environment variable is set to ie. `a4` or `letter`, it will be respected when exporting from Markdown to PDF using pandoc, at the press of `ctrl-space`.
432* The `--pdf-engine=xelatex` and `--listings` flags are used, so `xelatex` and the `listings` package needs to be available. A standard installation of LaTeX and Pandoc should provide both.
433* `Export to PDF with pandoc` will only appear on the `ctrl-o` menu when editing a Markdown file and `pandoc` is installed.
434
435## Easter egg
436
437Try the Konami code while in the `ctrl-o` menu to start a silly little game about feeding creatures with pellets before they are eaten.
438
439## Recommended symlinks
440
441* For starting `o` with the light theme: `ln -sf /usr/bin/o /usr/bin/lighted`.
442* For starting `o` with the red/black theme: `ln -sf /usr/bin/o /usr/bin/redblack`.
443
444## The GUI frontend `ko`
445
446Build:
447
448 make
449
450Install:
451
452 make gui-install
453
454## Terminal settings
455
456### Konsole
457
458* Untick the `Flow control` option in the profile settings, to ensure that `ctrl-s` will never freeze the terminal.
459
460## Stars
461
462[](https://starchart.cc/xyproto/o)
463
464## General info
465
466* Version: 2.46.0
467* License: 3-clause BSD
468* Author: Alexander F. Rødseth <xyproto@archlinux.org>
469
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}