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.6.0/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] match-with match-case 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[@]}"
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}
op-format ${x@P}
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
extglob @(*.py|*.sh)
regex [[ foo =~ [a-z]+ ]]
[Brace Expand] braces {alice,bob}@example.com
[History] histsub !$ !! !n
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 compgen compopt compadjust
[Shell Process] exec X logout
umask X ulimit X times
[Child Process] jobs wait ampersand &
fg X bg X disown
[External] test [ printf getopts X kill
[Introspection] help X hash type X caller
[Word Lookup] command builtin
[Interactive] alias unalias history X fc X bind
X [Unsupported] enable
OIL BUILTINS
[Compatibility] sh-builtin sh-eval sh-expr
[I/O] write readline
[External] dirname basename env ?
SHELL OPTIONS
[Errors] nounset errexit pipefail
[Globbing] noglob failglob nullglob
[Debugging] xtrace X verbose X extdebug
[Interactive] emacs vi
[Other] X noclobber
[Parsing] TODO
[OSH Strict] strict-argv strict-array strict-arith
X strict-backslash strict-errexit strict-control-flow
X strict-glob strict-word-eval
[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
[Shell Options] SHELLOPTS X BASHOPTS
[Other Vars] HOME PATH IFS
SPECIAL VARIABLES
X [Platform] HOSTNAME OSTYPE BASH_VERSION @BASH_VERSINFO
[Call Stack] @BASH_SOURCE @FUNCNAME @BASH_LINENO
X BASH_ARGV X 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
[Completion] @COMP_WORDS COMP_CWORD COMP_LINE COMP_POINT
COMP_WORDBREAKS @COMPREPLY X COMP_KEY
X COMP_TYPE COMP_ARGV
[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
[Words] PS1 X PS2 X PS3 PS4
[Completion] complete
X [Other] command_not_found PROMPT_COMMAND
OIL EXTENSIONS
X [Static] :use :option
X [awk] BEGIN END when
X [make] rule
X [find] fs
X [xargs] each
OIL LIBRARIES
X [Compatibility] shExpr() shEval()
X [Builtin Procs] log die
X [Builtin Funcs] join() split() strftime()
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?
If the --rcfile flag is specified, osh and oil will source that on startup. Otherwise they source ~/.config/oil/oshrc and ~/.config/oil/oilrc, respectively. To disable startup files, pass --rcfile /dev/null.
Oil currently has support for building against GNU readline.
OSH supports bash-compatible $PS1 syntax.
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.
${x@P} evaluates x as a prompt string, e.g. the string that would be printed if
PS1=$x.
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
Register completion policies for different commands.
Generate completion candidates inside a user-defined completion function.
Change completion options inside a user-defined completion function.
Adjust COMP_ARGV according to specified delimiters, and optionally set variables cur, prev, words (an array), and cword. May also set 'split'. This is an OSH extension that makes it easier to run the bash-completion project.
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.
For the 'set' builtin.
For the 'shopt' builtin.
$HOME is used for: 1. ~ expansion 2. ~ abbreviation in the UI (the dirs builtin, \W in $PS1). Note: The shell doesn't set $HOME. According to POSIX, the program that invokes the login shell sets it based on /etc/passwd.
Used for finding executables to run.
Used for word splitting.
An array of words, split by : and = for compatibility with bash. New completion scripts should use COMP_ARGV instead.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
User-defined completion functions should Fill this array with candidates. It is cleared on every completion request.
An array of partial command arguments to complete. Preferred over COMP_WORDS. The compadjust builtin uses this variable.
First line of a prompt.
Second line of a prompt.
For the 'select' builtin (unimplemented).
For 'set -o xtrace'. The leading character is special.
Useful for logging callbacks. NOTE: bash has this with the obscure printf '%(...)' syntax.