OILS / doc / ref / toc-ysh.md View on Github | oilshell.org

357 lines, 314 significant
1---
2title: YSH Table of Contents
3all_docs_url: ..
4css_files: ../../web/base.css ../../web/manual.css ../../web/ref-index.css
5preserve_anchor_case: yes
6---
7
8<div class="doc-ref-header">
9
10[Oils Reference](index.html) &mdash;
11[OSH](toc-osh.html) | **YSH Table of Contents** | [Data Notation](toc-data.html)
12
13</div>
14
15[YSH]($xref) is shell with a familiar syntax, JSON-like data structures, good
16error handling, and more.
17
18<!--
19<div class="custom-toc">
20
21[type-method](#type-method) &nbsp;
22[builtin-func](#builtin-func) &nbsp;
23[builtin-cmd](#builtin-cmd) &nbsp;
24[front-end](#front-end) &nbsp;
25[cmd-lang](#cmd-lang) &nbsp;
26[ysh-cmd](#ysh-cmd) &nbsp;
27[expr-lang](#expr-lang) &nbsp;
28[word-lang](#word-lang) &nbsp;
29[mini-lang](#mini-lang) &nbsp;
30[option](#option) &nbsp;
31[special-var](#special-var) &nbsp;
32[plugin](#plugin)
33
34</div>
35-->
36
37<h2 id="type-method">
38 Types and Methods <a class="group-link" href="chap-type-method.html">type-method</a>
39</h2>
40
41```chapter-links-type-method
42 [Atom Types] Null Bool
43 [Number Types] Int Float
44 [Str] X find() replace()
45 trim() trimStart() trimEnd()
46 startsWith() endsWith()
47 upper() lower()
48 search() leftMatch()
49 [List] List/append() pop() extend() indexOf()
50 X insert() X remove() reverse()
51 [Dict] keys() values() X get() erase()
52 X inc() X accum()
53 [Range]
54 [Eggex]
55 [Match] group() start() end()
56 X groups() X groupDict()
57 [Place] setValue()
58 [Code Types] Expr Command
59 BuiltinFunc BoundFunc
60X [Func] name() location() toJson()
61X [Proc] name() location() toJson()
62X [Module] name() filename()
63 [IO] eval() captureStdout()
64 promptVal()
65 X time() X strftime()
66 X glob()
67X [Guts] heapId()
68```
69
70<h2 id="builtin-func">
71 Builtin Functions <a class="group-link" href="chap-builtin-func.html">builtin-func</a>
72</h2>
73
74```chapter-links-builtin-func
75 [Values] len() func/type()
76 [Conversions] bool() int() float()
77 str() list() dict()
78 X runes() X encodeRunes()
79 X bytes() X encodeBytes()
80 [Str] X strcmp() X split() shSplit()
81 [List] join()
82 [Float] floatsEqual() X isinf() X isnan()
83 [Collections] X copy() X deepCopy()
84 [Word] glob() maybe()
85 [Serialize] toJson() fromJson()
86 toJson8() fromJson8()
87X [J8 Decode] J8.Bool() J8.Int() ...
88 [Pattern] _group() _start() _end()
89 [Introspection] shvarGet() getVar() evalExpr()
90 [Hay Config] parseHay() evalHay()
91X [Hashing] sha1dc() sha256()
92```
93
94<!-- ideas
95X [Codecs] quoteUrl() quoteHtml() quoteSh() quoteC()
96 quoteMake() quoteNinja()
97X [Wok] _field()
98-->
99
100<h2 id="builtin-cmd">
101 Builtin Commands <a class="group-link" href="chap-builtin-cmd.html">builtin-cmd</a>
102</h2>
103
104<!-- linkify_stop_col is 42 -->
105
106```chapter-links-builtin-cmd_42
107 [Memory] cmd/append Add elements to end of array
108 pp value proc line
109 asdl cell X gc-stats
110 [Handle Errors] error error 'failed' (status=2)
111 try Run with errexit, set _error
112 failed Test if _error.code !== 0
113 boolstatus Enforce 0 or 1 exit status
114 assert assert [42 === f(x)]
115 [Shell State] ysh-cd ysh-shopt compatible, and takes a block
116 shvar Temporary modify global settings
117 ctx Share and update a temporary "context"
118 push-registers Save registers like $?, PIPESTATUS
119 [Modules] runproc Run a proc; use as main entry point
120 module guard against duplicate 'source'
121 is-main false when sourcing a file
122 use change first word lookup
123 [I/O] ysh-read flags --all, -0
124 ysh-echo no -e -n with simple_echo
125 write Like echo, with --, --sep, --end
126 fork forkwait Replace & and (), and takes a block
127 fopen Open multiple streams, takes a block
128 X dbg Only thing that can be used in funcs
129 [Hay Config] hay haynode For DSLs and config files
130 [Completion] compadjust compexport
131 [Data Formats] json read write
132 json8 read write
133```
134
135<h2 id="stdlib">
136 Standard Library<a class="group-link" href="chap-stdlib.html">stdlib</a>
137</h2>
138
139<!-- linkify_stop_col is 42 -->
140
141```chapter-links-stdlib_42
142 [math] abs()
143 max() min()
144 X round()
145 sum()
146 [list] all() any()
147 repeat()
148 [args] parser Parse command line arguments
149 flag
150 arg
151 rest
152 parseArgs()
153 [yblocks] yb-capture
154 yb-capture-2
155X [Lines] slurp-by combine adjacent lines into cells
156X [Awk] each-line --j8 --max-jobs (Str, Template, Block) - xargs
157 each-row --max-jobs (Str, Template, Block) - xargs
158 each-word xargs-like splitting, similar to IFS too
159 split-by (str=\n, ifs=':', pattern=/s+/)
160 if-split-by
161 chop alias for split-by (pattern=/s+/)
162 must-match (/ <capture d+> </capture w+> /)
163 if-match
164X [Table Create] table --by-row --by-col (&place); construct/parse a table
165 table/cols cols name age - cols name:Str age:Int
166 types type Str Int
167 attr attr units - secs
168 row emit row
169 table cat concatenate TSV8
170 table align to ssv8
171 table tabify to tsv8
172 table header (cols = :|name age|, types = :|Str Int|, units = :|- secs|)
173 table slice e.g. slice (1, -1) slice (5, 7)
174 table to-tsv lose type info, and error on \t in cells
175X [Table Ops] where subset of rows; dplyr filter()
176 pick subset of columns ('select' taken by shell)
177 mutate transmute [average = count / sum] - drop the ones that are used?
178 rename (bytes='bytes', path='filename')
179 group-by add a column with a group ID [ext]
180 sort-by sort by columns; dplyr arrange() [ext]
181 summary count, sum, histogram, any, all, reduce(), etc. [ext]
182```
183
184<!--
185Naming ideas:
186
187X [External Lang] BEGIN END when (awk)
188 rule (make) each (xargs) fs (find)
189-->
190
191<h2 id="front-end">
192 Front End <a class="group-link" href="chap-front-end.html">front-end</a>
193</h2>
194
195```chapter-links-front-end
196 [Usage] oils-usage ysh-usage
197 [Lexing] ascii-whitespace [ \t\r\n]
198 doc-comment ### multiline-command ...
199 [Tools] cat-em
200```
201
202<h2 id="cmd-lang">
203 Command Language <a class="group-link" href="chap-cmd-lang.html">cmd-lang</a>
204</h2>
205
206<!-- linkify_stop_col is 33 -->
207
208```chapter-links-cmd-lang_33
209 [YSH Simple] typed-arg json write (x)
210 lazy-expr-arg assert [42 === x]
211 block-arg cd /tmp { echo $PWD }; cd /tmp (; ; blockexpr)
212 [YSH Cond] ysh-case case (x) { *.py { echo 'python' } }
213 ysh-if if (x > 0) { echo }
214 [YSH Iter] ysh-while while (x > 0) { echo }
215 ysh-for for i, item in (mylist) { echo }
216```
217
218<h2 id="ysh-cmd">
219 YSH Command Language Keywords <a class="group-link" href="chap-ysh-cmd.html">ysh-cmd</a>
220</h2>
221
222```chapter-links-ysh-cmd_33
223 [Assignment] const var Declare variables
224 setvar setvar a[i] = 42
225 setglobal setglobal d.key = 'foo'
226 [Expression] equal = = 1 + 2*3
227 call call mylist->append(42)
228 [Definitions] proc proc p (s, ...rest) {
229 typed proc p (; typed, ...rest; n=0; b) {
230 func func f(x; opt1, opt2) { return (x + 1) }
231 ysh-return return (myexpr)
232```
233
234<h2 id="expr-lang">
235 Expression Language and Assignments <a class="group-link" href="chap-expr-lang.html">expr-lang</a>
236</h2>
237
238<!-- linkify_stop_col is 33 -->
239
240```chapter-links-expr-lang_33
241 [Assignment] assign =
242 aug-assign += -= *= /= **= //= %=
243 &= |= ^= <<= >>=
244 [Literals] atom-literal true false null
245 int-literal 42 65_536 0xFF 0o755 0b10
246 float-lit 3.14 1.5e-10
247 char-literal \\ \t \" \y00 \u{3bc}
248 X num-suffix 42 K Ki M Mi G Gi T Ti / ms us
249 ysh-string "x is $x" $"x is $x" r'[a-z]\n'
250 u'line\n' b'byte \yff'
251 triple-quoted """ $""" r''' u''' b'''
252 str-template ^"$a and $b" for Str::replace()
253 list-literal ['one', 'two', 3] :| unquoted words |
254 dict-literal {name: 'bob'} {a, b}
255 range 1 .. n+1
256 block-expr ^(echo $PWD)
257 expr-literal ^[1 + 2*3]
258 X expr-sub $[myobj]
259 X expr-splice @[myobj]
260 [Operators] op-precedence Like Python
261 concat s1 ++ s2, L1 ++ L2
262 ysh-equals === !== ~== is, is not
263 ysh-in in, not in
264 ysh-compare < <= > >= (numbers only)
265 ysh-logical not and or
266 ysh-arith + - * / // % **
267 ysh-bitwise ~ & | ^ << >>
268 ysh-ternary '+' if x >= 0 else '-'
269 ysh-index s[0] mylist[3] mydict['key']
270 ysh-attr mydict.key
271 ysh-slice a[1:-1] s[1:-1]
272 func-call f(x, y; ...named)
273 thin-arrow mylist->pop()
274 fat-arrow mystr => startsWith('prefix')
275 match-ops ~ !~ ~~ !~~
276 [Eggex] re-literal / d+ ; re-flags ; ERE /
277 re-primitive %zero 'sq'
278 class-literal [c a-z 'abc' @str_var \\ \xFF \u{3bc}]
279 named-class dot digit space word d s w
280 re-repeat d? d* d+ d{3} d{2,4}
281 re-compound seq1 seq2 alt1|alt2 (expr1 expr2)
282 re-capture <capture d+ as name: int>
283 re-splice Subpattern @subpattern
284 re-flags reg_icase reg_newline
285 X re-multiline ///
286```
287
288<h2 id="word-lang">
289 Word Language <a class="group-link" href="chap-word-lang.html">word-lang</a>
290</h2>
291
292<!-- linkify_stop_col is 33 -->
293
294```chapter-links-word-lang_33
295 [Quotes] ysh-string "x is $x" $"x is $x" r'[a-z]\n'
296 u'line\n' b'byte \yff'
297 triple-quoted """ $""" r''' u''' b'''
298 X tagged-str "<span id=$x>"html
299 [Substitutions] expr-sub echo $[42 + a[i]]
300 expr-splice echo @[split(x)]
301 var-splice @myarray @ARGV
302 command-sub @(split command)
303 [Formatting] X ysh-printf ${x %.3f}
304 X ysh-format ${x|html}
305```
306
307<h2 id="mini-lang">
308 Other Mini Languages <a class="group-link" href="chap-mini-lang.html">mini-lang</a>
309</h2>
310
311<!-- linkify_stop_col is 33 -->
312
313```chapter-links-mini-lang_33
314 [Patterns] glob-pat *.py
315 [Other Sublang] braces {alice,bob}@example.com
316```
317
318<h2 id="option">
319 Global Shell Options <a class="group-link" href="chap-option.html">option</a>
320</h2>
321
322```chapter-links-option
323 [Groups] strict:all ysh:upgrade ysh:all
324 [YSH Details] opts-redefine opts-internal
325```
326
327<h2 id="special-var">
328 Special Variables <a class="group-link" href="chap-special-var.html">special-var</a>
329</h2>
330
331```chapter-links-special-var
332 [YSH Vars] ARGV X ENV X _ESCAPE
333 _this_dir
334 [YSH Status] _error
335 _pipeline_status _process_sub_status
336 [YSH Tracing] SHX_indent SHX_punct SHX_pid_str
337 [YSH read] _reply
338 [History] YSH_HISTFILE
339 [Oils VM] OILS_VERSION
340 OILS_GC_THRESHOLD OILS_GC_ON_EXIT
341 OILS_GC_STATS OILS_GC_STATS_FD
342 LIB_YSH
343 [Float] NAN INFINITY
344```
345
346<!-- ideas
347X [Wok] _filename _line _line_num
348X [Builtin Sub] _buffer
349-->
350
351<h2 id="plugin">
352 Plugins and Hooks <a class="group-link" href="chap-plugin.html">plugin</a>
353</h2>
354
355```chapter-links-plugin
356 [YSH] renderPrompt()
357```