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

306 lines, 280 significant
1---
2in_progress: yes
3css_files: ../../web/base.css ../../web/ref-index.css ../../web/toc.css
4preserve_anchor_case: yes
5---
6
7YSH Table of Contents
8=====================
9
10[YSH]($xref) is shell with familiar syntax, JSON-like data structures, and
11more. It handles errors properly.
12
13This page has links to topics in the [Oils Reference](index.html).
14
15Siblings: [OSH Topics](toc-osh.html), [Data Topics](toc-data.html)
16
17<div id="toc">
18</div>
19
20
21<h2 id="front-end">
22 Front End (<a class="group-link" href="chap-front-end.html">front-end</a>)
23</h2>
24
25```chapter-links-front-end
26 [Usage] bundle-usage ysh-usage
27 [Lexing] ascii-whitespace [ \t\r\n]
28 doc-comment ### multiline-command ...
29 [Tools] cat-em
30```
31
32<h2 id="cmd-lang">
33 Command Language (<a class="group-link" href="chap-cmd-lang.html">cmd-lang</a>)
34</h2>
35
36```chapter-links-cmd-lang
37 [YSH Simple] typed-arg json write (x)
38 lazy-expr-arg assert [42 === x]
39 block-arg cd /tmp { echo $PWD }; cd /tmp (; ; blockexpr)
40 [YSH Assign] const var setvar setglobal
41 [YSH Expr] equal = = 1 + 2*3
42 call call mylist->append(42)
43 [YSH Code] proc-def proc p (out Ref; pos, ...rest; n=0; b Block) {
44 func-def func f(x; opt1, opt2) { return (x + 1) }
45 ysh-return return (myexpr)
46 [YSH Cond] ysh-case case (x) { *.py { echo 'python' } }
47 ysh-if if (x > 0) { echo }
48 [YSH Iter] ysh-while while (x > 0) { echo }
49 ysh-for for i, item in (mylist) { echo }
50```
51
52<h2 id="expr-lang">
53 Expression Language and Assignments (<a class="group-link" href="chap-expr-lang.html">expr-lang</a>)
54</h2>
55
56```chapter-links-expr-lang
57 [Assign Ops] = += -= *= /= **= //= %=
58 &= |= ^= <<= >>=
59 [Literals] bool-literal true false null
60 int-literal 42 65_536 0xFF 0o755 0b10
61 float-lit 3.14 1.5e-10
62 X num-suffix 42 K Ki M Mi G Gi T Ti / ms us
63 rune-literal #'a' #'_' \n \\ \u{3bc}
64 ysh-string "$x" r'[a-z]\n' u'line\n' b'byte \yff'
65 triple-quoted """ r''' u''' b'''
66 str-template ^"$a and $b" for Str::replace()
67 list-literal ['one', 'two', 3] :| unquoted words |
68 dict-literal {name: 'bob'}
69 range 1 .. n+1
70 block-literal ^(echo $PWD)
71 expr-lit ^[1 + 2*3]
72 X to-string $[myobj]
73 X to-array @[myobj]
74 [Operators] concat s1 ++ s2, L1 ++ L2
75 ysh-equals === !== ~== is, is not, in, not in
76 ysh-compare < <= > >= (numbers only)
77 ysh-logical not and or
78 ysh-arith + - * / // % **
79 ysh-bitwise ~ & | ^ << >>
80 ysh-ternary '+' if x >= 0 else '-'
81 ysh-index a[3] s[3]
82 ysh-attr mydict.key
83 ysh-slice a[1:-1] s[1:-1]
84 func-call f(x, y)
85 thin-arrow mylist->pop()
86 fat-arrow mystr => startsWith('prefix')
87 match-ops ~ !~ ~~ !~~
88 [Eggex] re-literal / d+ ; re-flags ; ERE /
89 re-primitive %zero 'sq'
90 class-literal [c a-z 'abc' @str_var \\ \xFF \u0100]
91 named-class dot digit space word d s w
92 re-repeat d? d* d+ d{3} d{2,4}
93 re-compound seq1 seq2 alt1|alt2 (expr1 expr2)
94 re-capture <capture d+ as name: int>
95 re-splice Subpattern @subpattern
96 re-flags reg_icase reg_newline
97 X re-multiline ///
98```
99
100<h2 id="word-lang">
101 Word Language (<a class="group-link" href="chap-word-lang.html">word-lang</a>)
102</h2>
103
104```chapter-links-word-lang
105 [Quotes] ysh-string "$x" r'[a-z]\n' u'line\n' b'byte \yff'
106 triple-quoted """ r''' u''' b'''
107 X tagged-str "<span id=$x>"html
108 [Substitutions] expr-sub echo $[42 + a[i]]
109 expr-splice echo @[split(x)]
110 var-splice @myarray @ARGV
111 command-sub @(split command)
112 [Formatting] X ysh-printf ${x %.3f}
113 X ysh-format ${x|html}
114```
115
116<h2 id="builtin-cmd">
117 Builtin Commands (<a class="group-link" href="chap-builtin-cmd">builtin-cmd</a>)
118</h2>
119
120```chapter-links-builtin-cmd
121 [Memory] append Add elements to end of array
122 pp asdl cell X gc-stats line proc
123 [Handle Errors] try Run with errexit, set _status _error
124 boolstatus Enforce 0 or 1 exit status
125 error error 'failed' (status=2)
126 [Shell State] ysh-cd ysh-shopt compatible, and takes a block
127 shvar Temporary modify global settings
128 ctx Share and update a temporary "context"
129 push-registers Save registers like $?, PIPESTATUS
130 [Modules] runproc Run a proc; use as main entry point
131 module guard against duplicate 'source'
132 is-main false when sourcing a file
133 use change first word lookup
134 [I/O] ysh-read flags --all, -0
135 ysh-echo no -e -n with simple_echo
136 write Like echo, with --, --sep, --end
137 fork forkwait Replace & and (), and takes a block
138 fopen Open multiple streams, takes a block
139 X dbg Only thing that can be used in funcs
140 X log X die common functions (polyfill)
141 [Hay Config] hay haynode For DSLs and config files
142 [Completion] compadjust compexport
143 [Data Formats] json read write
144 json8 read write
145 X packle read write, Graph-shaped
146X [TSV8] rows pick rows; dplyr filter()
147 cols pick columns ('select' already taken)
148 group-by add a column with a group ID [ext]
149 sort-by sort by columns; dplyr arrange() [ext]
150 summary count, sum, histogram, etc. [ext]
151 [Args Parser] parser Parse command line arguments
152 flag
153 arg
154 rest
155 parseArgs()
156X [Testing] describe Test harness
157 assert takes an expression
158X [External Lang] BEGIN END when (awk)
159 rule (make) each (xargs) fs (find)
160```
161
162<h2 id="option">
163 Shell Options (<a class="group-link" href="chap-option.html">option</a>)
164</h2>
165
166```chapter-links-option
167 [Option Groups] strict:all ysh:upgrade ysh:all
168 [Strictness] ... More Runtime Errors
169 strict_argv No empty argv
170 strict_arith Fatal parse errors (on by default)
171 strict_array Arrays and strings aren't confused
172 strict_control_flow Disallow misplaced keyword, empty arg
173 strict_errexit Disallow code that ignores failure
174 strict_nameref trap invalid variable names
175 strict_word_eval Expose unicode and slicing errors
176 strict_tilde Tilde subst can result in error
177 X strict_glob Parse the sublanguage more strictly
178 [YSH Upgrade] ... Migrate Existing Code to YSH
179 parse_at echo @array @[arrayfunc(x, y)]
180 parse_brace if true { ... }; cd ~/src { ... }
181 parse_equals x = 'val' in Caps { } config blocks
182 parse_paren if (x > 0) ...
183 parse_proc proc p { ... }
184 parse_triple_quote """$x""" '''x''' (command mode)
185 parse_ysh_string echo r'\' u'\\' b'\\' (command mode)
186 command_sub_errexit Synchronous errexit check
187 process_sub_fail Analogous to pipefail for process subs
188 sigpipe_status_ok status 141 -> 0 in pipelines
189 simple_word_eval No splitting, static globbing
190 xtrace_rich Hierarchical and process tracing
191 xtrace_details (-u) Disable most tracing with +
192 dashglob (-u) Disabled to avoid files like -rf
193 redefine_proc (-u) Can procs be redefined?
194 [Interactive] redefine_module 'module' builtin always returns 0
195 X redefine_const Can consts be redefined?
196 [Simplicity] ... More Consistent Style
197 simple_echo echo doesn't accept flags -e -n
198 simple_eval_builtin eval takes exactly 1 argument
199 simple_test_builtin 3 args or fewer; use test not [
200 X simple_trap Function name only
201 [YSH Breaking] ... The Full YSH Language
202 parse_at_all @ starting any word is an operator
203 parse_backslash (-u) Allow bad backslashes in "" and $''
204 parse_backticks (-u) Allow legacy syntax `echo hi`
205 parse_bare_word (-u) 'case unquoted' and 'for x in unquoted'
206 parse_dollar (-u) Allow bare $ to mean \$ (maybe $/d+/)
207 parse_dbracket (-u) Is legacy [[ allowed?
208 parse_dparen (-u) Is (( legacy arithmetic allowed?
209 parse_ignored (-u) Parse, but ignore, certain redirects
210 parse_sh_arith (-u) Allow legacy shell arithmetic
211 expand_aliases (-u) Whether aliases are expanded
212 X copy_env (-u) Use $[ENV.PYTHONPATH] when false
213 X old_builtins (-u) local/declare/etc. pushd/popd/dirs
214 ... source unset printf [un]alias
215 ... getopts
216 X old_syntax (-u) [[ $(( )) ( ) ${x%prefix}
217 ${a[@]} $$
218 [Compatibility] eval_unsafe_arith Allow dynamically parsed a[$(echo 42)]
219 verbose_errexit Whether to print detailed errors
220 [More Options] _allow_command_sub To implement strict_errexit, eval_unsafe_arith
221 _allow_process_sub To implement strict_errexit
222 dynamic_scope To implement 'proc'
223 _no_debug_trap Used in pipelines in job control shell
224```
225
226<h2 id="special-var">
227 Special Variables (<a class="group-link" href="chap-special-var.html">special-var</a>)
228</h2>
229
230```chapter-links-special-var
231 [YSH Vars] ARGV X ENV X _ESCAPE
232 _this_dir
233 [YSH Status] _status _error
234 _pipeline_status _process_sub_status
235 [YSH Tracing] SHX_indent SHX_punct SHX_pid_str
236 [YSH read] _reply
237 [History] YSH_HISTFILE
238 [Oils VM] OILS_VERSION
239 OILS_GC_THRESHOLD OILS_GC_ON_EXIT
240 OILS_GC_STATS OILS_GC_STATS_FD
241X [Wok] _filename _line
242X [Builtin Sub] _buffer
243```
244
245<h2 id="type-method">
246 Builtin Types and Methods (<a class="group-link" href="chap-type-method.html">type-method</a>)
247</h2>
248
249```chapter-links-type-method
250 [Primitive] Bool Int Float Str Slice Range
251 [Str] X find(eggex) replace()
252 trim() trimStart() trimEnd()
253 startsWith() endsWith()
254 upper() lower() # ascii or unicode
255 search() leftMatch()
256 [Match] group() start() end()
257 X groups() X groupDict()
258 [List] append() pop() extend() indexOf()
259 X insert() X remove() reverse()
260 [Dict] keys() values() X get() X erase()
261 X inc() X accum()
262X [Func] name() location() toJson()
263X [Proc] name() location() toJson()
264X [Module] name() filename()
265 [Place] setValue()
266 [IO] X eval() X captureStdout()
267 promptVal()
268 X time() X strftime()
269 X glob()
270 [Quotation] Expr X Template Command
271 [Code] BuiltinFunc BuiltinMethod
272X [Guts] heapId()
273```
274
275<h2 id="builtin-func">
276 Builtin Functions (<a class="group-link" href="chap-builtin-func.html">builtin-func</a>)
277</h2>
278
279```chapter-links-builtin-func
280 [Values] len() type() X repeat()
281 [Conversions] bool() int() float() str() list() dict()
282 X chr() X ord() X runes()
283X [Str] strcmp() X split() shSplit()
284 [List] join() any() all()
285 [Collections] X copy() X deepCopy()
286 [Word] glob() maybe()
287 [Math] abs() max() min() X round() sum()
288 [Serialize] toJson() fromJson()
289 toJson8() fromJson8()
290X [J8 Decode] J8.Bool() J8.Int() ...
291X [Codecs] quoteUrl() quoteHtml() quoteSh() quoteC()
292 quoteMake() quoteNinja()
293 [Pattern] _group() _start() _end()
294 [Introspection] shvarGet() evalExpr()
295 [Hay Config] parseHay() evalHay()
296X [Wok] _field()
297X [Hashing] sha1dc() sha256()
298```
299
300<h2 id="plugin">
301 Plugins and Hooks (<a class="group-link" href="chap-plugin.html">plugin</a>)
302</h2>
303
304```chapter-links-plugin
305 [YSH] renderPrompt()
306```