NOTE: This document is a work in progress!
- Below is a list of topics, organized into [Sections].
- Features not yet implemented have an X prefix.
- View it on the web at https://www.oilshell.org/TODO
- NOTE: Oil features are all unimplemented!
INTRO
[Overview] overview osh-vs-oil command-vs-expr
[Usage] osh-usage oil-usage config startup line-editing
prompt
[Lexing] comments # line-continuation \
[Oil Lexing] single-line $ 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
[Grouping] function block { subshell (
[Concurrency] pipe | X |&
ampersand & X proc-sub
[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
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 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
X proc-sub diff <(sort L.txt) <(sort R.txt)
[Special Vars] special-vars $? $# $PPID $IFS ...
[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 [[ $a == $b ]]
[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
[Set Options] set shopt
[Working Dir] cd pwd pushd popd dirs
[Completion] complete X compgen X compopt
[Shell Process] exec exit X logout
umask X ulimit X trap 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
[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-control-flow X strict-arith
[OSH Sane] SANE X sane-no-word-split X sane-glob
ENVIRONMENT VARIABLES
X [Prompts] PS1 PS2
X [select] PS3
[xtrace] PS4
[Shell Options] X 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 LINENO
[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
[Oil] SOURCE_NAME
PLUGINS AND HOOKS
X [Signals] SIGINT SIGABRT SIGTODO
X [Traps] ERR DEBUG RETURN EXIT
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 [getopts] ?
X [Testing] ?
X [Data Formats] json csv tsv2
OSH is a shell.
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 MAIN_NAME [ARG]...
MAIN_NAME [ARG]...
oil 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 osh -c 'echo hi'
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.