Commands and Sigil

How Shale reads a line

Shale decides what a line is from its first character that isn't whitespace, such as a space or a tab:

  • A line that starts with ( is a Sigil form. Shale evaluates it and doesn't print its value, though anything the form writes, such as with display, still appears.

  • A line that starts with a comma runs a comma command such as ,last, or, when what follows isn't a command name, evaluates one Sigil expression and prints its value.

  • Any other line is a command line, read much as Bash reads it.

There's no mode to switch and nothing to guess. When Shale reads a line the way you didn't mean, it says which way it read it and how to get the other:

shale
~/project $ (echo hi)
shale: unbound variable 'echo'
shale: this line was read as Sigil; for a command line, remove the parentheses, or use ($ make cwd: "build")

✗ exited 1 · 0s

~/project $ string-upcase hello
shale: could not run string-upcase (not-found)
shale: this line was read as a command; put a Sigil form in parentheses

✗ exited 127 · 0s

Command lines

A command line is words separated by spaces. Single quotes keep text exactly as written, double quotes keep spaces but still expand variables, and a backslash keeps the next character as it is.

shale
~/project $ echo "home is $HOME" 'not $HOME'
home is /home/ada not $HOME

~/project $ echo "${USER}'s files"
ada's files

These work much as they do in Bash:

  • variables, written $NAME or ${NAME@}, and ~ for your home directory at the start of a word;

  • command output in place of a word, written $(command);

  • globs, with *, ?, [...] and @{a,b@}. Unlike Bash, @{a,b@} matches existing files only, and matches in the current directory start with ./;

  • pipes with |, and &&, || and ; to run commands one after another;

  • & at the end to run a command in the background;

  • redirects for standard input, output and error, written with <, >, >> and 2>&1;

  • # to start a comment.

shale
~/project $ ls src | wc -l > count.txt && cat count.txt
2

~/project $ echo there are $(ls src | wc -l) source files
there are 2 source files

A glob that matches nothing is an error, so a typo can't turn into a command that runs on the literal pattern:

shale
~/project $ ls *.zip
shale: no paths match *.zip

✗ exited 1 · 0s

For loops and conditions, use Sigil. Shale refuses the control words of the POSIX shell language, such as if, for and while, and there are no here-documents. Redirects reach standard input, output and error only.

Sigil in a command line

A comma at the start of a word puts a Sigil value into the command line. ,name uses a variable's value, ,(expression) the value of an expression, and ,@list splices in each item of a list as its own word. They work the way the comma works in a Sigil script that runs commands, so a line you got working at the prompt pastes into a script.

shale
~/project $ (define sources (glob "src/*.sgl"))

~/project $ wc -l ,@sources | tail -1
 3 total

~/project $ echo ,(length sources) files, ,(string-upcase "loud")
2 files, LOUD

A string goes in as one word, spaces and all, so you never quote it again. A number or a symbol goes in as it would print. Any other value, such as a list, is an error unless you splice it with ,@@.

Sigil at the prompt

Your Sigil session lasts as long as Shale does. Definitions stay, and you can import any library a Sigil script can import. The session starts with (sigil fs), (sigil io), (sigil process) and (sigil shell) imported, so files, processes and $ for running commands are ready to use.

shale
~/project $ (define notes (read-file-string "notes.txt"))

~/project $ ,(string-length notes)
26

When a Sigil form fails, Shale prints the error and the line gets a result line, like a failed command. To see the stack trace, type ,debug.