Why Sponsor Oils? | source | all docs for version 0.20.0 | all versions | oilshell.org

Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

Front End

This chapter in the Oils Reference describes command line usage and lexing.

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*

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

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*

`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

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

History is read?

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 (_status !== 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

doc-comment

Doc comments look like this:

proc deploy {   
  ### Deploy the app
  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

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:

    front-end
    command-lang
    osh-assign
    word-lang
    mini-lang
    builtin-cmd
    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:

    front-end
    command-lang
    expr-lang
    word-lang
    builtin-cmd
    option
    special-var
    type-method
    builtin-func

Example:

    help ysh-expr-lang