The language¶
Everything you type into nish is Nim, more precisely NimScript, the part of Nim the compiler's VM can run. Before a line reaches the VM, nish checks whether it is a shell command. If it is, nish rewrites it into a call that runs the command, so ls -la becomes run("ls -la").
Commands or Nim?¶
A line is a command when its first word:
- is not a Nim keyword (
for,let,procand so on), - is not a Nim name in scope (a proc, variable, type or constant, from your session or an imported module), and
- names a program on your
PATH, an alias, or a path to an executable like./build.sh.
Nim matches names style insensitively (sayHi calls a proc declared as say_hi), and nish does too, with one exception: when a name is also a program, only the exact declared spelling makes it Nim. Nim itself would accept mkdir for NimScript's mkDir, but at a shell prompt mkdir means the program, so that's what nish runs. Spelled mkDir, it's the Nim proc.
So Nim wins whenever a name means something in Nim:
| Input | Result |
|---|---|
ls -la |
runs ls |
echo "hi" |
Nim's echo |
true |
the Nim value true, which is an error on its own line |
ls = 3 |
Nim (an assignment), even though ls is a program |
ls(x), ls.len |
Nim, because of the ( or . right after the name |
Three things override the rule:
- Shell-only operators. A line containing
&&,||,>>or>&outside quotes and comments is a command, whatever its first word is, because those are never Nim.false || printf "fallback\n"runs both programs. - A leading
!. It makes the whole line a command:!echo x | wc -l. Use it for lines whose first word is a Nim name, when the line only uses operators that Nim has too, like|,>and<. - Plain Nim.
run"echo x | wc -l"is an ordinary Nim call, so it works anywhere.
A line is split at ; (outside quotes and brackets) first, and each part is classified on its own, since ; separates statements in Nim too. ls; echo "done" runs ls and then Nim's echo.
Commands inside Nim code¶
Commands work anywhere a statement does:
import std/strutils
proc backup(file: string) =
cp @(file) @(file & ".bak")
for f in listFiles("."):
if f.endsWith(".nim"):
backup(f)
nish follows the structure of the code to stay out of the way of Nim:
- Lines inside
type,const,letandvarsections, inside open brackets, continuing an expression, or inside#[ ]#comments are never commands. - Names declared earlier in the same input count as Nim: a proc's parameters and
result, loop variables, and names fromletandvar. A parameter calledtimestays a parameter even thoughtimeis a program.
When nothing matches¶
A line shaped like a command whose first word is neither Nim nor a program gets nish: foo: command not found, and lastStatus becomes 127. Anything else goes to the compiler, which reports errors as usual.
Command syntax¶
Inside a command line, the syntax is a familiar subset of POSIX shells.
- Pipes and redirects
a | b,> file,>> file,< file,2> file,2>&1. A digit right before>or<picks the descriptor.- Chaining
a && brunsbifasucceeded,a || brunsbif it failed,a; bruns both.- Background
a &startsaas a background job.- Quoting
'single quotes'are literal."double quotes"expand$VARand allow\",\\and\$. A backslash outside quotes escapes the next character.- Expansion
- In unquoted words: globs (
*.nim,file?.txt,[ab].txt),~at the start of a word, and$VARor${VAR}. A glob that matches nothing stays as written. - Comments
- A
#that starts a word begins a comment. Inside a word (a#b) it is an ordinary character.
There is no $(...) command substitution and no if or while in command syntax: Nim does those jobs. Use sh"..." for output and Nim's own control flow.
Nim values in commands¶
@(expr) puts the value of a Nim expression into a command line:
let name = "notes.txt"
let flags = @["-l", "-a"]
ls @(flags) @(name) # runs: ls -l -a notes.txt
cp @(name) "backup-@(name)"
- A string, number,
boolorcharbecomes one argument, even if it contains spaces. - A sequence or array becomes one argument per element, and an empty one becomes none.
- Inside a word or inside double quotes, the value is inserted into the text and must be a single value.
@(inside single quotes, or written as\@(, is literal text.
Output and status¶
sh"..." runs a command line and returns what it wrote to standard output, without trailing newlines:
let branch = sh"git branch --show-current"
let files = sh"ls src".splitLines # needs: import std/strutils
lastStatus holds the exit status of the last command. A failed input sets it to 1, and a missing command to 127:
run also returns the status, so if run("test -d build") != 0: works too. Both run and sh take @(...) values as extra arguments when you call them directly: run("ls \0", dir), where \0 marks where each value goes.
Builtins¶
A few commands are handled by nish itself:
cd [dir]- Changes the directory; without an argument, to your home directory.
cd "/tmp"andcd(dir)are the Nim call, which also works. exit [status]- Quits the shell, with
lastStatusif no status is given. jobs,fg [n],bg [n]- Manage jobs.
fg %2andfg 2both mean job 2.
Jobs¶
Each pipeline is a job. At the prompt, the job that runs in the foreground owns the terminal:
- Ctrl-C stops the foreground job. The shell itself keeps running.
- Ctrl-Z suspends it and returns to the prompt:
[1] Stopped sleep 100. cmd &starts a job in the background and prints its number and process ID. When it finishes, nish says so before the next prompt.jobslists the background and stopped jobs,fgbrings one back to the foreground, andbglets a stopped one continue in the background.
A command captured with sh"..." can't be suspended, since its output could never arrive. Ctrl-C still stops it.
Scripts, -c and piped input have no job control, as in other shells: jobs share the shell's process group, and Ctrl-C stops the whole script.
The NimScript API¶
The API that .nims files have is built in too: cd, getEnv, putEnv, existsEnv, fileExists, dirExists, listFiles, listDirs, mkDir, rmFile, cpFile, mvFile, exec, gorgeEx and the rest of system/nimscript. nish's own additions are in the API reference.