1 | ---
|
2 | title: Front End (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 **Front End**
|
13 |
|
14 | </div>
|
15 |
|
16 | This chapter describes command line usage and lexing.
|
17 |
|
18 | <span class="in-progress">(in progress)</span>
|
19 |
|
20 | <div id="dense-toc">
|
21 | </div>
|
22 |
|
23 | <h2 id="usage">Command Line Usage</h2>
|
24 |
|
25 | <h3 id="oils-usage" class="osh-ysh-topic" oils-embed="1">
|
26 | oils-usage
|
27 | </h3>
|
28 |
|
29 | <!-- pre-formatted for help builtin -->
|
30 |
|
31 | ```
|
32 | bin/oils-for-unix is an executable that contains OSH, YSH, and more.
|
33 |
|
34 | Usage: oils-for-unix MAIN_NAME ARG*
|
35 | MAIN_NAME ARG*
|
36 |
|
37 | It behaves like busybox. The command name can be passed as the first argument:
|
38 |
|
39 | oils-for-unix ysh -c 'echo hi'
|
40 |
|
41 | More commonly, it's invoked through a symlink like 'ysh', which causes it to
|
42 | behave like that command:
|
43 |
|
44 | ysh -c 'echo hi'
|
45 |
|
46 | ```
|
47 |
|
48 | <h3 id="osh-usage" class="osh-topic" oils-embed="1">
|
49 | osh-usage
|
50 | </h3>
|
51 |
|
52 | <!-- pre-formatted for help builtin -->
|
53 |
|
54 | ```
|
55 | bin/osh is compatible with POSIX shell, bash, and other shells.
|
56 |
|
57 | Usage: osh FLAG* SCRIPT ARG*
|
58 | osh FLAG* -c COMMAND ARG*
|
59 | osh FLAG*
|
60 |
|
61 | The command line accepted by `bin/osh` is compatible with /bin/sh and bash.
|
62 |
|
63 | osh -c 'echo hi'
|
64 | osh myscript.sh
|
65 | echo 'echo hi' | osh
|
66 |
|
67 | It also has a few enhancements:
|
68 |
|
69 | osh -n -c 'hello' # pretty-print the AST
|
70 | osh --ast-format text -n -c 'hello' # print it full
|
71 |
|
72 | osh accepts POSIX sh flags, with these additions:
|
73 |
|
74 | -n parse the program but don't execute it. Print the AST.
|
75 | --ast-format what format the AST should be in
|
76 | ```
|
77 |
|
78 | <h3 id="ysh-usage" class="ysh-topic" oils-embed="1">
|
79 | ysh-usage
|
80 | </h3>
|
81 |
|
82 | <!-- pre-formatted for help builtin -->
|
83 |
|
84 | ```
|
85 | bin/ysh is the shell with data tYpes, influenced by pYthon, JavaScript, ...
|
86 |
|
87 | Usage: ysh FLAG* SCRIPT ARG*
|
88 | ysh FLAG* -c COMMAND ARG*
|
89 | ysh FLAG*
|
90 |
|
91 | `bin/ysh` is the same as `bin/osh` with a the `ysh:all` option group set. So
|
92 | `bin/ysh` also accepts shell flags.
|
93 |
|
94 | ysh -c 'echo hi'
|
95 | ysh myscript.ysh
|
96 | echo 'echo hi' | ysh
|
97 | ```
|
98 |
|
99 |
|
100 | <h3 id="config" class="osh-ysh-topic">config</h3>
|
101 |
|
102 | If the --rcfile flag is specified, that file will be executed on startup.
|
103 | Otherwise:
|
104 |
|
105 | - `bin/osh` runs `~/.config/oils/oshrc`
|
106 | - `bin/ysh` runs `~/.config/oils/yshrc`
|
107 |
|
108 | Pass --rcfile /dev/null or --norc to disable the startup file.
|
109 |
|
110 | If the --rcdir flag is specified, files in that folder will be executed on
|
111 | startup.
|
112 | Otherwise:
|
113 |
|
114 | - `bin/osh` runs everything in `~/.config/oils/oshrc.d/`
|
115 | - `bin/ysh` runs everything in `~/.config/oils/yshrc.d/`
|
116 |
|
117 | Pass --norc to disable the startup directory.
|
118 |
|
119 | <h3 id="startup" class="osh-ysh-topic">startup</h3>
|
120 |
|
121 | History is read?
|
122 |
|
123 | <h3 id="line-editing" class="osh-ysh-topic">line-editing</h3>
|
124 |
|
125 | Oils is often built with GNU readline, which recognizes many terminal commands
|
126 | for editing input.
|
127 |
|
128 | A useful option is `set -o vi`, which tells GNU readline to accept vi keys.
|
129 |
|
130 | <h3 id="exit-codes" class="osh-ysh-topic">exit-codes</h3>
|
131 |
|
132 | The meaning of exit codes is a convention, and generally follows one of two
|
133 | paradigms.
|
134 |
|
135 | #### The Success / Failure Paradigm
|
136 |
|
137 | - `0` for **success**.
|
138 | - `1` for **runtime error**
|
139 | - Example: `echo foo > out.txt` and `out.txt` can't be opened.
|
140 | - Example: `fg` and there's not job to put in the foreground.
|
141 | - `2` for **parse error**. This means that we didn't *attempt* to do
|
142 | anything, rather than doing something, then it fails.
|
143 | - Example: A language parse error, like `echo $(`.
|
144 | - Example: Builtin usage error, like `read -z`.
|
145 | - `3` for runtime **expression errors**. The expression language is new to
|
146 | Oils, so its errors have a new exit code.
|
147 | - Example: divide by zero `42 / 0`
|
148 | - Example: index out of range `a[1000]`
|
149 |
|
150 | POSIX exit codes:
|
151 |
|
152 | - `126` for permission denied when running a command (`errno EACCES`)
|
153 | - `127` for command not found
|
154 |
|
155 | Hint: Error checking often looks like this:
|
156 |
|
157 | try {
|
158 | ls /bad
|
159 | }
|
160 | if (_error.code !== 0) {
|
161 | echo 'failed'
|
162 | }
|
163 |
|
164 | #### The Boolean Paradigm
|
165 |
|
166 | - `0` for **true**
|
167 | - `1` for **false**.
|
168 | - Example: `test -f foo` and `foo` isn't a file.
|
169 | - `2` for **error** (usage error, parse error, etc.)
|
170 | - Example: `test -q`: the flag isn't accepted.
|
171 |
|
172 | Hint: The `boolstatus` builtin ensures that false and error aren't confused:
|
173 |
|
174 | if boolstatus test -f foo {
|
175 | echo 'foo exists'
|
176 | }
|
177 |
|
178 | See [YSH Fixes Shell's Error Handling](../error-handling.html) for more detail.
|
179 |
|
180 | ## Lexing
|
181 |
|
182 | <h3 id="comment" class="osh-ysh-topic">comment</h3>
|
183 |
|
184 | A comment starts with `#` and goes until the end of the line.
|
185 |
|
186 | echo hi # print a greeting
|
187 |
|
188 | <h3 id="line-continuation" class="osh-ysh-topic">line-continuation</h3>
|
189 |
|
190 | A backslash `\` at the end of a line continues the line without executing it:
|
191 |
|
192 | ls /usr/bin \
|
193 | /usr/lib \
|
194 | ~/src # A single command split over three lines
|
195 |
|
196 | <h3 id="ascii-whitespace" class="osh-ysh-topic">ascii-whitespace</h3>
|
197 |
|
198 | In most places, Oils uses the same definition of ASCII whitespace as JSON.
|
199 | That is, any of these 4 bytes are considered whitespace:
|
200 |
|
201 | [ \t\r\n] # space, tab, carriage return, newline
|
202 |
|
203 | Sometimes newlines are significant, e.g. after shell commands. Then the set of
|
204 | whitespace characters is:
|
205 |
|
206 | [ \t\r]
|
207 |
|
208 | (We don't handle the Windows `\r\n` sequence in a special way. Instead, `\r`
|
209 | is often treated like space and tab.)
|
210 |
|
211 | Examples:
|
212 |
|
213 | - Inside shell arithmetic `$(( 1 + 2 ))`, ASCII whitespace is ignored.
|
214 | - Inside YSH expressions `42 + a[i] * f(x)`, ASCII whitespace is ignored.
|
215 |
|
216 | Exceptions:
|
217 |
|
218 | - Carriage return `\r` may not always be whitespace.
|
219 | - It can appear in an unquoted shell words, a rule that all POSIX shells
|
220 | follow.
|
221 | - The default `$IFS` doesn't include `\r`.
|
222 | - YSH `trim()` functions also respect Unicode space.
|
223 |
|
224 | <h3 id="ascii-control-chars" class="osh-ysh-topic">ascii-control-chars</h3>
|
225 |
|
226 | The ASCII control chars have byte values `0x00` to `0x1F`. This set includes 3
|
227 | whitespace chars:
|
228 |
|
229 | - tab - `\t` aka `0x09`
|
230 | - newline - `\n` aka `0x0a`
|
231 | - carriage return - `\r` aka `0x0d`
|
232 |
|
233 | (It doesn't include the space - `0x20`.)
|
234 |
|
235 | General rules:
|
236 |
|
237 | - In J8 **data** languages, control chars other than whitespace are illegal.
|
238 | This is consistent with the JSON spec.
|
239 | - In **source code**, control chars are allowed (but discouraged).
|
240 | - For example, in OSH, we don't check for control chars unquoted words
|
241 | words or string literals. They are treated like printable chars.
|
242 | - TODO: YSH should only allow printable characters, which implies valid
|
243 | UTF-8.
|
244 |
|
245 | Note about `NUL` aka `0x00`:
|
246 |
|
247 | - The NUL byte is often used to terminate buffers, i.e. as a sentinel for
|
248 | [re2c](https://re2c.org) lexing. This means that data after the NUL will be
|
249 | ignored.
|
250 | - J8 **data** input is read all at once, i.e. **not** split into lines. So
|
251 | everything after the first NUL may be ignored.
|
252 | - Shell **source code** is split into lines.
|
253 |
|
254 | <h3 id="doc-comment" class="ysh-topic">doc-comment</h3>
|
255 |
|
256 | Doc comments look like this:
|
257 |
|
258 | proc deploy {
|
259 | ### Deploy the app
|
260 | echo hi
|
261 | }
|
262 |
|
263 | <h3 id="multiline-command" class="ysh-topic">multiline-command</h3>
|
264 |
|
265 | The ... prefix starts a single command over multiple lines. It allows writing
|
266 | long commands without \ continuation lines, and the resulting limitations on
|
267 | where you can put comments.
|
268 |
|
269 | Single command example:
|
270 |
|
271 | ... chromium-browser
|
272 | # comment on its own line
|
273 | --no-proxy-server
|
274 | --incognito # comment to the right
|
275 | ;
|
276 |
|
277 | Long pipelines and and-or chains:
|
278 |
|
279 | ... find .
|
280 | # exclude tests
|
281 | | grep -v '_test.py'
|
282 | | xargs wc -l
|
283 | | sort -n
|
284 | ;
|
285 |
|
286 | ... ls /
|
287 | && ls /bin
|
288 | && ls /lib
|
289 | || error "oops"
|
290 | ;
|
291 |
|
292 | ## Tools
|
293 |
|
294 | ### cat-em
|
295 |
|
296 | Print files embedded in the `oils-for-unix` binary to stdout. Example:
|
297 |
|
298 | osh --tool cat-em stdlib/math.ysh stdlib/other.ysh
|
299 |
|
300 |
|
301 | ## Help Chapters
|
302 |
|
303 | <h3 id="osh-chapters" class="osh-topic" oils-embed="1">
|
304 | osh-chapters
|
305 | </h3>
|
306 |
|
307 | <!-- shown at the bottom of 'help' -->
|
308 |
|
309 | ```
|
310 | The reference is divided in to "chapters", each of which has its own table of
|
311 | contents. Type:
|
312 |
|
313 | help osh-$CHAPTER
|
314 |
|
315 | Where $CHAPTER is one of:
|
316 |
|
317 | front-end
|
318 | command-lang
|
319 | osh-assign
|
320 | word-lang
|
321 | mini-lang
|
322 | builtin-cmd
|
323 | option
|
324 | special-var
|
325 | plugin
|
326 |
|
327 | Example:
|
328 |
|
329 | help osh-word-lang
|
330 | ```
|
331 |
|
332 |
|
333 | <h3 id="ysh-chapters" class="ysh-topic" oils-embed="1">
|
334 | ysh-chapters
|
335 | </h3>
|
336 |
|
337 | <!-- shown at the bottom of 'help' -->
|
338 |
|
339 | ```
|
340 | The reference is divided in to "chapters", each of which has its own table of
|
341 | contents. Type:
|
342 |
|
343 | help ysh-$CHAPTER
|
344 |
|
345 | Where $CHAPTER is one of:
|
346 |
|
347 | front-end
|
348 | command-lang
|
349 | expr-lang
|
350 | word-lang
|
351 | builtin-cmd
|
352 | option
|
353 | special-var
|
354 | type-method
|
355 | builtin-func
|
356 |
|
357 | Example:
|
358 |
|
359 | help ysh-expr-lang
|
360 | ```
|
361 |
|
362 | <!-- h4 needed to end last card: ysh-chapters -->
|
363 | <h4></h4>
|