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

Oil Help Topics

This is the online help for the Oil language. It underlies the help builtin.

For example, typing help proc in the shell shows you how to use the proc statement. A link to this same text appears in the command group below.

To view this index inside the shell, use:

help oil

An X next to a help topic means that the feature is unimplemented.

You may also want to browse OSH Help Topics.

Table of Contents
Overview (overview)
Command Language (command)
Assignments and Expression Language (assign)
Word Language (word)
Builtin Commands (builtin)
Shell Options (option)
Environment Variables (env)
Special Variables (special)
Builtin Functions (lib)

Overview (overview)

  [Usage]         bundle-usage   oil-usage
  [Oil Lexing]    X single-command %%%   X docstring ###

Command Language (command)

                  proc          proc p (x, y, @rest, &block) { echo hi }
                  equal =       = 1 + 2*3
                  underscore _  _ push(x, 3)
                  oil-block     cd /tmp { echo $PWD }

Assignments and Expression Language (assign)

  [Keywords]      const   var   setvar   setref   setglobal   setlocal/set
  [Literals]      oil-numbers    42  3.14  1e100
                  oil-string    c'line\n'  r'[a-z]\n'
                  char-literal  #'a'   #'_'   \n   \\   \u{3bc}
                  bool-literal  True   False   None
                  list-literal  %(one two)  ['one', 'two', 3]
                  dict-literal  {name: 'bob'}
  [Operators]     concat        s1 ++ s2,  L1 ++ L2
                  oil-equals    ==   !=   ~==   is, is not, in, not in
                  oil-compare   <  <=  >  >=  (numbers only)
                  oil-logical    not  and  or
                  oil-arith     +  -  *  /  //  %   ** 
                  oil-bitwise   ~  &  |  ^  <<  >>
                  oil-ternary   '+' if x >= 0 else '-'
                  oil-index     a[3]  s[3]
                  oil-slice     a[1:-1]  s[1:-1]
                  func-call     f(x, y)
                  block-expr    &(echo $PWD)
                  match-ops     ~   !~   ~~   !~~
  [Eggex]         re-literal    / d+ /
                  re-compound   ~   (group)   <capture>   sequence
                  re-primitive  %zero   Subpattern   @subpattern
                                'sq'   "dq"   $x   ${x}
                  named-class    dot  digit  space  word  d  s  w
                  class-literal [c a-z 'abc' \\ \xFF \u0100]
                  X re-flags    ignorecase etc.
                  X re-multiline  ///

Word Language (word)

                  inline-call   $strfunc(x, y) @arrayfunc(z)
                  splice        @myarray @ARGV
                  expr-sub      echo $[42 + a[i]]
                  X oil-printf  ${x %.3f}
                  X oil-format  ${x|html}

Builtin Commands (builtin)

  [Oil Builtins]  cd   X shopt   X env   compatible, and takes a block
                  X fork   X forkwait    replaces & and (), takes a block
                  X fopen                Many open streams, takes a block
                  X use                  source with namespace, file-relative 
                  X opts                 getopts replacement
                  push                   add elements to end of array
                  repr                   Show debug representation of vars
                  write                  like echo, but with --, -sep, -end
                  oil-read               buffered I/O with --line, --all, --qsn
                  run                    re-enable errexit; exit status utils
                  X log   X die          common functions (polyfill)
  [Data Formats]  json   X qtsv
X [External Lang] BEGIN   END   when (awk)
                  rule (make)   each (xargs)   fs (find)
X [Testing]       check

Shell Options (option)

  [strict:all]    * All options starting with 'strict_'
                  strict_argv            No empty argv
                  strict_arith           Fatal parse errors (on by default)
                  strict_array           Arrays don't decay to strings
                  strict_control_flow    trap misplaced break/continue
                  strict_echo            echo takes 0 or 1 arguments
                  strict_errexit         Disallow code that ignores failure
                  strict_eval_builtin    eval takes exactly 1 argument
                  strict_nameref         trap invalid variable names
                  strict_word_eval       Expose unicode and slicing errors
                  strict_tilde           Tilde subst can result in error
                  strict_backslash       Parse $'' and c'' more strictly
                  strict_backticks       Disallow `echo hi`
                  X strict_glob          Parse the sublanguage more strictly
                  X strict_trap          Function name only
                  parse_ignored          Parse and silently ignore?
  [oil:basic]     * Enable Oil functionality
                  parse_at               echo @array @arrayfunc(x, y)
                  parse_brace            if true { ... }; cd ~/src { ... }
                  parse_paren            if (x > 0) ...
                  command_sub_errexit    More errexit checks --  at command sub
                  process_sub_fail       Analogous to pipefail for process subs
                  simple_word_eval       No splitting, static globbing
                  dashglob               Disabled to avoid files like -rf
                  X longopts             test -file, read -delim, etc.
                  X parse_redir_expr     >> var x   << 'here string'
  [oil:all]       * The full Oil language
                  parse_equals           x = 'val' (for cleaner config blocks)
                  parse_set              'set' instead of 'setlocal'
                  X parse_amp            echo hi &2 > /dev/null
                  X parse_dollar_slash   egrep $/ d+ / *.txt
                  X parse_dparen         remove ((
                  X parse_rawc           r'\'   c'\n'   c"$x\n"
                  X simple_test_builtin  Only file tests, remove [, status 2
                  X no_old_builtins      local/declare/etc.  pushd/popd/dirs
                                         ... source  unset  printf  [un]alias
                                         ... getopts
                  X no_old_syntax        [[   $(( ))  ${x%prefix}   $$
                                         $'\n'   @(*.py|*.sh)  `echo comsub`
  [Compatibility] eval_unsafe_arith   parse_dynamic_arith
  [More Options]  allow_command_sub      Internal detail for strict_errexit

Environment Variables (env)

  [Oil Paths]     ?builtins   ?completion_plugins   ?coprocesses

Special Variables (special)

  [Platform]      OIL_VERSION
  [Exit Status]   _status   _pipeline_status   _process_sub_status
X [Wok]           _filename   _line

Builtin Functions (lib)

Access silently mutated globals:

  [Pattern]       _match()   X _start()   X _end()
X [Wok]           _field()


  [Collections]   len()   copy()
X [String]        find()   sub()   join() 
                  split()             $IFS, awk algorithm, regex
  [Word]          glob()   maybe()
X [Arrays]        index()
  [Assoc Arrays]  @keys()   @values()
X [Block]         setvar()            for procs to set in outer scope
                  evalblock()         procs evaluate block to namespace
X [Better Syntax] shquote()
                  lstrip()   rstrip()   lstripglob()   rstripglob()
                  upper()   lower()
X [Hashing]       sha1   sha256 (etc.)

Generated on Fri Oct 23 00:21:10 PDT 2020