| 1 | ---
|
| 2 | in_progress: yes
|
| 3 | default_highlighter: oils-sh
|
| 4 | css_files: ../../web/base.css ../../web/manual.css ../../web/toc.css
|
| 5 | ---
|
| 6 |
|
| 7 | Oil Keywords
|
| 8 | ============
|
| 9 |
|
| 10 | Related:
|
| 11 |
|
| 12 | - [Procs and Blocks](proc-block-func.html)
|
| 13 | - [Variables](variables.html)
|
| 14 |
|
| 15 | <div id="toc">
|
| 16 | </div>
|
| 17 |
|
| 18 | ## Two Styles of Variable Declaration and Assignment
|
| 19 |
|
| 20 | ### Legacy Style: `readonly`, `local`, `name=val`
|
| 21 |
|
| 22 | They don't allow expressions on the right.
|
| 23 |
|
| 24 | ### Oil's Style: `const`, `var`, `setvar`, `setglobal`, and `setref`
|
| 25 |
|
| 26 | See the doc on [variables](variables.html) for details.
|
| 27 |
|
| 28 | ## Expressions Go on the Right
|
| 29 |
|
| 30 | Just like with assignments.
|
| 31 |
|
| 32 | ### `=` Pretty Prints an Expression
|
| 33 |
|
| 34 | Useful interactively.
|
| 35 |
|
| 36 | $ = 'foo'
|
| 37 | (Str) 'foo'
|
| 38 |
|
| 39 | $ = :| one two |
|
| 40 | (StrArray) ['one', 'two']
|
| 41 |
|
| 42 | ### `_` Ignores an Expression
|
| 43 |
|
| 44 | Think of this:
|
| 45 |
|
| 46 | _ f(x)
|
| 47 |
|
| 48 | as a shortcut for:
|
| 49 |
|
| 50 | _ = f(x) # assign to "meh" variable
|
| 51 |
|
| 52 |
|
| 53 | ## Other Kinds of Assignment
|
| 54 |
|
| 55 | ### `auto` for Autovivification (future, not implemented)
|
| 56 |
|
| 57 | auto count += 1
|
| 58 |
|
| 59 | auto hist['key'] += 1
|
| 60 |
|
| 61 | auto total += 3.5
|
| 62 | auto hist['key'] += 4.6
|
| 63 |
|
| 64 | ## Notes and Examples
|
| 65 |
|
| 66 | ### Mutating Arrays
|
| 67 |
|
| 68 | Use `setvar`:
|
| 69 |
|
| 70 | Shell:
|
| 71 |
|
| 72 |
|
| 73 | a=(one two three)
|
| 74 | a[0]=zz
|
| 75 |
|
| 76 | Oil:
|
| 77 |
|
| 78 | var a = :| one two three |
|
| 79 | setvar a[0] = 'zz' # also acceptable
|
| 80 |
|
| 81 | ### Mutating Associative Arrays
|
| 82 |
|
| 83 | Shell:
|
| 84 |
|
| 85 | declare -A A=(['name']=foo ['type']='dir')
|
| 86 | A['type']=file
|
| 87 |
|
| 88 | Oil:
|
| 89 |
|
| 90 | var A = {name: 'foo', type: 'dir'}
|
| 91 | setvar A['type'] = 'file' # also acceptable
|
| 92 |
|
| 93 |
|
| 94 | ## `proc` Disables Dynamic Scope
|
| 95 |
|
| 96 | Recall that [procs](proc-block-func.html) are the way to declare shell-like
|
| 97 | functions in Oil.
|
| 98 |
|
| 99 | proc p {
|
| 100 | echo one
|
| 101 | echo two
|
| 102 | }
|
| 103 |
|
| 104 | p > file.txt
|
| 105 |
|
| 106 | They mostly look like and work like shell functions, but they change scoping rules.
|
| 107 |
|
| 108 | <!--
|
| 109 |
|
| 110 | ## Variables and Assignment
|
| 111 |
|
| 112 | TODO: Merge this
|
| 113 |
|
| 114 | I just implemented some more Oil language semantics! [1]
|
| 115 |
|
| 116 | In shell (and Python), there's no difference between variable declaration and
|
| 117 | mutation. These are valid:
|
| 118 |
|
| 119 | ```
|
| 120 | declare x=1
|
| 121 | declare x=2 # mutates x, "declare" is something of a misnomer
|
| 122 | x=2 # better way of mutating x
|
| 123 | f() {
|
| 124 | local y=1
|
| 125 | local y=2 # mutates y
|
| 126 | y=2 # better way of mutating y
|
| 127 | }
|
| 128 | ```
|
| 129 |
|
| 130 | Likewise, `z=3` can be any of these 3, depending on the context:
|
| 131 |
|
| 132 | 1. mutating a local
|
| 133 | 2. mutating a global
|
| 134 | 3. creating a new global
|
| 135 |
|
| 136 | In Oil, there are separate keywords for declaring variables and mutating them.
|
| 137 |
|
| 138 | ```
|
| 139 | var x = 1
|
| 140 | var x = 2 # error: it's already declared
|
| 141 |
|
| 142 | setvar x = 2 # successful mutation
|
| 143 | set x = 2 # I plan to add shopt -s parse-set to take over the 'set' builtin, which can be replaced with `shopt` or `builtin set`
|
| 144 | ```
|
| 145 |
|
| 146 | (Ever notice that the set and unset builtins aren't opposites in shell ?!?!)
|
| 147 |
|
| 148 | You can mutate a global from a function:
|
| 149 |
|
| 150 | ```
|
| 151 | var myglobal = 'g'
|
| 152 | f() {
|
| 153 | set myglobal = 'new'
|
| 154 | set other = 'foo' # error: not declared yet!
|
| 155 | }
|
| 156 | ```
|
| 157 |
|
| 158 | Comments appreciated!
|
| 159 |
|
| 160 | [1] https://github.com/oilshell/oil/commit/54754f3e8298bc3c272416eb0fc96946c8fa0694
|
| 161 |
|
| 162 |
|
| 163 | Note that `shopt -s all:oil` turns on all the `parse_*` options.
|
| 164 | -->
|