NOTE: This document is a work in progress!

OSH Quick Reference

Version 0.5.alpha2

- 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.5.alpha2/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]   switch   match   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[@]}"
                  X 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}
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
                  X extglob     @(*.py|*.sh)
                  regex         [[ foo =~ [a-z]+ ]]
  [Brace Expand]  braces        {alice,bob}@example.com

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   X compgen   X compopt
  [Shell Process] exec   X logout 
                  umask   X ulimit   X times
  [Child Process] jobs   wait   ampersand &
                  X fg   X bg   X disown 
  [External]      test [   X printf   getopts   X kill
  [Introspection] help   X hash   type   X caller
X [Word Lookup]   command   builtin
X [Interactive]   alias   unalias   bind   history   fc
X [Unsupported]   enable

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

SHELL OPTIONS
  [Errors]        nounset   errexit   pipefail
  [Globbing]      noglob   failglob   nullglob
  [Debugging]     xtrace   X verbose   X extdebug
  [Other]         X noclobber
  [Parsing]       TODO
  [OSH Strict]    STRICT   strict-array   strict-control-flow   
                  strict-errexit   X strict-arith
  [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
X [Prompts]       PS1   PS2
X [select]        PS3
  [xtrace]        PS4
  [Shell Options] SHELLOPTS   X BASHOPTS
  [Other]         HOME   PATH   IFS

SPECIAL VARIABLES
X [Platform]      HOSTNAME   OSTYPE   BASH_VERSION   @BASH_VERSINFO
X [Call Stack]    @BASH_SOURCE   @FUNCNAME   @BASH_LINENO   
                  @BASH_ARGV   @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
  [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
X [Words]         PS1   PS2   PS4
X [Completion]    
X [Other]         command_not_found

OIL EXTENSIONS

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

OIL LIBRARIES

X [Builtin Procs] log   die
X [Builtin Funcs] join()   split()   strftime()
                  shEvalArith()   shEvalWord()   
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


Shell Startup


Line Editing


Customizing the Prompt String


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



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   X compgen   X compopt

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


Special Variables


Plugins and Hooks


Oil Extensions


Oil Libraries


Builtins Procs


Builtins Funcs


strftime()


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

Generated on Thu Mar 1 18:38:48 PST 2018