1 | ---
|
2 | title: Command Language (Oils Reference)
|
3 | all_docs_url: ..
|
4 | body_css_class: width40
|
5 | default_highlighter: oils-sh
|
6 | preserve_anchor_case: yes
|
7 | ---
|
8 |
|
9 | <div class="doc-ref-header">
|
10 |
|
11 | [Oils Reference](index.html) —
|
12 | Chapter **Command Language**
|
13 |
|
14 | </div>
|
15 |
|
16 | This chapter describes the command language for OSH, and some YSH extensions.
|
17 |
|
18 | <span class="in-progress">(in progress)</span>
|
19 |
|
20 | <div id="dense-toc">
|
21 | </div>
|
22 |
|
23 | ## Quick Sketch: What's a Command?
|
24 |
|
25 | OSH:
|
26 |
|
27 | print-files() {
|
28 | for name in *.py; do
|
29 | if test -x "$name"; then
|
30 | echo "$name is executable"
|
31 | fi
|
32 | done
|
33 | }
|
34 |
|
35 | YSH:
|
36 |
|
37 | proc print-files {
|
38 | for name in *.py {
|
39 | if test -x $name { # no quotes needed
|
40 | echo "$name is executable"
|
41 | }
|
42 | }
|
43 | }
|
44 |
|
45 |
|
46 | <h2 id="Commands">Commands</h2>
|
47 |
|
48 | <h3 id="simple-command" class="osh-ysh-topic">simple-command</h3>
|
49 |
|
50 | Commands are composed of words. The first word may be the name of
|
51 |
|
52 | 1. A builtin shell command
|
53 | 1. A YSH `proc` or shell "function"
|
54 | 1. A Hay node declared with `hay define`
|
55 | 1. An external command
|
56 | 1. An alias
|
57 |
|
58 | Examples:
|
59 |
|
60 | echo hi # a shell builtin doesn't start a process
|
61 | ls /usr/bin ~/src # starts a new process
|
62 | myproc "hello $name"
|
63 | myshellfunc "hello $name"
|
64 | myalias -l
|
65 | <!-- TODO: document lookup order -->
|
66 |
|
67 | Redirects are also allowed in any part of the command:
|
68 |
|
69 | echo 'to stderr' >&2
|
70 | echo >&2 'to stderr'
|
71 |
|
72 | echo 'to file' > out.txt
|
73 | echo > out.txt 'to file'
|
74 |
|
75 | <h3 id="semicolon" class="osh-ysh-topic">semicolon ;</h3>
|
76 |
|
77 | Run two commands in sequence like this:
|
78 |
|
79 | echo one; echo two
|
80 |
|
81 | or this:
|
82 |
|
83 | echo one
|
84 | echo two
|
85 |
|
86 | <h2 id="Conditional">Conditional</h2>
|
87 |
|
88 | <h3 id="case" class="osh-topic">case</h3>
|
89 |
|
90 | Match a string against a series of glob patterns. Execute code in the section
|
91 | below the matching pattern.
|
92 |
|
93 | path='foo.py'
|
94 | case "$path" in
|
95 | *.py)
|
96 | echo 'python'
|
97 | ;;
|
98 | *.sh)
|
99 | echo 'shell'
|
100 | ;;
|
101 | esac
|
102 |
|
103 | For bash compatibility, the `;;` terminator can be substituted with either:
|
104 |
|
105 | - `;&` - fall through to next arm, ignoring the condition
|
106 | - `;;&` - fall through to next arm, respecting the condition
|
107 |
|
108 | <h3 id="if" class="osh-topic">if</h3>
|
109 |
|
110 | Test if a command exited with status zero (true). If so, execute the
|
111 | corresponding block of code.
|
112 |
|
113 | Shell:
|
114 |
|
115 | if test -d foo; then
|
116 | echo 'foo is a directory'
|
117 | elif test -f foo; then
|
118 | echo 'foo is a file'
|
119 | else
|
120 | echo 'neither'
|
121 | fi
|
122 |
|
123 | YSH:
|
124 |
|
125 | if test -d foo {
|
126 | echo 'foo is a directory'
|
127 | } elif test -f foo {
|
128 | echo 'foo is a file'
|
129 | } else {
|
130 | echo 'neither'
|
131 | }
|
132 |
|
133 | <h3 id="dbracket" class="osh-topic">dbracket [[</h3>
|
134 |
|
135 | Statically parsed boolean expressions, from bash and other shells:
|
136 |
|
137 | x=42
|
138 | if [[ $x -eq 42 ]]; then
|
139 | echo yes
|
140 | fi # => yes
|
141 |
|
142 | Compare with the [test][] builtin, which is dynamically parsed.
|
143 |
|
144 | See [bool-expr][] for the expression syntax.
|
145 |
|
146 | [test]: chap-builtin-cmd.html#test
|
147 | [bool-expr]: chap-mini-lang.html#bool-expr
|
148 |
|
149 |
|
150 | <h3 id="true" class="osh-ysh-topic">true</h3>
|
151 |
|
152 | Do nothing and return status 0.
|
153 |
|
154 | if true; then
|
155 | echo hello
|
156 | fi
|
157 |
|
158 | <h3 id="false" class="osh-ysh-topic">false</h3>
|
159 |
|
160 | Do nothing and return status 1.
|
161 |
|
162 | if false; then
|
163 | echo 'not reached'
|
164 | else
|
165 | echo hello
|
166 | fi
|
167 |
|
168 | <h3 id="colon" class="osh-topic">colon :</h3>
|
169 |
|
170 | Like `true`: do nothing and return status 0.
|
171 |
|
172 | <h3 id="bang" class="osh-ysh-topic">bang !</h3>
|
173 |
|
174 | Invert an exit code:
|
175 |
|
176 | if ! test -d /tmp; then
|
177 | echo "No temp directory
|
178 | fi
|
179 |
|
180 | <h3 id="and" class="osh-ysh-topic">and &&</h3>
|
181 |
|
182 | mkdir -p /tmp && cp foo /tmp
|
183 |
|
184 | <h3 id="or" class="osh-ysh-topic">or ||</h3>
|
185 |
|
186 | ls || die "failed"
|
187 |
|
188 | <h2 id="Iteration">Iteration</h2>
|
189 |
|
190 | <h3 id="while" class="osh-ysh-topic">while</h3>
|
191 |
|
192 | POSIX
|
193 |
|
194 | <h3 id="until" class="osh-topic">until</h3>
|
195 |
|
196 | POSIX
|
197 |
|
198 | <h3 id="for" class="osh-ysh-topic">for</h3>
|
199 |
|
200 | For loops iterate over words.
|
201 |
|
202 | YSH style:
|
203 |
|
204 | var mystr = 'one'
|
205 | var myarray = :| two three |
|
206 |
|
207 | for i in $mystr @myarray *.py {
|
208 | echo $i
|
209 | }
|
210 |
|
211 |
|
212 | Shell style:
|
213 |
|
214 | local mystr='one'
|
215 | local myarray=(two three)
|
216 |
|
217 | for i in "mystr" "${myarray[@]}" *.py; do
|
218 | echo $i
|
219 | done
|
220 |
|
221 | Both fragments output 3 lines and then Python files on remaining lines.
|
222 |
|
223 | <h3 id="for-expr-sh" class="osh-topic">for-expr-sh</h3>
|
224 |
|
225 | A bash/ksh construct:
|
226 |
|
227 | for (( i = 0; i < 5; ++i )); do
|
228 | echo $i
|
229 | done
|
230 |
|
231 | <h2 id="Control Flow">Control Flow</h2>
|
232 |
|
233 | These are keywords in Oils, not builtins!
|
234 |
|
235 | ### break
|
236 |
|
237 | Break out of a loop. (Not used for case statements!)
|
238 |
|
239 | ### continue
|
240 |
|
241 | Continue to the next iteration of a loop.
|
242 |
|
243 | ### return
|
244 |
|
245 | Return from a function.
|
246 |
|
247 | ### exit
|
248 |
|
249 | Exit the shell process with the given status:
|
250 |
|
251 | exit 2
|
252 |
|
253 | <h2 id="Grouping">Grouping</h2>
|
254 |
|
255 | ### sh-func
|
256 |
|
257 | POSIX:
|
258 |
|
259 | f() {
|
260 | echo args "$@"
|
261 | }
|
262 | f 1 2 3
|
263 |
|
264 | ### sh-block
|
265 |
|
266 | POSIX:
|
267 |
|
268 | { echo one; echo two; }
|
269 |
|
270 | The trailing `;` is necessary in OSH, but not YSH. In YSH, `parse_brace` makes
|
271 | `}` is more of a special word.
|
272 |
|
273 |
|
274 | ### subshell
|
275 |
|
276 | ( echo one; echo two )
|
277 |
|
278 | In YSH, use [forkwait](chap-builtin-cmd.html#forkwait) instead of parentheses.
|
279 |
|
280 | <h2 id="Concurrency">Concurrency</h2>
|
281 |
|
282 | ### pipe
|
283 |
|
284 | Pipelines are a traditional POSIX shell construct:
|
285 |
|
286 | ls /tmp | grep ssh | sort
|
287 |
|
288 | Related:
|
289 |
|
290 | - [`PIPESTATUS`]() in OSH
|
291 | - [`_pipeline_status`]() in YSH
|
292 |
|
293 | [PIPESTATUS]: chap-special-var.html#PIPESTATUS
|
294 | [_pipeline_status]: chap-special-var.html#_pipeline_status
|
295 |
|
296 | <h3 id="ampersand" class="osh-topic">ampersand &</h3>
|
297 |
|
298 | Start a command as a background job. Don't wait for it to finish, and return
|
299 | control to the shell.
|
300 |
|
301 | The PID of the job is recorded in the `$!` variable.
|
302 |
|
303 | sleep 1 &
|
304 | echo pid=$!
|
305 | { echo two; sleep 2 } &
|
306 | wait
|
307 | wait
|
308 |
|
309 | In YSH, use the [fork][] builtin.
|
310 |
|
311 | [fork]: chap-builtin-cmd.html#fork
|
312 |
|
313 |
|
314 | <h2 id="Redirects">Redirects</h2>
|
315 |
|
316 | ### redir-file
|
317 |
|
318 | Examples of redirecting the `stdout` of a command:
|
319 |
|
320 | echo foo > out.txt # overwrite out.txt
|
321 | date >> stamp.txt # append to stamp.txt
|
322 |
|
323 | <!--
|
324 | echo foo >| out.txt # clobber the file even if set -o noclobber
|
325 | -->
|
326 |
|
327 | Redirect to the `stdin` of a command:
|
328 |
|
329 | cat < in.txt
|
330 |
|
331 | Redirects are compatible with POSIX and bash, so they take descriptor numbers
|
332 | on the left:
|
333 |
|
334 | make 2> stderr.txt # '2>' is valid, but '2 >' is not
|
335 |
|
336 | Note that the word argument to **file** redirects is evaluated like bash, which
|
337 | is different than other arguments to other redirects:
|
338 |
|
339 | tar -x -z < Python* # glob must expand to exactly 1 file
|
340 | tar -x -z < $myvar # $myvar is split because it's unquoted
|
341 |
|
342 | In other words, it's evaluated **as** a sequence of 1 word, which **produces**
|
343 | zero to N strings. But redirects are only valid when it produces exactly 1
|
344 | string.
|
345 |
|
346 | (Related: YSH uses `shopt --set simple_word_eval`, which means that globs that
|
347 | match nothing evaluate to zero strings, not themselves.)
|
348 |
|
349 | <!-- They also take a file descriptor on the left -->
|
350 |
|
351 |
|
352 | ### redir-desc
|
353 |
|
354 | Redirect to a file descriptor:
|
355 |
|
356 | echo 'to stderr' >&2
|
357 |
|
358 | <!--
|
359 | NOTE: >&2 is just like <&2
|
360 | There's no real difference.
|
361 | -->
|
362 |
|
363 | ### here-doc
|
364 |
|
365 | TODO: unbalanced HTML if we use \<\<?
|
366 |
|
367 | cat <<EOF
|
368 | here doc with $double ${quoted} substitution
|
369 | EOF
|
370 |
|
371 | myfunc() {
|
372 | cat <<-EOF
|
373 | here doc with one tab leading tab stripped
|
374 | EOF
|
375 | }
|
376 |
|
377 | cat <<< 'here string'
|
378 |
|
379 | <!-- TODO: delimiter can be quoted -->
|
380 | <!-- Note: Python's HTML parser thinks <EOF starts a tag -->
|
381 |
|
382 | ## Other Command
|
383 |
|
384 | <h3 id="dparen" class="osh-topic">dparen ((</h3>
|
385 |
|
386 | <h3 id="time" class="osh-ysh-topic">time</h3>
|
387 |
|
388 | time [-p] pipeline
|
389 |
|
390 | Measures the time taken by a command / pipeline. It uses the `getrusage()`
|
391 | function from `libc`.
|
392 |
|
393 | Note that time is a KEYWORD, not a builtin!
|
394 |
|
395 | <!-- Note: bash respects TIMEFORMAT -->
|
396 |
|
397 |
|
398 | ## YSH Simple
|
399 |
|
400 | ### typed-arg
|
401 |
|
402 | Internal commands (procs and builtins) accept typed arguments in parentheses:
|
403 |
|
404 | json write (myobj)
|
405 |
|
406 | Redirects can also appear after the typed args:
|
407 |
|
408 | json write (myobj) >out.txt
|
409 |
|
410 | ### lazy-expr-arg
|
411 |
|
412 | Expressions in brackets like this:
|
413 |
|
414 | assert [42 === x]
|
415 |
|
416 | Are syntactic sugar for:
|
417 |
|
418 | assert (^[42 === x])
|
419 |
|
420 | That is, it's single arg of type `value.Expr`.
|
421 |
|
422 | Redirects can also appear after the lazy typed args:
|
423 |
|
424 | assert [42 ===x] >out.txt
|
425 |
|
426 | ### block-arg
|
427 |
|
428 | Blocks can be passed to simple commands, either literally:
|
429 |
|
430 | cd /tmp {
|
431 | echo $PWD # prints /tmp
|
432 | }
|
433 | echo $PWD
|
434 |
|
435 | Or as an expression:
|
436 |
|
437 | var block = ^(echo $PWD)
|
438 | cd /tmp (; ; block)
|
439 |
|
440 | Note that `cd` has no typed or named arguments, so the two semicolons are
|
441 | preceded by nothing.
|
442 |
|
443 | Compare with [sh-block](#sh-block).
|
444 |
|
445 | Redirects can appear after the block arg:
|
446 |
|
447 | cd /tmp {
|
448 | echo $PWD # prints /tmp
|
449 | } >out.txt
|
450 |
|
451 | ## YSH Cond
|
452 |
|
453 | ### ysh-if
|
454 |
|
455 | Like shell, you can use a command:
|
456 |
|
457 | if test --file $x {
|
458 | echo "$x is a file"
|
459 | }
|
460 |
|
461 | You can also use an expression:
|
462 |
|
463 | if (x > 0) {
|
464 | echo 'positive'
|
465 | }
|
466 |
|
467 | ### ysh-case
|
468 |
|
469 | Like the shell case statement, the Ysh case statement has **string/glob** patterns.
|
470 |
|
471 | var s = 'README.md'
|
472 | case (s) {
|
473 | *.py { echo 'Python' }
|
474 | *.cc | *.h { echo 'C++' }
|
475 | * { echo 'Other' }
|
476 | }
|
477 | # => Other
|
478 |
|
479 | We also generated it to **typed data** within `()`:
|
480 |
|
481 | var x = 43
|
482 | case (x) {
|
483 | (30 + 12) { echo 'the integer 42' }
|
484 | (else) { echo 'neither' }
|
485 | }
|
486 | # => neither
|
487 |
|
488 | The `else` is a special keyword that matches any value.
|
489 |
|
490 | case (s) {
|
491 | / dot* '.md' / { echo 'Markdown' }
|
492 | (else) { echo 'neither' }
|
493 | }
|
494 | # => Markdown
|
495 |
|
496 | ## YSH Iter
|
497 |
|
498 | ### ysh-while
|
499 |
|
500 | Command or expression:
|
501 |
|
502 | var x = 5
|
503 | while (x < 0) {
|
504 | setvar x -= 1
|
505 | }
|
506 |
|
507 | ### ysh-for
|
508 |
|
509 | #### Words
|
510 |
|
511 | This is a shell-style loop over "words":
|
512 |
|
513 | for name in README.md *.py {
|
514 | echo $name
|
515 | }
|
516 | # => README.md
|
517 | # => foo.py
|
518 |
|
519 | You can also ask for the index:
|
520 |
|
521 | for i, name in README.md *.py {
|
522 | echo "$i $name"
|
523 | }
|
524 | # => 0 README.md
|
525 | # => 1 foo.py
|
526 |
|
527 | #### Lines of `stdin`
|
528 |
|
529 | Here's how to iterate over the lines of stdin:
|
530 |
|
531 | for line in (stdin) {
|
532 | echo $line
|
533 | }
|
534 |
|
535 | Likewise, you can ask for the index with `for i, line in (stdin) { ...`.
|
536 |
|
537 | #### Expressions
|
538 |
|
539 | Expressions are enclosed in `()`.
|
540 |
|
541 | Iterating over a `List` or `Range` is like iterating over words or lines:
|
542 |
|
543 | var mylist = [42, 43]
|
544 | for item in (mylist) {
|
545 | echo $item
|
546 | }
|
547 | # => 42
|
548 | # => 43
|
549 |
|
550 | var n = 5
|
551 | for i in (3 .. n) {
|
552 | echo $i
|
553 | }
|
554 | # => 3
|
555 | # => 4
|
556 |
|
557 | However, there are **three** ways of iterating over a `Dict`:
|
558 |
|
559 | for key in (mydict) {
|
560 | echo $key
|
561 | }
|
562 |
|
563 | for key, value in (mydict) {
|
564 | echo "$key $value"
|
565 | }
|
566 |
|
567 | for i, key, value in (mydict) {
|
568 | echo "$i $key $value"
|
569 | }
|
570 |
|
571 | That is, if you ask for two things, you'll get the key and value. If you ask
|
572 | for three, you'll also get the index.
|
573 |
|