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

305 lines, 200 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## Debugging
86
87These options are from POSIX shell:
88
89 xtrace verbose
90
91From bash:
92
93 extdebug
94
95## Interactive
96
97These options are from bash.
98
99 emacs vi
100
101## Other Option
102
103 noclobber # Redirects don't overwrite files
104 errtrace # Inherits ERR trap in shell functions, sub processes, sub commands (option -E)
105
106## Compat
107
108### eval_unsafe_arith
109
110Allow dynamically parsed `a[$(echo 42)]` For bash compatibility.
111
112
113## Groups
114
115To turn OSH into YSH, we use three option groups. Some of them allow new
116features, and some disallow old features.
117
118<!-- note: explicit anchor necessary because of mangling -->
119<h3 id="strict:all">strict:all</h3>
120
121Option in this group disallow problematic or confusing shell constructs. The
122resulting script will still run in another shell.
123
124 shopt --set strict:all # turn on all options
125 shopt -p strict:all # print their current state
126
127Details on each option:
128
129 strict_argv No empty argv
130 strict_arith Fatal parse errors (on by default)
131 strict_array Arrays and strings aren't confused
132 strict_control_flow Disallow misplaced keyword, empty arg
133 strict_errexit Disallow code that ignores failure
134 strict_nameref trap invalid variable names
135 strict_word_eval Expose unicode and slicing errors
136 strict_tilde Tilde subst can result in error
137 X strict_glob Parse the sublanguage more strictly
138
139<h3 id="ysh:upgrade">ysh:upgrade</h3>
140
141Options in this group enable new YSH features. It doesn't break existing shell
142scripts when it's avoidable.
143
144For example, `parse_at` means that `@myarray` is now the operation to splice
145an array. This will break scripts that expect `@` to be literal, but you can
146simply quote it like `'@literal'` to fix the problem.
147
148 shopt --set ysh:upgrade # turn on all options
149 shopt -p ysh:upgrade # print their current state
150
151Details on each option:
152
153 parse_at echo @array @[arrayfunc(x, y)]
154 parse_brace if true { ... }; cd ~/src { ... }
155 parse_equals x = 'val' in Caps { } config blocks
156 parse_paren if (x > 0) ...
157 parse_proc proc p { ... }
158 parse_triple_quote """$x""" '''x''' (command mode)
159 X parse_utf8_only YSH source code must be valid UTF-8
160 parse_ysh_string echo r'\' u'\\' b'\\' (command mode)
161 command_sub_errexit Synchronous errexit check
162 process_sub_fail Analogous to pipefail for process subs
163 sigpipe_status_ok status 141 -> 0 in pipelines
164 simple_word_eval No splitting, static globbing
165 xtrace_rich Hierarchical and process tracing
166 xtrace_details (-u) Disable most tracing with +
167 dashglob (-u) Disabled to avoid files like -rf
168 X env_dict Copy environ into ENV dict
169
170
171<h3 id="ysh:all">ysh:all</h3>
172
173Enable the full YSH language. This includes everything in the `ysh:upgrade`
174group and the `strict:all` group.
175
176 shopt --set ysh:all # turn on all options
177 shopt -p ysh:all # print their current state
178
179Details on options that are not in `ysh:upgrade` and `strict:all`:
180
181 parse_at_all @ starting any word is an operator
182 parse_backslash (-u) Allow bad backslashes in "" and $''
183 parse_backticks (-u) Allow legacy syntax `echo hi`
184 parse_bare_word (-u) 'case unquoted' and 'for x in unquoted'
185 parse_dollar (-u) Allow bare $ to mean \$ (maybe $/d+/)
186 parse_dbracket (-u) Is legacy [[ allowed?
187 parse_dparen (-u) Is (( legacy arithmetic allowed?
188 parse_ignored (-u) Parse, but ignore, certain redirects
189 parse_sh_arith (-u) Allow legacy shell arithmetic
190 expand_aliases (-u) Whether aliases are expanded
191 X no_env_vars Use $[ENV.PYTHONPATH], not $PYTHONPATH
192 X old_builtins (-u) local/declare/etc. pushd/popd/dirs
193 ... source unset printf [un]alias
194 ... getopts
195 X old_syntax (-u) ( ) ${x%prefix} ${a[@]} $$
196 simple_echo echo doesn't accept flags -e -n
197 simple_eval_builtin eval takes exactly 1 argument
198 simple_test_builtin 3 args or fewer; use test not [
199 X simple_trap Function name only
200 verbose_errexit Whether to print detailed errors
201
202## YSH Details
203
204### opts-redefine
205
206In the interactive shell, you can redefine procs and funcs.
207
208 redefine_module 'module' builtin always returns 0
209 redefine_proc_func (-u) Can shell func, proc and func be redefined?
210 X redefine_const Can consts be redefined?
211
212### opts-internal
213
214These options are used by the interpreter. You generally shouldn't set them
215yourself.
216
217 _allow_command_sub To implement strict_errexit, eval_unsafe_arith
218 _allow_process_sub To implement strict_errexit
219 dynamic_scope To implement proc and func
220 _no_debug_trap Used in pipelines in job control shell
221 _running_trap To disable strict_errexit
222 _running_hay Hay evaluation
223
224## Unlinked Descriptions
225
226Here are some descriptions of individual options.
227
228### strict_control_flow
229
230Disallow `break` and `continue` at the top level, and disallow empty args like
231`return $empty`.
232
233### strict_tilde
234
235Failed tilde expansions cause hard errors (like zsh) rather than silently
236evaluating to `~` or `~bad`.
237
238
239### strict_nameref
240
241When `strict_nameref` is set, undefined references produce fatal errors:
242
243 declare -n ref
244 echo $ref # fatal error, not empty string
245 ref=x # fatal error instead of decaying to non-reference
246
247References that don't contain variables also produce hard errors:
248
249 declare -n ref='not a var'
250 echo $ref # fatal
251 ref=x # fatal
252
253### parse_ignored
254
255For compatibility, YSH will parse some constructs it doesn't execute, like:
256
257 return 0 2>&1 # redirect on control flow
258
259When this option is disabled, that statement is a syntax error.
260
261### parse_triple_quote
262
263Parse the shell-style multi-line strings, which strip leading whitespace:
264
265 echo '''
266 one
267 two
268 '''
269
270 echo """
271 hello
272 $name
273 """
274
275(This option affects only command mode. Such strings are always parsed in
276expression mode.)
277
278### parse_ysh_string
279
280Allow `r'\'` and `u'\\'` and `b'\\'` strings, as well as their multi-line
281versions.
282
283Since shell strings are already raw, this means that YSH just ignores the r
284prefix:
285
286 echo r'\' # a single backslash
287
288J8 unicode strings:
289
290 echo u'mu \u{3bc}' # mu char
291
292J8 byte strings:
293
294 echo b'byte \yff'
295
296(This option affects only command mode. Such strings are always parsed in
297expression mode.)
298
299### sigpipe_status_ok
300
301If a process that's part of a pipeline exits with status 141 when this is
302option is on, it's turned into status 0, which avoids failure.
303
304SIGPIPE errors occur in cases like 'yes | head', and generally aren't useful.
305