OILS / doc / ref / chap-ysh-cmd.md View on Github | oilshell.org

170 lines, 102 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 shell-like functions, but with named parameters, and without dynamic
125scope.
126
127Here's a simple proc:
128
129 proc my-cp (src, dest) {
130 cp --verbose --verbose $src $dest
131 }
132
133Here'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
147See the [Guide to Procs and Funcs](../proc-func.html) for details.
148
149Compare with [sh-func](chap-builtin-cmd.html#sh-func).
150
151### func
152
153Define pure functions, in the style of Python and JavaScript:
154
155 func add(x, y) {
156 return (x + y)
157 }
158
159 echo $[add(3, 2)] # => 5
160
161See the [Guide to Procs and Funcs](../proc-func.html) for details.
162
163### ysh-return
164
165To return an expression, wrap it in `()` as usual:
166
167 func inc(x) {
168 return (x + 1)
169 }
170