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