Why Sponsor Oils? | source | all docs for version 0.32.0 | all versions | oils.pub

This chapter describes command line usage and lexing.

(in progress)

Command Line Usage

oils-usage

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'

osh-usage

bin/osh is compatible with POSIX shell, bash, and other shells.

Usage:
   osh FLAG* SCRIPT ARG*
   osh FLAG* -c COMMAND ARG*
   osh FLAG*

Examples:
    osh -c 'echo hi'
    osh myscript.sh
    echo 'echo hi' | osh

ysh-usage

bin/ysh is the shell with data tYpes, influenced by pYthon, JavaScript, ...

Usage:
    ysh FLAG* SCRIPT ARG*
    ysh FLAG* -c COMMAND ARG*
    ysh FLAG*

Examples:
    ysh -c 'echo hi'
    ysh myscript.ysh
    echo 'echo hi' | ysh

Note that bin/ysh is the same as bin/osh with the ysh:all option group set:
    osh -o ysh:all -c 'echo hi'  # Same as YSH

shell-flags

osh and ysh accept standard POSIX shell flags, like:

    bin/osh -o errexit -c 'false'
    bin/ysh -n myfile.ysh
    bin/ysh +o errexit -c 'false; echo ok'

They also accept these flags:

    --eval FILE
        Evaluate the given file, similar to the 'source' builtin.  Specify it
        multiple times to run multiple files.  If the errexit option is on
        (e.g. in YSH), then the shell stops when $? is non-zero after
        evaluating a file.

    --eval-pure FILE
        Like --eval, but disallow I/O (known as "pure mode").

    --location-str
        Use this string to display error messages.
        See 'help sourceCode' for an example.

    --location-start-line
        Use this line number offset to display error messages.

    --tool            Run a tool instead of the shell (cat-em|syntax-tree)
    -n                Parse the program but don't execute it.  Print the AST.
    --ast-format FMT  The format for the AST (text|text-abbrev)

Examples:

    ysh --eval one.ysh --eval two.ysh -c 'echo hi'  # Run 2 files first
    osh -n -c 'hello'                               # pretty-print the AST
    ysh --ast-format text -n -c 'hello'             # in unabridged format

config

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.

startup

TODO:

1. History is read
2. ...

line-editing

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.

exit-codes

The meaning of exit codes is a convention, and generally follows one of two paradigms.

The Success / Failure Paradigm

• 0 for success.
• 1 for runtime error
  • Example: echo foo > out.txt and out.txt can't be opened.
  • Example: fg and there's not job to put in the foreground.
• 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.
• 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]

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 (_error.code !== 0) {
  echo 'failed'
}

The Boolean Paradigm

• 0 for true
• 1 for false.
  • Example: test -f foo and foo isn't a file.
• 2 for error (usage error, parse error, etc.)
  • Example: test -q: the flag isn't accepted.

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.

Lexing

comment

A comment starts with # and goes until the end of the line.

echo hi  # print a greeting

line-continuation

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

ascii-whitespace

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.

ascii-control-chars

The ASCII control chars have byte values 0x00 to 0x1F. This set includes 3 whitespace chars:

• tab - \t aka 0x09
• newline - \n aka 0x0a
• carriage return - \r aka 0x0d

(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-comment

Doc comments can be attached to procs or shell functions:

proc deploy {   
  ### Deploy the app
  echo hi
}

my_sh_function() {
  ### This also works
  echo hi
}

multiline-command

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"
 ;

Tools

cat-em

Print files embedded in the oils-for-unix binary to stdout. Example:

osh --tool cat-em stdlib/math.ysh stdlib/other.ysh

syntax-tree

Print the syntax tree in a debug format.

osh --tool syntax-tree stdlib/ysh/math.ysh

The -n flag is a shortcut:

osh -n stdlib/ysh/math.ysh

Help Chapters

osh-chapters

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:

    type-method
    builtin-cmd
    stdlib
    front-end
    cmd-lang
    osh-assign
    word-lang
    mini-lang
    option
    special-var
    plugin

Example:

    help osh-word-lang

ysh-chapters

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:

    type-method
    builtin-func
    builtin-cmd
    stdlib
    front-end
    cmd-lang
    ysh-cmd
    expr-lang
    word-lang
    option
    special-var
    plugin

Example:

    help ysh-expr-lang
    help ysh-ysh-cmd    # may change