Why Sponsor Oils? | source | all docs for version 0.23.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() X clear()
[Dict] erase() X inc() X accum() X clear()
[Range]
[Eggex]
[Match] group() start() end()
X groups() X groupDict()
[Place] setValue()
[Code Types] Command CommandFrag
Expr ExprFrag
BuiltinFunc BoundFunc
Frame
X [Func] name() location() toJson()
X [Proc] name() location() toJson()
[IO] stdin eval() evalToDict()
captureStdout()
evalExpr()
promptVal()
X time() X strftime() X glob()
[Obj] __invoke__ X __call__ X __str__
[VM] X getFrame()
[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()
[Dict] keys() values() get()
[Float] floatsEqual() X isinf() X isnan()
[Obj] Object() prototype() propView()
get()
[Word] glob() maybe()
[Serialize] toJson() fromJson()
toJson8() fromJson8()
X [J8 Decode] J8.Bool() J8.Int() ...
[Pattern] _group() _start() _end()
[Introspection] id()
shvarGet() getVar() setVar()
parseCommand() X parseExpr() X bindFrame()
[Hay Config] parseHay() evalHay()
X [Hashing] sha1dc() sha256()
[Memory] cmd/append Add elements to end of array
pp value proc test_
asdl_ cell_ X gc-stats_
[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
assert assert [42 === f(x)]
[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
[Introspection] runproc Run a proc; use as main entry point
X extern Run an external command, with an ENV
X invoke Control which "invokables" are run
[Modules]
source-guard guard against duplicate 'source'
is-main false when sourcing a file
use create a module Obj from a source file
[I/O] ysh-read flags --all, -0
ysh-echo no -e -n with simple_echo
ysh-test --file --true etc.
write Like echo, with --, --sep, --end
fork forkwait Replace & and (), and takes a block
fopen Open multiple streams, takes a block
[Hay Config] hay haynode For DSLs and config files
[Completion] compadjust compexport
[Data Formats] json read write
json8 read write
[math] abs() max() min() X round()
sum()
[list] all() any() repeat()
[yblocks] yb-capture yb-capture-2
[args] parser flag arg rest
parseArgs()
Design for streams and tables (awk/xargs/dplyr):
X [Lines] slurp-by combine adjacent lines into cells
X [Awk] each-line --j8 --max-jobs (Str, Template, Block)
each-row --max-jobs (Str, Template, Block)
each-word xargs-like splitting, similar to IFS too
split-by (str=\n, ifs=':', pattern=/s+/)
if-split-by only lines that match
chop alias for split-by (pattern=/s+/)
must-match (/ <capture d+> </capture w+> /)
if-match only lines that match
X [Table Create] table def &place or print TSV8
table parse --by-row --by-col (&place), TSV or TSV8
table/cols cols name age, or 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 (similar to table parse)
table header cols = :|name age|, types = :|Str Int|, ...
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 [average = count / sum]
transmute drop columns 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, ...
[Usage] oils-usage ysh-usage
[Lexing] ascii-whitespace [ \t\r\n]
doc-comment ### multiline-command ...
[Tools] cat-em
[Redirect] ysh-here-str read <<< '''
[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-for for i, item in (mylist) { echo }
ysh-while while (x > 0) { 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
char-literal \\ \t \" \y00 \u{3bc}
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 mystr.startsWith('x')
ysh-slice a[1:-1] s[1:-1]
func-call f(x, y; ...named)
thin-arrow mylist->pop()
fat-arrow mylist => join() => upper()
match-ops ~ !~ ~~ !~~
[Eggex] re-literal / d+ ; re-flags ; ERE /
re-primitive %zero 'sq'
class-literal [c a-z 'abc' @str_var \\ \xFF \u{3bc}]
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 @(cat my-j8-lines.txt)
[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
[Module] __provide__
[YSH] renderPrompt()