Why Sponsor Oils? | source | all docs for version 0.22.0 | all versions | oilshell.org
Oils Reference — OSH | YSH Table of Contents | Data Notation
YSH is shell with a familiar syntax, JSON-like data structures, good error handling, and more.
[Atom Types] Null Bool
[Number Types] Int Float
[Str] X find() replace()
trim() trimStart() trimEnd()
startsWith() endsWith()
upper() lower()
search() leftMatch()
[List] List/append() pop() extend() indexOf()
X insert() X remove() reverse()
[Dict] keys() values() X get() X erase()
X inc() X accum()
[Range]
[Eggex]
[Match] group() start() end()
X groups() X groupDict()
[Place] setValue()
[Code Types] Expr Command
BuiltinFunc BoundFunc
X [Func] name() location() toJson()
X [Proc] name() location() toJson()
X [Module] name() filename()
[IO] X eval() X captureStdout()
promptVal()
X time() X strftime()
X glob()
X [Guts] heapId()
[Values] len() func/type()
[Conversions] bool() int() float()
str() list() dict()
X runes() X encodeRunes()
X bytes() X encodeBytes()
[Str] X strcmp() X split() shSplit()
[List] join()
[Float] floatsEqual() X isinf() X isnan()
[Collections] X copy() X deepCopy()
[Word] glob() maybe()
[Serialize] toJson() fromJson()
toJson8() fromJson8()
X [J8 Decode] J8.Bool() J8.Int() ...
[Pattern] _group() _start() _end()
[Introspection] shvarGet() getVar() evalExpr()
[Hay Config] parseHay() evalHay()
X [Hashing] sha1dc() sha256()
[Memory] cmd/append Add elements to end of array
pp asdl cell X gc-stats line proc
[Handle Errors] error error 'failed' (status=2)
try Run with errexit, set _error
failed Test if _error.code !== 0
boolstatus Enforce 0 or 1 exit status
[Shell State] ysh-cd ysh-shopt compatible, and takes a block
shvar Temporary modify global settings
ctx Share and update a temporary "context"
push-registers Save registers like $?, PIPESTATUS
[Modules] runproc Run a proc; use as main entry point
module guard against duplicate 'source'
is-main false when sourcing a file
use change first word lookup
[I/O] ysh-read flags --all, -0
ysh-echo 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
[Hay Config] hay haynode For DSLs and config files
[Completion] compadjust compexport
[Data Formats] json read write
json8 read write
X [Testing] assert takes an expression
[math] abs()
max() min()
X round()
sum()
[list] all() any()
repeat()
[args] parser Parse command line arguments
flag
arg
rest
parseArgs()
[yblocks] yb-capture
yb-capture-2
X [Lines] slurp-by combine adjacent lines into cells
X [Awk] each-line --j8 --max-jobs (Str, Template, Block) - xargs
each-row --max-jobs (Str, Template, Block) - xargs
each-word xargs-like splitting, similar to IFS too
split-by (str=\n, ifs=':', pattern=/s+/)
if-split-by
chop alias for split-by (pattern=/s+/)
must-match (/ <capture d+> </capture w+> /)
if-match
X [Table Create] table --by-row --by-col (&place); construct/parse a table
table/cols cols name age - cols name:Str age:Int
types type Str Int
attr attr units - secs
row emit row
table cat concatenate TSV8
table align to ssv8
table tabify to tsv8
table header (cols = :|name age|, types = :|Str Int|, units = :|- secs|)
table slice e.g. slice (1, -1) slice (5, 7)
table to-tsv lose type info, and error on \t in cells
X [Table Ops] where subset of rows; dplyr filter()
pick subset of columns ('select' taken by shell)
mutate transmute [average = count / sum] - drop the ones that are used?
rename (bytes='bytes', path='filename')
group-by add a column with a group ID [ext]
sort-by sort by columns; dplyr arrange() [ext]
summary count, sum, histogram, any, all, reduce(), etc. [ext]
[Usage] oils-usage ysh-usage
[Lexing] ascii-whitespace [ \t\r\n]
doc-comment ### multiline-command ...
[Tools] cat-em
[YSH Simple] typed-arg json write (x)
lazy-expr-arg assert [42 === x]
block-arg cd /tmp { echo $PWD }; cd /tmp (; ; blockexpr)
[YSH Cond] ysh-case case (x) { *.py { echo 'python' } }
ysh-if if (x > 0) { echo }
[YSH Iter] ysh-while while (x > 0) { echo }
ysh-for for i, item in (mylist) { echo }
[Assignment] const var Declare variables
setvar setvar a[i] = 42
setglobal setglobal d.key = 'foo'
[Expression] equal = = 1 + 2*3
call call mylist->append(42)
[Definitions] proc proc p (s, ...rest) {
typed proc p (; typed, ...rest; n=0; b) {
func func f(x; opt1, opt2) { return (x + 1) }
ysh-return return (myexpr)
[Assignment] assign =
aug-assign += -= *= /= **= //= %=
&= |= ^= <<= >>=
[Literals] atom-literal true false null
int-literal 42 65_536 0xFF 0o755 0b10
float-lit 3.14 1.5e-10
X num-suffix 42 K Ki M Mi G Gi T Ti / ms us
ysh-string "x is $x" $"x is $x" r'[a-z]\n'
u'line\n' b'byte \yff'
triple-quoted """ $""" r''' u''' b'''
str-template ^"$a and $b" for Str::replace()
list-literal ['one', 'two', 3] :| unquoted words |
dict-literal {name: 'bob'} {a, b}
range 1 .. n+1
block-expr ^(echo $PWD)
expr-literal ^[1 + 2*3]
X expr-sub $[myobj]
X expr-splice @[myobj]
[Operators] op-precedence Like Python
concat s1 ++ s2, L1 ++ L2
ysh-equals === !== ~== is, is not
ysh-in in, not in
ysh-compare < <= > >= (numbers only)
ysh-logical not and or
ysh-arith + - * / // % **
ysh-bitwise ~ & | ^ << >>
ysh-ternary '+' if x >= 0 else '-'
ysh-index s[0] mylist[3] mydict['key']
ysh-attr mydict.key
ysh-slice a[1:-1] s[1:-1]
func-call f(x, y; ...named)
thin-arrow mylist->pop()
fat-arrow mystr => startsWith('prefix')
match-ops ~ !~ ~~ !~~
[Eggex] re-literal / d+ ; re-flags ; ERE /
re-primitive %zero 'sq'
class-literal [c a-z 'abc' @str_var \\ \xFF \u0100]
named-class dot digit space word d s w
re-repeat d? d* d+ d{3} d{2,4}
re-compound seq1 seq2 alt1|alt2 (expr1 expr2)
re-capture <capture d+ as name: int>
re-splice Subpattern @subpattern
re-flags reg_icase reg_newline
X re-multiline ///
[Quotes] ysh-string "x is $x" $"x is $x" r'[a-z]\n'
u'line\n' b'byte \yff'
triple-quoted """ $""" r''' u''' b'''
X tagged-str "<span id=$x>"html
[Substitutions] expr-sub echo $[42 + a[i]]
expr-splice echo @[split(x)]
var-splice @myarray @ARGV
command-sub @(split command)
[Formatting] X ysh-printf ${x %.3f}
X ysh-format ${x|html}
[Patterns] glob-pat *.py
[Other Sublang] braces {alice,bob}@example.com
[Groups] strict:all ysh:upgrade ysh:all
[YSH Details] opts-redefine opts-internal
[YSH Vars] ARGV X ENV X _ESCAPE
_this_dir
[YSH Status] _error
_pipeline_status _process_sub_status
[YSH Tracing] SHX_indent SHX_punct SHX_pid_str
[YSH read] _reply
[History] YSH_HISTFILE
[Oils VM] OILS_VERSION
OILS_GC_THRESHOLD OILS_GC_ON_EXIT
OILS_GC_STATS OILS_GC_STATS_FD
LIB_YSH
[Float] NAN INFINITY
[YSH] renderPrompt()