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