| 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 | [Atoms] Null null
|
| 43 | Bool expr/true expr/false
|
| 44 | [Numbers] Int
|
| 45 | Float
|
| 46 | Range
|
| 47 | [String] Str find() findLast()
|
| 48 | contains() replace()
|
| 49 | trim() trimStart() trimEnd()
|
| 50 | startsWith() endsWith()
|
| 51 | upper() lower()
|
| 52 | search() leftMatch()
|
| 53 | split() lines()
|
| 54 | [Patterns] Eggex
|
| 55 | Match group() start() end()
|
| 56 | X groups() X groupDict()
|
| 57 | [Containers] List List/append() pop() extend()
|
| 58 | indexOf() lastIndexOf() X includes()
|
| 59 | insert() remove()
|
| 60 | reverse() List/clear()
|
| 61 | Dict erase() Dict/clear() append()
|
| 62 | X update() inc()
|
| 63 | Place setValue()
|
| 64 | [Code Types] Func
|
| 65 | BuiltinFunc
|
| 66 | BoundFunc
|
| 67 | Proc docComment()
|
| 68 | BuiltinProc
|
| 69 | [Objects] Obj __invoke__ new
|
| 70 | X __call__ __index__ X __str__
|
| 71 | [Reflection] Command sourceCode()
|
| 72 | Expr
|
| 73 | Frame
|
| 74 | DebugFrame toString()
|
| 75 | io stdin io/eval() io/evalExpr()
|
| 76 | captureStdout() captureAll() promptVal()
|
| 77 | X time() X strftime() glob()
|
| 78 | libcGlob()
|
| 79 | vm getFrame() getDebugStack() id()
|
| 80 | ```
|
| 81 |
|
| 82 | <h2 id="builtin-func">
|
| 83 | Builtin Functions <a class="group-link" href="chap-builtin-func.html">builtin-func</a>
|
| 84 | </h2>
|
| 85 |
|
| 86 | ```chapter-links-builtin-func
|
| 87 | [Values] len() func/type()
|
| 88 | [Conversions] bool() int() float()
|
| 89 | str() list() dict()
|
| 90 | X runes() X encodeRunes()
|
| 91 | X bytes() X encodeBytes()
|
| 92 | [Str] strcmp()
|
| 93 | [List] join()
|
| 94 | [Dict] keys() values() get()
|
| 95 | [Float] floatsEqual() X isinf() X isnan()
|
| 96 | [Obj] first() rest() get()
|
| 97 | [Word] maybe() shSplit()
|
| 98 | [Serialize] toJson() fromJson()
|
| 99 | toJson8() fromJson8()
|
| 100 | X toJ8Line() X fromJ8Line()
|
| 101 | [Pattern] _group() _start() _end()
|
| 102 | [Reflection] func/eval() func/evalExpr()
|
| 103 | [Introspect] shvarGet() getVar() setVar()
|
| 104 | parseCommand() X parseExpr() X bindFrame()
|
| 105 | [Hay Config] parseHay() evalHay()
|
| 106 | X [Hashing] sha1dc() sha256()
|
| 107 | ```
|
| 108 |
|
| 109 | <!-- ideas
|
| 110 | More quoting:
|
| 111 |
|
| 112 | quoteC() quotePython() - can we make these ALWAYS work?
|
| 113 | - They can be like J8 b'' strings?
|
| 114 |
|
| 115 | quoteMake() quoteNinja()
|
| 116 |
|
| 117 | quoteSql() - doubling up ''
|
| 118 | quoteCsv() - doubling up ""
|
| 119 |
|
| 120 | X [Wok] _field()
|
| 121 | -->
|
| 122 |
|
| 123 | <h2 id="builtin-cmd">
|
| 124 | Builtin Commands <a class="group-link" href="chap-builtin-cmd.html">builtin-cmd</a>
|
| 125 | </h2>
|
| 126 |
|
| 127 | <!-- linkify_stop_col is 42 -->
|
| 128 |
|
| 129 | ```chapter-links-builtin-cmd_42
|
| 130 | [Memory] cmd/append Add elements to end of array
|
| 131 | pp value proc test_
|
| 132 | asdl_ cell_ X gc-stats_
|
| 133 | [Handle Errors] error error 'failed' (status=2)
|
| 134 | try Run with errexit, set _error
|
| 135 | failed Test if _error.code !== 0
|
| 136 | boolstatus Enforce 0 or 1 exit status
|
| 137 | assert assert [42 === f(x)]
|
| 138 | [Shell State] ysh-cd ysh-shopt compatible, and takes a block
|
| 139 | shvar Temporary modify global settings
|
| 140 | ctx Share and update a temporary "context"
|
| 141 | push-registers Save registers like $?, PIPESTATUS
|
| 142 | [Word Lookup] invoke Run a command, and control name lookup
|
| 143 | runproc Run a proc; use as main entry point
|
| 144 | X extern Run an external command, with an ENV
|
| 145 | [Modules]
|
| 146 | source-guard guard against duplicate 'source'
|
| 147 | is-main false when sourcing a file
|
| 148 | use create a module Obj from a source file
|
| 149 | [I/O] ysh-read flags --all, -0
|
| 150 | ysh-echo no -e -n with simple_echo
|
| 151 | ysh-test --file --true etc.
|
| 152 | ysh-wait wait --all --verbose
|
| 153 | write Like echo, with --, --sep, --end
|
| 154 | fork forkwait Replace & and (), and takes a block
|
| 155 | redir Run a block, with redirects
|
| 156 | [Run Code] ysh-trap
|
| 157 | [Private] cat rm POSIX-compatible
|
| 158 | sleep
|
| 159 | [Hay Config] hay haynode For DSLs and config files
|
| 160 | [Completion] compadjust compexport
|
| 161 | [Data Formats] json read write
|
| 162 | json8 read write
|
| 163 | ```
|
| 164 |
|
| 165 | <h2 id="stdlib">
|
| 166 | Standard Library<a class="group-link" href="chap-stdlib.html">stdlib</a>
|
| 167 | </h2>
|
| 168 |
|
| 169 | ```chapter-links-stdlib
|
| 170 | [math] abs() max() min() X round()
|
| 171 | sum()
|
| 172 | [list] all() any() repeat()
|
| 173 | [yblocks] yb-capture yb-capture-2
|
| 174 | [args] parser flag arg rest
|
| 175 | parseArgs()
|
| 176 | [binascii] X toBase16() X fromBase16()
|
| 177 | X toBase64() X fromBase64()
|
| 178 | ```
|
| 179 |
|
| 180 | <!-- linkify_stop_col is 42 -->
|
| 181 |
|
| 182 | Design for streams and tables (awk/xargs/dplyr):
|
| 183 |
|
| 184 | ```chapter-links-stdlib_42
|
| 185 | X [Lines] slurp-by combine adjacent lines into cells
|
| 186 | X [Awk] each-line --j8 --max-jobs (Str, Template, Block)
|
| 187 | each-row --max-jobs (Str, Template, Block)
|
| 188 | each-word xargs-like splitting, similar to IFS too
|
| 189 | split-by (str=\n, ifs=':', pattern=/s+/)
|
| 190 | if-split-by only lines that match
|
| 191 | chop alias for split-by (pattern=/s+/)
|
| 192 | must-match (/ <capture d+> </capture w+> /)
|
| 193 | if-match only lines that match
|
| 194 | X [Table Create] table def &place or print TSV8
|
| 195 | table parse --by-row --by-col (&place), TSV or TSV8
|
| 196 | table/cols cols name age, or name:Str age:Int
|
| 197 | types type Str Int
|
| 198 | attr attr units - secs
|
| 199 | row emit row
|
| 200 | table cat concatenate TSV8
|
| 201 | table align to ssv8
|
| 202 | table tabify to tsv8 (similar to table parse)
|
| 203 | table header cols = :|name age|, types = :|Str Int|, ...
|
| 204 | table slice e.g. slice (1, -1) slice (5, 7)
|
| 205 | table to-tsv lose type info, and error on \t in cells
|
| 206 | X [Table Ops] where subset of rows; dplyr filter()
|
| 207 | pick subset of columns ('select' taken by shell)
|
| 208 | mutate [average = count / sum]
|
| 209 | transmute drop columns that are used
|
| 210 | rename (bytes='bytes', path='filename')
|
| 211 | group-by add a column with a group ID [ext]
|
| 212 | sort-by sort by columns; dplyr arrange() [ext]
|
| 213 | summary count/sum, histogram, any/all, reduce, ...
|
| 214 | ```
|
| 215 |
|
| 216 | <!--
|
| 217 | Naming ideas:
|
| 218 |
|
| 219 | X [External Lang] BEGIN END when (awk)
|
| 220 | rule (make) each (xargs) fs (find)
|
| 221 | -->
|
| 222 |
|
| 223 | <h2 id="front-end">
|
| 224 | Front End <a class="group-link" href="chap-front-end.html">front-end</a>
|
| 225 | </h2>
|
| 226 |
|
| 227 | ```chapter-links-front-end
|
| 228 | [Usage] oils-usage ysh-usage shell-flags
|
| 229 | config startup line-editing
|
| 230 | exit-codes
|
| 231 | [Lexing] comment # line-continuation \ ascii-whitespace [ \t\r\n]
|
| 232 | [Lexing] doc-comment ### multiline-command ...
|
| 233 | [Tools] cat-em syntax-tree
|
| 234 | ```
|
| 235 |
|
| 236 | <h2 id="cmd-lang">
|
| 237 | Command Language <a class="group-link" href="chap-cmd-lang.html">cmd-lang</a>
|
| 238 | </h2>
|
| 239 |
|
| 240 | <!-- linkify_stop_col is 33 -->
|
| 241 |
|
| 242 | ```chapter-links-cmd-lang_33
|
| 243 | [Commands] simple-command
|
| 244 | command-lookup-order
|
| 245 | ysh-prefix-binding
|
| 246 | semicolon ;
|
| 247 | [Redirects] ysh-here-str read <<< '''
|
| 248 | [YSH Simple] typed-arg json write (x)
|
| 249 | lazy-expr-arg assert [42 === x]
|
| 250 | block-arg cd /tmp { echo $PWD }; cd /tmp (; ; blockexpr)
|
| 251 | [YSH Cond] ysh-case case (x) { *.py { echo 'python' } }
|
| 252 | ysh-if if (x > 0) { echo }
|
| 253 | [YSH Iter] ysh-for for i, item in (mylist) { echo }
|
| 254 | ysh-while while (x > 0) { echo }
|
| 255 | ```
|
| 256 |
|
| 257 | <!-- TODO: move YSH command topics to the chapter below -->
|
| 258 |
|
| 259 | <h2 id="ysh-cmd">
|
| 260 | YSH Command Language Keywords <a class="group-link" href="chap-ysh-cmd.html">ysh-cmd</a>
|
| 261 | </h2>
|
| 262 |
|
| 263 | ```chapter-links-ysh-cmd_33
|
| 264 | [Assignment] const var Declare variables
|
| 265 | setvar setvar a[i] = 42
|
| 266 | setglobal setglobal d.key = 'foo'
|
| 267 | [Expression] equal = = 1 + 2*3
|
| 268 | call call mylist->append(42)
|
| 269 | [Definitions] proc proc p (s, ...rest) {
|
| 270 | typed proc p (; typed, ...rest; n=0; b) {
|
| 271 | func func f(x; opt1, opt2) { return (x + 1) }
|
| 272 | ysh-return return (myexpr)
|
| 273 | ```
|
| 274 |
|
| 275 | <h2 id="expr-lang">
|
| 276 | Expression Language and Assignments <a class="group-link" href="chap-expr-lang.html">expr-lang</a>
|
| 277 | </h2>
|
| 278 |
|
| 279 | <!-- linkify_stop_col is 33 -->
|
| 280 |
|
| 281 | ```chapter-links-expr-lang_33
|
| 282 | [Assignment] assign =
|
| 283 | aug-assign += -= *= /= **= //= %=
|
| 284 | &= |= ^= <<= >>=
|
| 285 | [Literals] atom-literal null true false
|
| 286 | int-literal 42 65_536 0xFF 0o755 0b10
|
| 287 | float-literal 3.14 1.5e-10
|
| 288 | X num-suffix 42 K Ki M Mi G Gi T Ti / ms us
|
| 289 | char-literal \\ \t \" \y00 \u{3bc}
|
| 290 | ysh-string "x is $x" $"x is $x" r'[a-z]\n'
|
| 291 | u'line\n' b'byte \yff'
|
| 292 | triple-quoted """ $""" r''' u''' b'''
|
| 293 | list-literal ['one', 'two', 3] :| unquoted words |
|
| 294 | dict-literal {name: 'bob'} {a, b}
|
| 295 | range 1 ..< n 1 ..= n
|
| 296 | block-expr ^(echo $PWD)
|
| 297 | expr-literal ^[1 + 2*3]
|
| 298 | str-template ^"$a and $b" for Str.replace()
|
| 299 | expr-sub $[myobj]
|
| 300 | expr-splice @[myobj]
|
| 301 | [Operators] op-precedence Like Python
|
| 302 | concat s1 ++ s2, L1 ++ L2
|
| 303 | ysh-equals === !== ~== is, is not
|
| 304 | ysh-in in, not in
|
| 305 | ysh-compare < <= > >= (numbers only)
|
| 306 | ysh-logical not and or
|
| 307 | ysh-arith + - * / // % **
|
| 308 | ysh-unary + -
|
| 309 | ysh-bitwise ~ & | ^ << >>
|
| 310 | ysh-ternary '+' if x >= 0 else '-'
|
| 311 | ysh-index s[0] mylist[3] mydict['key']
|
| 312 | ysh-attr mydict.key mystr.startsWith('x')
|
| 313 | ysh-slice a[1:-1] s[1:-1]
|
| 314 | ysh-func-call f(x, y, ...pos; n=1, ...named)
|
| 315 | thin-arrow mylist->pop()
|
| 316 | fat-arrow mylist => join() => upper()
|
| 317 | match-ops ~ !~ ~~ !~~
|
| 318 | [Eggex] re-literal / d+ ; re-flags ; ERE /
|
| 319 | re-primitive %zero 'sq'
|
| 320 | class-literal [c a-z 'abc' @str_var \\ \y01 \u{3bc}]
|
| 321 | re-chars \y01 \u{3bc}
|
| 322 | named-class dot digit space word d s w
|
| 323 | re-repeat d? d* d+ d{3} d{2,4}
|
| 324 | re-compound seq1 seq2 alt1|alt2 (expr1 expr2)
|
| 325 | re-capture <capture d+ as name: int>
|
| 326 | re-splice Subpattern @subpattern
|
| 327 | re-flags reg_icase reg_newline
|
| 328 | X re-multiline ///
|
| 329 | ```
|
| 330 |
|
| 331 | <h2 id="word-lang">
|
| 332 | Word Language <a class="group-link" href="chap-word-lang.html">word-lang</a>
|
| 333 | </h2>
|
| 334 |
|
| 335 | <!-- linkify_stop_col is 34 -->
|
| 336 |
|
| 337 | ```chapter-links-word-lang_34
|
| 338 | [Glob] ysh-glob *.py
|
| 339 | [Joining] ysh-word-join --flag='value' PATH="value"
|
| 340 | [Quotes] ysh-string "x is $x" $"x is $x" r'[a-z]\n'
|
| 341 | u'line\n' b'byte \yff'
|
| 342 | triple-quoted """ $""" r''' u''' b'''
|
| 343 | X tagged-str "<span id=$x>"html
|
| 344 | [Substitutions] expr-sub echo $[42 + a[i]]
|
| 345 | expr-splice echo @[split(x)]
|
| 346 | var-splice @myarray @ARGV
|
| 347 | command-sub $(date)
|
| 348 | command-splice @(cat my-j8-lines.txt)
|
| 349 | [Formatting] X ysh-printf ${x %.3f}
|
| 350 | X ysh-format ${x|html}
|
| 351 | ```
|
| 352 |
|
| 353 | <h2 id="mini-lang">
|
| 354 | Other Mini Languages <a class="group-link" href="chap-mini-lang.html">mini-lang</a>
|
| 355 | </h2>
|
| 356 |
|
| 357 | <!-- linkify_stop_col is 33 -->
|
| 358 |
|
| 359 | ```chapter-links-mini-lang_33
|
| 360 | [Patterns] glob-pat *.py
|
| 361 | [Other Sublang] braces {alice,bob}@example.com
|
| 362 | ```
|
| 363 |
|
| 364 | <h2 id="option">
|
| 365 | Global Shell Options <a class="group-link" href="chap-option.html">option</a>
|
| 366 | </h2>
|
| 367 |
|
| 368 | ```chapter-links-option
|
| 369 | [Optimize] rewrite_extern
|
| 370 | [Groups] strict:all ysh:upgrade ysh:all
|
| 371 | [YSH Details] opts-redefine opts-internal
|
| 372 | ```
|
| 373 |
|
| 374 | <h2 id="special-var">
|
| 375 | Special Variables <a class="group-link" href="chap-special-var.html">special-var</a>
|
| 376 | </h2>
|
| 377 |
|
| 378 | ```chapter-links-special-var
|
| 379 | [YSH Vars] ARGV ENV
|
| 380 | __defaults__ __builtins__ X __sh_function__
|
| 381 | _this_dir
|
| 382 | [YSH Status] _error
|
| 383 | _pipeline_status _process_sub_status
|
| 384 | [YSH Tracing] SHX_indent SHX_punct SHX_pid_str
|
| 385 | [YSH read] _reply
|
| 386 | [Oils VM] OILS_VERSION LIB_YSH
|
| 387 | OILS_GC_THRESHOLD OILS_GC_ON_EXIT
|
| 388 | OILS_GC_STATS OILS_GC_STATS_FD
|
| 389 | OILS_LOCALE_OK
|
| 390 | [libc locale] ysh-locale
|
| 391 | [Interactive] OILS_COMP_UI YSH_HISTFILE
|
| 392 | [Float] NAN INFINITY
|
| 393 | [Module] __provide__
|
| 394 | [Other Env] HOME PATH
|
| 395 | ```
|
| 396 |
|
| 397 | <!--
|
| 398 | ENV vars read by interpreter:
|
| 399 |
|
| 400 | ENV.{PS1,PS4,YSH_HISTFILE}
|
| 401 |
|
| 402 | - renderPrompt() takes precedence over PS1
|
| 403 | - SHX_* takes precedence over PS4
|
| 404 | - TODO: we may want to redo this - it is too confusing
|
| 405 | - HOME is read for ~, but it is not SET
|
| 406 | - we should read ENV.HOME
|
| 407 | - should be populate ENV.HOME?
|
| 408 |
|
| 409 | Notes:
|
| 410 | [Module] __E__ - for closures
|
| 411 | X [Builtin Sub] _buffer
|
| 412 |
|
| 413 | Ideas:
|
| 414 | X [Wok] _filename _line _line_num
|
| 415 | -->
|
| 416 |
|
| 417 | <h2 id="plugin">
|
| 418 | Plugins and Hooks <a class="group-link" href="chap-plugin.html">plugin</a>
|
| 419 | </h2>
|
| 420 |
|
| 421 | ```chapter-links-plugin
|
| 422 | [YSH] renderPrompt()
|
| 423 | ```
|