Why Sponsor Oil? | source | all docs for version 0.15.0 | 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 ...
X proc proc p (x, out Ref, @rest, e Expr, b Block) { c }
X func func f(x; opt1, opt2) { return (x + 1) }
X oil-return return (myexpr)
X oil-case case (x) { *.py { echo 'python' } }
oil-if if (x > 0) { echo }
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
num-suffix 42 K Ki M Mi G Gi T Ti / ms us
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]
X template ^"$a and $b" for Str::replace()
X to-string $[myobj]
X to-array @[myobj]
[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]
X oil-attr mydict.key
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 ///
splice @myarray @ARGV
expr-sub echo $[42 + a[i]]
X ystr y"byte \y00 unicode \u{123456}"
X oil-printf ${x %.3f}
X oil-format ${x|html}
[Memory] append Add elements to end of array
X argparse getopts replacement, sets OPT
X setref Builtin to replac ekeyword
pp Pretty print interpreter state
[Handle Errors] try Run with errexit and set _status
boolstatus Enforce 0 or 1 exit status
X error Can be used in both proc and func
[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
X oil-echo Single arg, no -e -n with simple_echo
write Like echo, with --, --sep, --end, ()
fork forkwait Replace & and (), and takes a block
fopen Open multiple streams, takes a block
X dbg Only thing that can be used in funcs
X log X die common functions (polyfill)
[Hay Config] hay haynode For DSLs and config files
[Data Formats] json
X ystr Upgrade JSON with binary, utf-8
X yson Tree-shaped
X ytsv Table-shaped
X packle Graph-shaped
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_arith (-u) Is legacy shell arithmetic allowed?
parse_sh_assign (-u) Are legacy a=b and PATH=. cmd allowed?
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] eval_unsafe_arith Allow dynamically parsed a[$(echo 42)]
verbose_errexit Whether to print detailed errors
[More Options] _allow_command_sub To implement strict_errexit, eval_unsafe_arith
_allow_process_sub To implement strict_errexit
dynamic_scope To implement '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(eggex) replace(eggex, template) 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.)