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

319 lines, 207 significant
1---
2title: Global Shell Options (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 **Global Shell Options**
13
14</div>
15
16This chapter describes global shell options in Oils. Some options are from
17POSIX shell, and some are from [bash]($xref). We also use options to turn
18[OSH]($xref) into [YSH]($xref).
19
20<span class="in-progress">(in progress)</span>
21
22<div id="dense-toc">
23</div>
24
25## Errors
26
27These options are from POSIX shell:
28
29 nounset -u
30 errexit -e
31
32These are from bash:
33
34 inherit_errexit:
35 pipefail
36
37## Globbing
38
39These options are from POSIX shell:
40
41 noglob -f
42
43From bash:
44
45 nullglob failglob dotglob
46
47From Oils:
48
49 dashglob
50
51Some details:
52
53### nullglob
54
55When `nullglob` is on, a glob matching no files expands to no arguments:
56
57 shopt -s nullglob
58 $ echo L *.py R
59 L R
60
61Without this option, the glob string itself is returned:
62
63 $ echo L *.py R # no Python files in this dir
64 L *.py R
65
66(This option is from GNU bash.)
67
68### dashglob
69
70Do globs return results that start with `-`? It's on by default in `bin/osh`,
71but off when YSH is enabled.
72
73Turning it off prevents a command like `rm *` from being confused by a file
74called `-rf`.
75
76 $ touch -- myfile -rf
77
78 $ echo *
79 -rf myfile
80
81 $ shopt -u dashglob
82 $ echo *
83 myfile
84
85## Other Option
86
87 noclobber -C # Redirects can't overwrite files
88 errtrace -E # Enable ERR trap is both shell functions and subshells
89
90## Debugging
91
92These options are from POSIX shell:
93
94 xtrace verbose
95
96From bash:
97
98 extdebug
99
100## Interactive
101
102These options are from bash.
103
104 emacs vi
105
106
107## Compat
108
109### eval_unsafe_arith
110
111Allow dynamically parsed `a[$(echo 42)]` For bash compatibility.
112
113### ignore_flags_not_impl
114
115Suppress failures from flags not implemented. Example:
116
117 shopt --set ignore_flags_not_impl
118
119 declare -i foo=2+3 # not evaluated to 5, but doesn't fail either
120
121This option can be useful for "getting past" errors while testing.
122
123## Groups
124
125To turn OSH into YSH, we use three option groups. Some of them allow new
126features, and some disallow old features.
127
128<!-- note: explicit anchor necessary because of mangling -->
129<h3 id="strict:all">strict:all</h3>
130
131Option in this group disallow problematic or confusing shell constructs. The
132resulting script will still run in another shell.
133
134 shopt --set strict:all # turn on all options
135 shopt -p strict:all # print their current state
136
137Parsing options:
138
139 strict_parse_slice # No implicit length for ${a[@]::}
140 X strict_parse_utf8 # Source code must be valid UTF-8
141
142Runtime options:
143
144 strict_argv # No empty argv
145 strict_arith # Fatal parse errors (on by default)
146 strict_array # Arrays and strings aren't confused
147 strict_control_flow # Disallow misplaced keyword, empty arg
148 strict_errexit # Disallow code that ignores failure
149 strict_nameref # Trap invalid variable names
150 strict_word_eval # Expose unicode and slicing errors
151 strict_tilde # Tilde subst can result in error
152 X strict_glob # Parse the sublanguage more strictly
153
154<h3 id="ysh:upgrade">ysh:upgrade</h3>
155
156Options in this group enable new YSH features. It doesn't break existing shell
157scripts when it's avoidable.
158
159For example, `parse_at` means that `@myarray` is now the operation to splice
160an array. This will break scripts that expect `@` to be literal, but you can
161simply quote it like `'@literal'` to fix the problem.
162
163 shopt --set ysh:upgrade # turn on all options
164 shopt -p ysh:upgrade # print their current state
165
166Details on each option:
167
168 parse_at echo @array @[arrayfunc(x, y)]
169 parse_brace if true { ... }; cd ~/src { ... }
170 parse_equals x = 'val' in Caps { } config blocks
171 parse_paren if (x > 0) ...
172 parse_proc proc p { ... }
173 parse_triple_quote """$x""" '''x''' (command mode)
174 parse_ysh_string echo r'\' u'\\' b'\\' (command mode)
175 command_sub_errexit Synchronous errexit check
176 process_sub_fail Analogous to pipefail for process subs
177 sigpipe_status_ok status 141 -> 0 in pipelines
178 simple_word_eval No splitting, static globbing
179 xtrace_rich Hierarchical and process tracing
180 xtrace_details (-u) Disable most tracing with +
181 dashglob (-u) Disabled to avoid files like -rf
182 X env_dict Copy environ into ENV dict
183
184
185<h3 id="ysh:all">ysh:all</h3>
186
187Enable the full YSH language. This includes everything in the `ysh:upgrade`
188group and the `strict:all` group.
189
190 shopt --set ysh:all # turn on all options
191 shopt -p ysh:all # print their current state
192
193Details on options that are not in `ysh:upgrade` and `strict:all`:
194
195 parse_at_all @ starting any word is an operator
196 parse_backslash (-u) Allow bad backslashes in "" and $''
197 parse_backticks (-u) Allow legacy syntax `echo hi`
198 parse_bare_word (-u) 'case unquoted' and 'for x in unquoted'
199 parse_dollar (-u) Allow bare $ to mean \$ (maybe $/d+/)
200 parse_dbracket (-u) Is legacy [[ allowed?
201 parse_dparen (-u) Is (( legacy arithmetic allowed?
202 parse_ignored (-u) Parse, but ignore, certain redirects
203 parse_sh_arith (-u) Allow legacy shell arithmetic
204 expand_aliases (-u) Whether aliases are expanded
205 X no_env_vars Use $[ENV.PYTHONPATH], not $PYTHONPATH
206 X old_builtins (-u) local/declare/etc. pushd/popd/dirs
207 ... source unset printf [un]alias
208 ... getopts
209 X old_syntax (-u) ( ) ${x%prefix} ${a[@]} $$
210 simple_echo echo doesn't accept flags -e -n
211 simple_eval_builtin eval takes exactly 1 argument
212 simple_test_builtin 3 args or fewer; use test not [
213 X simple_trap Function name only
214 verbose_errexit Whether to print detailed errors
215
216## YSH Details
217
218### opts-redefine
219
220In the interactive shell, you can redefine procs and funcs.
221
222 redefine_module 'module' builtin always returns 0
223 redefine_proc_func (-u) Can shell func, proc and func be redefined?
224 X redefine_const Can consts be redefined?
225
226### opts-internal
227
228These options are used by the interpreter. You generally shouldn't set them
229yourself.
230
231 _allow_command_sub To implement strict_errexit, eval_unsafe_arith
232 _allow_process_sub To implement strict_errexit
233 dynamic_scope To implement proc and func
234 _no_debug_trap Used in pipelines in job control shell
235 _running_trap To disable strict_errexit
236 _running_hay Hay evaluation
237
238## Unlinked Descriptions
239
240Here are some descriptions of individual options.
241
242### strict_control_flow
243
244Disallow `break` and `continue` at the top level, and disallow empty args like
245`return $empty`.
246
247### strict_tilde
248
249Failed tilde expansions cause hard errors (like zsh) rather than silently
250evaluating to `~` or `~bad`.
251
252
253### strict_nameref
254
255When `strict_nameref` is set, undefined references produce fatal errors:
256
257 declare -n ref
258 echo $ref # fatal error, not empty string
259 ref=x # fatal error instead of decaying to non-reference
260
261References that don't contain variables also produce hard errors:
262
263 declare -n ref='not a var'
264 echo $ref # fatal
265 ref=x # fatal
266
267### parse_ignored
268
269For compatibility, YSH will parse some constructs it doesn't execute, like:
270
271 return 0 2>&1 # redirect on control flow
272
273When this option is disabled, that statement is a syntax error.
274
275### parse_triple_quote
276
277Parse the shell-style multi-line strings, which strip leading whitespace:
278
279 echo '''
280 one
281 two
282 '''
283
284 echo """
285 hello
286 $name
287 """
288
289(This option affects only command mode. Such strings are always parsed in
290expression mode.)
291
292### parse_ysh_string
293
294Allow `r'\'` and `u'\\'` and `b'\\'` strings, as well as their multi-line
295versions.
296
297Since shell strings are already raw, this means that YSH just ignores the r
298prefix:
299
300 echo r'\' # a single backslash
301
302J8 unicode strings:
303
304 echo u'mu \u{3bc}' # mu char
305
306J8 byte strings:
307
308 echo b'byte \yff'
309
310(This option affects only command mode. Such strings are always parsed in
311expression mode.)
312
313### sigpipe_status_ok
314
315If a process that's part of a pipeline exits with status 141 when this is
316option is on, it's turned into status 0, which avoids failure.
317
318SIGPIPE errors occur in cases like 'yes | head', and generally aren't useful.
319