NOTE: This document is a work in progress!
- 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]
OSH is a shell.
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: 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: oil [OPTION]... SCRIPT [ARG]...
oil [OPTION]... -c COMMAND [ARG]...
TODO: any changes?
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
The command language is specified by the POSIX shell grammar.
Simple commands are separated by words:
ls /
Redirects can also appear anywhere
echo hi 1>&2
; -- separate statements
For conditionals.
OSH aims to have almost all of the builtins that bash does. Here they are, divided into sections.
These builtins take input and output. They are often used with redirects[1]. [1] help redirects
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
source . eval
set X shopt
cd pwd pushd popd dirs
complete X compgen X compopt
exec exit X logout umask X ulimit X trap X times
jobs wait ampersand & X fg X bg X disown
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
External: bash has builtins that replace these external commands, but OSH doesn't)
use /usr/bin/getopt
bash accepts job control syntax
Bash has this, but OSH won't implement it.
Useful for logging callbacks. NOTE: bash has this with the obscure printf '%(...)' syntax.