title | all_docs_url | body_css_class | default_highlighter | preserve_anchor_case |
---|---|---|---|---|
Front End (Oils Reference) |
.. |
width40 |
oils-sh |
true |
Oils Reference — Chapter Front End
This chapter describes command line usage and lexing.
(in progress)
bin/oils-for-unix is an executable that contains OSH, YSH, and more.
Usage: oils-for-unix MAIN_NAME ARG*
MAIN_NAME ARG*
It behaves like busybox. The command name can be passed as the first argument:
oils-for-unix ysh -c 'echo hi'
More commonly, it's invoked through a symlink like 'ysh', which causes it to
behave like that command:
ysh -c 'echo hi'
bin/osh is compatible with POSIX shell, bash, and other shells.
Usage: osh FLAG* SCRIPT ARG*
osh FLAG* -c COMMAND ARG*
osh FLAG*
The command line accepted by `bin/osh` is compatible with /bin/sh and bash.
osh -c 'echo hi'
osh myscript.sh
echo 'echo hi' | osh
It also has a few enhancements:
osh -n -c 'hello' # pretty-print the AST
osh --ast-format text -n -c 'hello' # print it full
osh accepts POSIX sh flags, with these additions:
-n parse the program but don't execute it. Print the AST.
--ast-format what format the AST should be in
bin/ysh is the shell with data tYpes, influenced by pYthon, JavaScript, ...
Usage: ysh FLAG* SCRIPT ARG*
ysh FLAG* -c COMMAND ARG*
ysh FLAG*
`bin/ysh` is the same as `bin/osh` with a the `ysh:all` option group set. So
`bin/ysh` also accepts shell flags.
ysh -c 'echo hi'
ysh myscript.ysh
echo 'echo hi' | ysh
If the --rcfile flag is specified, that file will be executed on startup. Otherwise:
bin/osh
runs~/.config/oils/oshrc
bin/ysh
runs~/.config/oils/yshrc
Pass --rcfile /dev/null or --norc to disable the startup file.
If the --rcdir flag is specified, files in that folder will be executed on startup. Otherwise:
bin/osh
runs everything in~/.config/oils/oshrc.d/
bin/ysh
runs everything in~/.config/oils/yshrc.d/
Pass --norc to disable the startup directory.
History is read?
Oils is often built with GNU readline, which recognizes many terminal commands for editing input.
A useful option is set -o vi
, which tells GNU readline to accept vi keys.
The meaning of exit codes is a convention, and generally follows one of two paradigms.
0
for success.1
for runtime error- Example:
echo foo > out.txt
andout.txt
can't be opened. - Example:
fg
and there's not job to put in the foreground.
- Example:
2
for parse error. This means that we didn't attempt to do anything, rather than doing something, then it fails.- Example: A language parse error, like
echo $(
. - Example: Builtin usage error, like
read -z
.
- Example: A language parse error, like
3
for runtime expression errors. The expression language is new to Oils, so its errors have a new exit code.- Example: divide by zero
42 / 0
- Example: index out of range
a[1000]
- Example: divide by zero
POSIX exit codes:
126
for permission denied when running a command (errno EACCES
)127
for command not found
Hint: Error checking often looks like this:
try {
ls /bad
}
if (_status !== 0) {
echo 'failed'
}
0
for true1
for false.- Example:
test -f foo
andfoo
isn't a file.
- Example:
2
for error (usage error, parse error, etc.)- Example:
test -q
: the flag isn't accepted.
- Example:
Hint: The boolstatus
builtin ensures that false and error aren't confused:
if boolstatus test -f foo {
echo 'foo exists'
}
See YSH Fixes Shell's Error Handling for more detail.
A comment starts with #
and goes until the end of the line.
echo hi # print a greeting
A backslash \
at the end of a line continues the line without executing it:
ls /usr/bin \
/usr/lib \
~/src # A single command split over three lines
In most places, Oils uses the same definition of ASCII whitespace as JSON. That is, any of these 4 bytes are considered whitespace:
[ \t\r\n] # space, tab, carriage return, newline
Sometimes newlines are significant, e.g. after shell commands. Then the set of whitespace characters is:
[ \t\r]
(We don't handle the Windows \r\n
sequence in a special way. Instead, \r
is often treated like space and tab.)
Examples:
- Inside shell arithmetic
$(( 1 + 2 ))
, ASCII whitespace is ignored. - Inside YSH expressions
42 + a[i] * f(x)
, ASCII whitespace is ignored.
Exceptions:
- Carriage return
\r
may not always be whitespace.- It can appear in an unquoted shell words, a rule that all POSIX shells follow.
- The default
$IFS
doesn't include\r
.
- YSH
trim()
functions also respect Unicode space.
The ASCII control chars have byte values 0x00
to 0x1F
. This set includes 3
whitespace chars:
- tab -
\t
aka0x09
- newline -
\n
aka0x0a
- carriage return -
\r
aka0x0d
(It doesn't include the space - 0x20
.)
General rules:
- In J8 data languages, control chars other than whitespace are illegal. This is consistent with the JSON spec.
- In source code, control chars are allowed (but discouraged).
- For example, in OSH, we don't check for control chars unquoted words words or string literals. They are treated like printable chars.
- TODO: YSH should only allow printable characters, which implies valid UTF-8.
Note about NUL
aka 0x00
:
- The NUL byte is often used to terminate buffers, i.e. as a sentinel for
re2c lexing. This means that data after the NUL will be
ignored.
- J8 data input is read all at once, i.e. not split into lines. So everything after the first NUL may be ignored.
- Shell source code is split into lines.
Doc comments look like this:
proc deploy {
### Deploy the app
echo hi
}
The ... prefix starts a single command over multiple lines. It allows writing long commands without \ continuation lines, and the resulting limitations on where you can put comments.
Single command example:
... chromium-browser
# comment on its own line
--no-proxy-server
--incognito # comment to the right
;
Long pipelines and and-or chains:
... find .
# exclude tests
| grep -v '_test.py'
| xargs wc -l
| sort -n
;
... ls /
&& ls /bin
&& ls /lib
|| error "oops"
;
Print files embedded in the oils-for-unix
binary to stdout. Example:
osh --tool cat-em stdlib/math.ysh stdlib/other.ysh
The reference is divided in to "chapters", each of which has its own table of
contents. Type:
help osh-$CHAPTER
Where $CHAPTER is one of:
front-end
command-lang
osh-assign
word-lang
mini-lang
builtin-cmd
option
special-var
plugin
Example:
help osh-word-lang
The reference is divided in to "chapters", each of which has its own table of
contents. Type:
help ysh-$CHAPTER
Where $CHAPTER is one of:
front-end
command-lang
expr-lang
word-lang
builtin-cmd
option
special-var
type-method
builtin-func
Example:
help ysh-expr-lang