Why Sponsor Oil? | source | all docs for version 0.13.1 | all versions | oilshell.org
Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.
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-lang 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.
[Usage] bundle-usage oil-usage
[Oil Lexing] docstring ### multiline-command ...
proc proc p (x, :out, @rest, e Expr, b Block) { c }
oil-if if (x > 0) { echo }
oil-case case $x { ('build') do build ;; }
oil-while while (x > 0) { echo }
oil-for for i, item in (mylist) { echo }
equal = = 1 + 2*3
underscore _ _ mylist.append(42)
typed-arg json write (x)
block-arg cd /tmp { echo $PWD }
[Keywords] const var setvar setglobal setref
[Literals] bool-literal true false null
int-literal 42 65_536 0xFF 0o755 0b10
X float-lit 3.14 1.5e-10
rune-literal #'a' #'_' \n \\ \u{3bc}
str-literal r'[a-z]\n' $'line\n'
list-literal %(one two) ['one', 'two', 3]
dict-literal {name: 'bob'}
block-literal ^(echo $PWD)
X expr-lit ^[1 + 2*3]
[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) s.startswith('prefix')
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 ///
inline-call $strfunc(x, y) @arrayfunc(z)
splice @myarray @ARGV
expr-sub echo $[42 + a[i]]
X builtin-sub ${.myproc arg1} @{.otherproc $x $y}
X oil-printf ${x %.3f}
X oil-format ${x|html}
[Memory] append Add elements to end of array
X argparse getopts replacement, sets OPT
pp Pretty print interpreter state
[Handle Errors] try Run with errexit and set _status
boolstatus Enforce 0 or 1 exit status
[Shell State] oil-cd oil-shopt compatible, and takes a block
shvar Temporary modify global settings
push-registers Save registers like $?, PIPESTATUS
[Modules] runproc Run a proc; use as main entry point
module guard against duplicate 'source'
use change first word lookup
[I/O] oil-read Buffered I/O with --line, --all, --qsn
write Like echo, but with --, --sep, --end
fork forkwait Replace & and (), and takes a block
fopen Open multiple streams, takes a block
X log X die common functions (polyfill)
[Hay Config] hay haynode For DSLs and config files
[Data Formats] json X qtt
X [QTT] rows pick rows; dplyr filter()
cols pick columns ('select' already taken)
group-by add a column with a group ID [ext]
sort-by sort by columns; dplyr arrange() [ext]
summary count, sum, histogram, etc. [ext]
X [Testing] describe Test harness
assert takes an expression
X [External Lang] BEGIN END when (awk)
rule (make) each (xargs) fs (find)
[Option Groups] strict:all oil:upgrade oil:all
[Strictness] ... More Runtime Errors
strict_argv No empty argv
strict_arith Fatal parse errors (on by default)
strict_array Arrays don't decay to strings
strict_control_flow Disallow misplaced keyword, empty arg
strict_errexit Disallow code that ignores failure
strict_nameref trap invalid variable names
strict_word_eval Expose unicode and slicing errors
strict_tilde Tilde subst can result in error
X strict_glob Parse the sublanguage more strictly
[Oil Upgrade] ... Migrate Existing Code to Oil
parse_at echo @array @arrayfunc(x, y)
parse_brace if true { ... }; cd ~/src { ... }
parse_equals x = 'val' in Caps { } config blocks
parse_paren if (x > 0) ...
parse_proc proc p { ... }
parse_raw_string echo r'\' (command mode)
parse_triple_quote """ ''' r''' $''' in command mode
command_sub_errexit Synchronous errexit check
process_sub_fail Analogous to pipefail for process subs
sigpipe_status_ok status 141 -> 0 in pipelines
simple_word_eval No splitting, static globbing
xtrace_rich Hierarchical and process tracing
xtrace_details (-u) Disable most tracing with +
dashglob (-u) Disabled to avoid files like -rf
expand_aliases (-u) Whether aliases are expanded
redefine_proc (-u) Can procs be redefined?
[Interactive] redefine_module 'module' builtin always returns 0
X redefine_const Can consts be redefined?
[Simplicity] ... More Consistent Style
simple_echo echo takes 0 or 1 arguments
simple_eval_builtin eval takes exactly 1 argument
simple_test_builtin 3 args or fewer; use test not [
X simple_trap Function name only
[Oil Breaking] ... The Full Oil Language
parse_at_all @ starting any word is an operator
parse_backslash (-u) Bad backslashes in $''
parse_backticks (-u) Legacy syntax `echo hi`
parse_bare_word (-u) 'case unquoted' and 'for x in unquoted'
parse_dollar (-u) Is $ allowed for \$? Maybe $/d+/
parse_dparen (-u) Is (( legacy arithmetic allowed?
parse_ignored (-u) Parse, but ignore, certain redirects
parse_sh_assign (-u) Are legacy a=b and PATH=. cmd allowed?
parse_sloppy_case (-u) Case patterns look like (*.py) not *.py)
X copy_env (-u) Use $[ENV->PYTHONPATH] when false
X old_builtins (-u) local/declare/etc. pushd/popd/dirs
... source unset printf [un]alias
... getopts
X old_syntax (-u) [[ $(( )) ${x%prefix} ${a[@]}
$$
[Compatibility] compat_array ${array} is ${array[0]}
eval_unsafe_arith Recursively parse and evaluate
parse_dynamic_arith LHS can contain variables
verbose_errexit Whether to print detailed errors
[More Options] allow_csub_psub For implementing strict_errexit
dynamic_scope For implementing 'proc'
[Oil Paths] ?builtins ?completion_plugins ?coprocesses
[Shell Vars] ARGV X ENV X OPT
X _ESCAPE _DIALECT
_this_dir
[Platform] OIL_VERSION
[Exit Status] _status _pipeline_status _process_sub_status
[Tracing] SHX_indent SHX_punct SHX_pid_str
X [Wok] _filename _line
X [Builtin Sub] _buffer
Access silently mutated globals:
[Pattern] _match() X _start() X _end()
X [Wok] _field()
Functions:
[Collections] len()
X [String] find() sub() join()
split() $IFS, awk algorithm, regex
[Word] glob() maybe()
[Arrays] X index() append() extend()
[Assoc Arrays] @keys() @values()
[Introspection] shvar_get()
X [Hay Config] parse_hay() eval_hay() block_as_str()
X [Better Syntax] lstrip() rstrip() lstripglob() rstripglob()
upper() lower()
strftime()
X [Codecs] posix-sh-str oil-str html-utf8
X [Hashing] sha1 sha256 (etc.)