NOTE: This document is a work in progress!

OSH Quick Reference

Version 0.7.pre2

- Below is a list of topics, organized into [Sections].
- The X prefix means "unimplemented".  Oil features are all unimplemented!
- HTML version: https://www.oilshell.org/release/0.7.pre2/doc/osh-quick-ref.html

INTRO
  [Overview]      overview   osh-vs-oil   command-vs-expr
  [Usage]         bundle-usage   osh-usage   oil-usage   config   startup
                  line-editing   prompt
  [Lexing]        comments #   line-continuation \
  [Oil Lexing]    single-command %   docstring?

COMMAND LANGUAGE
  [Commands]      simple-command   semicolon ;
  [Conditional]   case   if   true   false   colon :
                  bang !   and &&   or ||   dbracket [[
  [Iteration]     while   until   for   for-expr-sh ((
  [Control Flow]  break   continue   return   exit
  [Grouping]      function   block {   subshell (
  [Concurrency]   pipe   |   X |&
                  ampersand &
  [Redirects]     redir-file  >  >>  >|  <  <>   X &>
                  redir-desc  >&  <&
                  here-doc    <<  <<-  <<<
  [Other]         dparen ((   time   X coproc   X select

OIL COMMAND LANGUAGE

X [Conditional]   match-with   match-case   if-expr (
X [Iteration]     for-expr (   while-expr (
X [Grouping]      proc   func   lazy   pure   do {   shell {  
X [Context]       with-cd   with-redir   with-env   with-vars   with-file
                  with-logger
X [Concurrency]   fork
X [Redirects]     multiline-string '''_"""   file-descriptor !0

ASSIGNING VARIABLES
  [Keywords]      local   readonly   export   unset   shift
                  declare   typeset   X let
  [Operators]     assign        str='xyz'
                  append        str+='abc'
  [Compound Data] array         array=(a b c)   array[1]=B   "${a[@]}"
                  assoc         declare -A assoc=([a]=1 [b]=2)

OIL VARIABLES

X [Keywords]      var   const   set   setglobal
                  setargv   setenv   setoption
X [Operators]     pass ->   rhs-assign =>
X [Compound Data] oil-array     array = [a b c]
                  splice        a = [a @middle b]
X [Data Types]    Str   Int   Float   Bool   Array<>   Map<>    Table
                  (JSON compat: Null, List)

WORD LANGUAGE
  [Quotes]        quotes        'abc'  $'\n'  "$var"
  [Substitutions] com-sub       $(command)   `command`
                  var-sub       ${var}
                  arith-sub     $((1 + 2))  $[1 + 2]
                  tilde-sub     ~/src
                  proc-sub      diff <(sort L.txt) <(sort R.txt)
  [Special Vars]  special-vars  $@  $*  $#     $?  $-     $$  $!
  [Var Ops]       op-test       ${x:-default}  
                  op-unary      ${x%%suffix}  etc.
                  op-str        ${x//y/z}
                  op-slice      ${a[@]:0:1}
                  op-format     ${x@P}
X [Oil Quotes]    c-string      c'1\t2\n'    c"1\t$two\n"
                  safe-subst    h"<p>$[name]</p>"

OTHER SHELL SUBLANGUAGES
  [Arithmetic]    arith-intro   Contexts where math is allowed
                  num-literals  0xFF  0755  etc.
                  math          1 + 2*3
                  arith-logical !a && b
                  bitwise       ~a ^ b
                  arith-assign  a *= 2
  [Boolean]       dbracket      [[ vs. the test builtin
                  bool-expr       [[ ! $x && $y || $z ]]
                                test ! $x -a $y -o $z
                  bool-infix    [[ $a -nt $b ]]  [[ $x == $y ]]
                  bool-path     [[ -d /etc ]]
                  bool-str      [[ -z '' ]]
                  bool-other    [[ -o errexit ]]
  [Patterns]      glob          *.py
                  extglob       @(*.py|*.sh)
                  regex         [[ foo =~ [a-z]+ ]]
  [Brace Expand]  braces        {alice,bob}@example.com
  [History]       histsub       !$  !!  !n

BUILTIN COMMANDS
  [I/O]           read   echo 
                  X readarray   X mapfile
  [Run Code]      source .   eval   trap
  [Set Options]   set   shopt
  [Working Dir]   cd   pwd   pushd   popd   dirs
  [Completion]    complete   compgen   compopt   compadjust
  [Shell Process] exec   X logout 
                  umask   X ulimit   X times
  [Child Process] jobs   wait   ampersand &
                  fg   X bg   X disown 
  [External]      test [   printf   getopts   X kill
  [Introspection] help   hash   type   X caller
  [Word Lookup]   command   builtin
  [Interactive]   alias   unalias   history   X fc   X bind
X [Unsupported]   enable

OIL BUILTINS
  [Compatibility] sh-builtin   sh-eval   sh-expr
  [I/O]           write   readline
  [External]      dirname   basename   env ?

SHELL OPTIONS
  [Errors]        nounset   errexit   pipefail
  [Globbing]      noglob   failglob   nullglob
  [Debugging]     xtrace   X verbose   X extdebug
  [Interactive]   emacs   vi
  [Other]         X noclobber
  [Parsing]       TODO
  [OSH Strict]    strict-argv   strict-array   strict-arith
                  X strict-backslash   strict-errexit   strict-control-flow
                  X strict-glob   strict-word-eval
  [OSH Sane]      SANE   X sane-no-word-split   X sane-glob
                  X sane-echo   X sane-read   X sane-eval   X sane-trap

ENVIRONMENT VARIABLES
  [Shell Options] SHELLOPTS   X BASHOPTS
  [Other Vars]    HOME   PATH   IFS

SPECIAL VARIABLES
X [Platform]      HOSTNAME   OSTYPE   BASH_VERSION   @BASH_VERSINFO
  [Call Stack]    @BASH_SOURCE   @FUNCNAME   @BASH_LINENO   
                  X BASH_ARGV   X BASH_ARGC
  [Tracing]       LINENO   SOURCE_NAME
  [Process State] X BASHPID   X PPID   UID   EUID   
X [Process Stack] BASH_SUBSHELL   SHLVL
X [Shell State]   BASH_CMDS   @DIRSTACK
  [Completion]    @COMP_WORDS   COMP_CWORD   COMP_LINE   COMP_POINT
                  COMP_WORDBREAKS   @COMPREPLY   X COMP_KEY   
                  X COMP_TYPE   COMP_ARGV

  [cd]            PWD   OLDPWD   X CDPATH
  [getopts]       OPTIND   OPTARG   X OPTERR
  [read]          REPLY   IFS
  [Functions]     X RANDOM   X SECONDS
  [Other]         BASH_REMATCH   @PIPESTATUS

PLUGINS AND HOOKS
  [Signals]       SIGTERM   X SIGINT   X SIGABRT   SIG...
  [Traps]         EXIT   X ERR   X DEBUG   X RETURN
  [Words]         PS1   X PS2   X PS3   PS4
  [Completion]    complete
  [Other]         X command_not_found   PROMPT_COMMAND

OIL EXTENSIONS

X [Static]        :use   :option
X [awk]           BEGIN   END   when
X [make]          rule
X [find]          fs
X [xargs]         each

OIL LIBRARIES

X [Compatibility] shExpr()   shEval()   
X [Builtin Procs] log   die
X [Builtin Funcs] join()   split()   strftime()
X [getopts]       ?
X [Testing]       ?
X [Data Formats]  json   csv   tsv2
X [Hash Functions]









Introduction


Overview


overview


OSH is a shell.


Usage


Usage of the Oil App Bundle

Usage: oil.ovm MAIN_NAME [ARG]...
       MAIN_NAME [ARG]...

oil.ovm behaves like busybox.  If it's invoked through a symlink, e.g. 'osh',
then it behaves like that binary.  Otherwise the binary name can be passed as
the first argument, e.g.:

    oil.ovm osh -c 'echo hi'

Usage of the OSH Binary

Usage: osh [OPTION]... SCRIPT [ARG]...
       osh [OPTION]... -c COMMAND [ARG]...

osh accepts POSIX sh flags, with the following differences:

  -n             only validate the syntax.  Also prints the AST.
  --show-ast     print the AST in addition to executing.
  --ast-format   what format the AST should be in


Usage of the Oil Binary

Usage: oil [OPTION]... SCRIPT [ARG]...
       oil [OPTION]... -c COMMAND [ARG]...

TODO: any changes?

Configuration Files


If the --rcfile flag is specified, osh and oil will source that on startup.

Otherwise they source ~/.config/oil/oshrc and ~/.config/oil/oilrc,
respectively.

To disable startup files, pass --rcfile /dev/null.

Shell Startup


Line Editing


Oil currently has support for building against GNU readline.

Customizing the Prompt String


OSH supports bash-compatible $PS1 syntax.

Lexing


Oil Lexing


The % Prefix Starts a Single Command Over Multiple Lines


This special lexer mode has several use cases:

Long command lines without trailing \

    % chromium-browser
      --no-proxy-server
      # comments allowed
      --incognito

Long pipelines or and-or chains without trailing \ 

    % find .
    # exclude tests
    | grep -v '_test.py'
    | xargs wc -l
    | sort -n

    %  ls /
    && ls /bin
    && ls /lib
    || error "oops"

Using {} for brace expansion, rather than the start of a block:

    % echo {alice,bob}@example.com
    %
    echo next   # blank line or bare % required to end the command

NOTE: This should be valid without % :

    ls *.[ch]

Using Oil syntax at an OSH shell prompt:

    $   echo hi >&2    # POSIX sh syntax
    $ % echo hi > !2   # Oil syntax

Command Language


The command language is specified by the POSIX shell grammar.

Commands


Simple Commands

Simple commands are separated by words:
    ls /

Redirects can also appear anywhere
    echo hi 1>&2

Semi-colon ;

;  -- separate statements

Conditional Constructs


case



if


true false colon :


bang !


and && or ||


dbracket [[

For conditionals.

Iteration Constructs


while until


for for-expr


Grouping Constructs


function


block


subshell


Concurrency


pipe


ampersand &


Redirects


redir-file


redir-desc


here-doc


Other Commands


dparen ((


time


coproc



Assigning Variables


Assignment Keywords


Assignment Operators


Compound Data Structures



Word Language


Quotes


Substitutions


Special Variables


Operations on Variables


Variable Formatting Operators


${x@P} evaluates x as a prompt string, e.g. the string that would be printed if
PS1=$x.

Other Shell Sublanguages


Arithmetic


Boolean


Patterns


Brace Expansion


Builtin Commands


OSH aims to have almost all of the builtins that bash does.  Here they are,
divided into sections.

I/O Builtins


These builtins take input and output.  They are often used with redirects[1].

[1] help redirects

read

Usage: read -p 

Or maybe get rid of #END -- it can just go until the next # command.  It's a
little bit like the spec tests honestly.  Can copy sh_specpy

Run Code

source .   eval

Set Shell Options

set   X shopt

Builtins - Working Dir

cd   pwd   pushd   popd   dirs

Completion


complete


Register completion policies for different commands.

compgen


Generate completion candidates inside a user-defined completion function.

compopt


Change completion options inside a user-defined completion function.

compadjust


Adjust COMP_ARGV according to specified delimiters, and optionally set
variables cur, prev, words (an array), and cword.  May also set 'split'.

This is an OSH extension that makes it easier to run the bash-completion
project.

Shell Process Control

exec   exit   X logout 
umask   X ulimit   X trap   X times

Child Process Control

jobs   wait   ampersand &
X fg   X bg   X disown 

Builtins That Introspect


help

Usage:
  help <topic>   -- show help on a given topic
  help toc       -- list help topics
  help osh-usage -- same as osh --help
  help oil-usage -- same as oil --help

View on the web: http://www.oilshell.org/$VERSION/doc/osh-quick-ref.html

hash


caller


type


Builtins That Are Like External Commands


External: bash has builtins that replace these external commands, but OSH
doesn't)

getopt


use /usr/bin/getopt

kill


bash accepts job control syntax

enable


Bash has this, but OSH won't implement it.

Shell Options



Parsing Options


Execution Options


Options Only in OSH


Environment Variables


Variables That Set Shell Options


SHELLOPTS


For the 'set' builtin.

BASHOPTS


For the 'shopt' builtin.

Other Variables


HOME


$HOME is used for:

1. ~ expansion 
2. ~ abbreviation in the UI (the dirs builtin, \W in $PS1).

Note: The shell doesn't set $HOME.  According to POSIX, the program that
invokes the login shell sets it based on /etc/passwd.

PATH


Used for finding executables to run.

IFS


Used for word splitting.

Special Variables


Platform


Call Stack


Tracing


Process State


Process Stack


Shell State


Completion


COMP_WORDS


An array of words, split by : and = for compatibility with bash.  New
completion scripts should use COMP_ARGV instead.

COMP_CWORD


Discouraged; for compatibility with bash.

COMP_LINE


Discouraged; for compatibility with bash.

COMP_POINT


Discouraged; for compatibility with bash.

COMPREPLY


User-defined completion functions should Fill this array with candidates.  It
is cleared on every completion request.

COMP_ARGV


An array of partial command arguments to complete.  Preferred over COMP_WORDS.
The compadjust builtin uses this variable.

Plugins and Hooks


Signals


Traps


Words


PS1


First line of a prompt.

PS2


Second line of a prompt.

PS3


For the 'select' builtin (unimplemented).

PS4


For 'set -o xtrace'.  The leading character is special.

Oil Extensions


Oil Libraries


Builtins Procs


Builtins Funcs


strftime()


Useful for logging callbacks.  NOTE: bash has this with the obscure 
printf '%(...)' syntax.

Generated on Wed Jul 24 23:31:45 PDT 2019