Builtins and comma commands

Builtins

A builtin is a command Shale runs itself instead of starting a program, because it changes Shale's own state: its directory, its environment or its jobs. When a builtin and a program have the same name, the builtin wins.

A builtin has to be a command of its own. You can't pipe into or out of one, redirect it, start it with & or put NAME=value in front of it; Shale says so if you try. &&, || and ; work, since each side is still a command of its own.

Builtin

What it does

cd [DIRECTORY]

Change to DIRECTORY, or to your home directory with no argument. cd - goes back to the previous directory and prints its name. Shale sets both PWD and OLDPWD to match.

export [NAME=VALUE ...]

Set environment variables for Shale and every program it starts. With no arguments, print the whole environment, one export line per variable.

unset NAME ...

Remove environment variables.

jobs

List the jobs Shale is running, with their number, state and command line.

fg [%N]

Bring job N to the foreground, or the newest job with no argument. A stopped job continues.

bg [%N]

Let stopped job N continue in the background, or the newest job with no argument.

kill %N

Ask job N to stop by sending it SIGTERM. A stopped job is continued so it can receive the signal.

exit [STATUS]

Leave Shale with STATUS, from 0 to 255, or with the status of the last command when you don't give one.

To see the job builtins in a session, read Jobs and outcomes.

Comma commands

A line that starts with a comma and one of these names runs the command instead of evaluating Sigil. Three are Shale's own; the rest come from Sigil's REPL, and ,help lists them.

Command

What it does

,last

Show the outcome of the last command you ran in the foreground: the program's name, or pipe for a pipeline, how it ended and how long it took.

,reload

Read your configuration again now, instead of waiting for the next prompt.

,debug

Inspect the last Sigil error, at a debug> prompt of its own.

,doc NAME, ,d

Show the documentation for a Sigil procedure or variable.

,search QUERY, ,s

Search Sigil's procedures by name or description.

,use (LIBRARY)

Import a library into the session, such as ,use (sigil json).

,module (NAME), ,m

Switch the session to another module, such as ,m (sigil io).

,load FILE

Load a Sigil file into the session.

,help, ,h

List the commands that come from Sigil's REPL.

,exit, ,quit, ,q

Leave Shale, like exit.