Customizing¶
nish is configured in Nim. When an interactive session starts, nish runs ~/.config/nish/init.nims (or $XDG_CONFIG_HOME/nish/init.nims), and everything in it works the same as typing it at the prompt. Errors in it are reported with its file name and line, and the shell starts anyway.
import std/strutils
alias "ll", "ls -la"
alias "gs", "git status"
prompt = proc(): string =
let branch = sh"git branch --show-current 2> /dev/null"
"\e[1;34m" & tildePath(getCurrentDir()) & "\e[0m" &
(if branch.len > 0: " (" & branch & ")" else: "") & "> "
onDirChange.add proc(dir: string) =
ls
completers.add proc(line, word: string): seq[string] =
if line.startsWith("git ") and line.count(' ') == 1:
for sub in ["status", "commit", "push", "pull", "log"]:
if sub.startsWith(word):
result.add sub
Start nish with --no-init to skip the file.
Aliases¶
alias name, line makes name stand for the start of a command line:
An alias can refer to itself, as ls does here, and to other aliases. Its name counts as a command, so ll works even though there is no ll program.
The prompt¶
prompt is a proc that returns the prompt string, called before every input. continuationPrompt is the one shown on the following lines of a multi-line input. Both may use color codes: the editor leaves them out when it measures the line.
tildePath(path) writes your home directory as ~, which is handy for prompts.
Hooks¶
Hooks are procs that nish calls at certain moments. They run for input typed at the prompt, not for scripts.
onPreCommand: seq[proc(line: string)]- Before each input is evaluated, with the input.
onCommandDone: seq[proc(line: string, status: int)]- After each input, with its
lastStatus. onDirChange: seq[proc(dir: string)]- Before a prompt, when the current directory has changed.
completers: seq[Completer]- Asked when you press Tab, see Completion.
Add to them with .add. A hook that raises an error doesn't take the shell down: nish reports the error and carries on with a fallback, such as a plain nish> prompt.
Completion¶
Tab completes the word before the cursor. The default completer offers programs, Nim names in scope and builtins for the first word of a line, and file names after it (~/ included). If there are several candidates, Tab completes their common start and then lists them.
A completer is a proc(line, word: string): seq[string]: it gets the whole line up to the cursor and the word being completed, and returns replacements for that word. Every completer in completers is asked, and their answers are combined.
Key bindings¶
bindKey binds a key to a Nim proc that runs instead of the editor's own action:
bindKey "ctrl-t", proc() =
editorSetText("time " & editorText(), editorCursor() + 5)
bindKey "alt-g", proc() =
editorInsert(sh"git branch --show-current")
Inside the proc, editorText() and editorCursor() read the input being edited, and editorSetText and editorInsert change it. Key names look like ctrl-t, alt-x, up, ctrl-right, pageup and delete. Printable characters can't be bound.
The line editor¶
| Keys | Action |
|---|---|
| Enter | Accept the input, or add a line if a block is still open |
| Ctrl-J, Alt-Enter | Add a line |
| Tab | Complete |
| Up, Down | Move between lines of the input, then through the history |
| Ctrl-P, Ctrl-N | Previous and next history entry |
| Ctrl-R | Search the history; Ctrl-R again for older matches, Enter to take one, Ctrl-G to cancel |
| Left, Right, Ctrl-B, Ctrl-F | Move by character |
| Alt-B, Alt-F, Ctrl-Left, Ctrl-Right | Move by word |
| Home, End, Ctrl-A, Ctrl-E | Start and end of the line |
| Backspace, Delete, Ctrl-D | Delete a character; Ctrl-D on an empty input quits |
| Ctrl-W, Alt-Backspace | Delete the word before the cursor |
| Alt-D | Delete the word after the cursor |
| Ctrl-K, Ctrl-U | Delete to the end or the start of the line |
| Ctrl-Y | Insert the text deleted last |
| Ctrl-L | Clear the screen |
| Ctrl-C | Discard the input |
A pasted block is inserted as a whole and runs only when you press Enter.
Alt on macOS
macOS terminals type special characters with Option by default, so the Alt keys don't reach nish. In Terminal, turn on "Use Option as Meta key" in the profile's keyboard settings; in iTerm2, set the Option key to "Esc+".
History is saved after every input, in history in nish's data directory, and the last 10,000 entries are kept. The data directory is ~/.local/share/nish on Linux and ~/Library/Application Support/nish on macOS, or $XDG_DATA_HOME/nish when that is set.
Plugins¶
A plugin is a Nim module. nish looks for modules in plugins/ under ~/.config/nish and under its data directory (see above), directly or one directory down, so a cloned repository works as it is. Import a plugin from init.nims:
A plugin uses the same API as init.nims. It imports nishapi to reach it:
# ~/.config/nish/plugins/gitprompt/gitprompt.nim
import nishapi
proc branch(): string =
sh"git branch --show-current 2> /dev/null"
prompt = proc(): string =
let b = branch()
tildePath(getCurrentDir()) & (if b.len > 0: " [" & b & "]" else: "") & "> "
Plugins run in the VM like everything else, so they can't call C libraries. Anything beyond NimScript has to come from nish's API.