OSH Quick Reference

- 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.alpha1/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]

