1 | ---
|
2 | title: YSH Command Language Keywords (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 **YSH Command Language Keywords**
|
13 |
|
14 | </div>
|
15 |
|
16 | This chapter describes new YSH keywords in the command language.
|
17 |
|
18 | <span class="in-progress">(in progress)</span>
|
19 |
|
20 | <div id="dense-toc">
|
21 | </div>
|
22 |
|
23 | ## Assignment
|
24 |
|
25 | ### const
|
26 |
|
27 | Binds a name to a YSH expression on the right, with a **dynamic** check to
|
28 | prevent mutation.
|
29 |
|
30 | const c = 'mystr' # equivalent to readonly c=mystr
|
31 | const pat = / digit+ / # an eggex, with no shell equivalent
|
32 |
|
33 | If you try to re-declare or mutate the name, the shell will fail with a runtime
|
34 | error. `const` uses the same mechanism as the `readonly` builtin.
|
35 |
|
36 | Consts should only appear at the top-level, and can't appear within `proc` or
|
37 | `func`.
|
38 |
|
39 | ### var
|
40 |
|
41 | Initializes a name to a YSH expression.
|
42 |
|
43 | var s = 'mystr' # equivalent to declare s=mystr
|
44 | var pat = / digit+ / # an eggex, with no shell equivalent
|
45 |
|
46 | It's either global or scoped to the current function.
|
47 |
|
48 | You can bind multiple variables:
|
49 |
|
50 | var flag, i = parseArgs(spec, ARGV)
|
51 |
|
52 | var x, y = 42, 43
|
53 |
|
54 | You can omit the right-hand side:
|
55 |
|
56 | var x, y # implicitly initialized to null
|
57 |
|
58 | ### setvar
|
59 |
|
60 | At the top-level, setvar creates or mutates a variable.
|
61 |
|
62 | setvar gFoo = 'mutable'
|
63 |
|
64 | Inside a func or proc, it mutates a local variable declared with var.
|
65 |
|
66 | proc p {
|
67 | var x = 42
|
68 | setvar x = 43
|
69 | }
|
70 |
|
71 | You can mutate a List location:
|
72 |
|
73 | setvar a[42] = 'foo'
|
74 |
|
75 | Or a Dict location:
|
76 |
|
77 | setvar d['key'] = 43
|
78 | setvar d.key = 43 # same thing
|
79 |
|
80 | You can use any of these these augmented assignment operators
|
81 |
|
82 | += -= *= /= **= //= %=
|
83 | &= |= ^= <<= >>=
|
84 |
|
85 | Examples:
|
86 |
|
87 | setvar x += 2 # increment by 2
|
88 |
|
89 | setvar a[42] *= 2 # multiply by 2
|
90 |
|
91 | setvar d.flags |= 0b0010_000 # set a flag
|
92 |
|
93 |
|
94 | ### setglobal
|
95 |
|
96 | Creates or mutates a global variable. Has the same syntax as `setvar`.
|
97 |
|
98 |
|
99 | ## Expression
|
100 |
|
101 | ### equal
|
102 |
|
103 | The `=` keyword evaluates an expression and shows the result:
|
104 |
|
105 | oil$ = 1 + 2*3
|
106 | (Int) 7
|
107 |
|
108 | It's meant to be used interactively. Think of it as an assignment with no
|
109 | variable on the left.
|
110 |
|
111 | ### call
|
112 |
|
113 | The `call` keyword evaluates an expression and throws away the result:
|
114 |
|
115 | var x = :| one two |
|
116 | call x->append('three')
|
117 | call x->append(['typed', 'data'])
|
118 |
|
119 |
|
120 | ## Definitions
|
121 |
|
122 | ### proc
|
123 |
|
124 | Procs are shell-like functions, but with named parameters, and without dynamic
|
125 | scope.
|
126 |
|
127 | Here's a simple proc:
|
128 |
|
129 | proc my-cp (src, dest) {
|
130 | cp --verbose --verbose $src $dest
|
131 | }
|
132 |
|
133 | Here's the most general form:
|
134 |
|
135 | proc p (
|
136 | w1, w2, ...rest_words;
|
137 | t1, t2, ...rest_typed;
|
138 | n1, n2, ...rest_named;
|
139 | block) {
|
140 |
|
141 | = w1
|
142 | = t1
|
143 | = n1
|
144 | = block
|
145 | }
|
146 |
|
147 | See the [Guide to Procs and Funcs](../proc-func.html) for details.
|
148 |
|
149 | Compare with [sh-func](chap-builtin-cmd.html#sh-func).
|
150 |
|
151 | ### func
|
152 |
|
153 | TODO
|
154 |
|
155 | ### ysh-return
|
156 |
|
157 | To return an expression, wrap it in `()` as usual:
|
158 |
|
159 | func inc(x) {
|
160 | return (x + 1)
|
161 | }
|
162 |
|