OILS / doc / ref / chap-ysh-cmd.md View on Github | oils.pub

174 lines, 104 significant
1---
2title: YSH Command Language Keywords (Oils Reference)
3all_docs_url: ..
4body_css_class: width40
5default_highlighter: oils-sh
6preserve_anchor_case: yes
7---
8
9<div class="doc-ref-header">
10
11[Oils Reference](index.html) &mdash;
12Chapter **YSH Command Language Keywords**
13
14</div>
15
16This 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
27Binds a name to a YSH expression on the right, with a **dynamic** check to
28prevent mutation.
29
30 const c = 'mystr' # equivalent to readonly c=mystr
31 const pat = / digit+ / # an eggex, with no shell equivalent
32
33If you try to re-declare or mutate the name, the shell will fail with a runtime
34error. `const` uses the same mechanism as the `readonly` builtin.
35
36Consts should only appear at the top-level, and can't appear within `proc` or
37`func`.
38
39### var
40
41Initializes 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
46It's either global or scoped to the current function.
47
48You can bind multiple variables:
49
50 var flag, i = parseArgs(spec, ARGV)
51
52 var x, y = 42, 43
53
54You can omit the right-hand side:
55
56 var x, y # implicitly initialized to null
57
58### setvar
59
60At the top-level, setvar creates or mutates a variable.
61
62 setvar gFoo = 'mutable'
63
64Inside 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
71You can mutate a List location:
72
73 setvar a[42] = 'foo'
74
75Or a Dict location:
76
77 setvar d['key'] = 43
78 setvar d.key = 43 # same thing
79
80You can use any of these these augmented assignment operators
81
82 += -= *= /= **= //= %=
83 &= |= ^= <<= >>=
84
85Examples:
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
96Creates or mutates a global variable. Has the same syntax as `setvar`.
97
98
99## Expression
100
101### equal
102
103The `=` keyword evaluates an expression and shows the result:
104
105 oil$ = 1 + 2*3
106 (Int) 7
107
108It's meant to be used interactively. Think of it as an assignment with no
109variable on the left.
110
111### call
112
113The `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
124Procs are like POSIX shell "functions", but with named parameters.
125
126Instead of using shell's "dynamic scope" rules, they obey lexical scope. In
127other words, they are closures.
128
129Here's a simple proc:
130
131 proc my-cp (src, dest) {
132 cp --verbose --verbose $src $dest
133 }
134
135Here's the most general form:
136
137 proc p (
138 w1, w2, ...rest_words;
139 t1, t2, ...rest_typed;
140 n1, n2, ...rest_named;
141 block) {
142
143 = w1
144 = t1
145 = n1
146 = block
147 }
148
149See the [Guide to Procs and Funcs](../proc-func.html) for details.
150
151Compare with [sh-func](chap-builtin-cmd.html#sh-func).
152
153### func
154
155Funcs are pure functions, in the style of Python and JavaScript:
156
157 func add(x, y) {
158 return (x + y)
159 }
160
161 echo $[add(3, 2)] # => 5
162
163Like procs, funcs are closures.
164
165See the [Guide to Procs and Funcs](../proc-func.html) for details.
166
167### ysh-return
168
169To return an expression, wrap it in `()` as usual:
170
171 func inc(x) {
172 return (x + 1)
173 }
174