Oils Reference — Chapter Front End

This chapter describes command line usage and lexing.

(in progress)

In This Chapter

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:

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:

Pass --norc to disable the startup directory.

startup

History is read?

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

POSIX exit codes:

Hint: Error checking often looks like this:

try {
  ls /bad
}
if (_error.code !== 0) {
  echo 'failed'
}

The Boolean Paradigm

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:

Exceptions:

ascii-control-chars

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

(It doesn't include the space - 0x20.)

General rules:

Note about NUL aka 0x00:

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

Generated on Mon, 22 Jul 2024 06:36:28 +0000