source | all docs for version 0.8.10 | all versions | oilshell.org

Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

Oil Keywords

Related:

• Procs and Blocks
• Variable Scope

Three Styles of Variable Declaration and Assignment

Legacy Style: readonly, local, name=val

They don't allow expressions on the right.

Oil's Shell-Like Style: const, var, and setvar

• const declares a constant, like readonly
• var declares a local or global
• setvar mutates a local, mutates a global, or creates a new global.
  • This makes it more convenient for interactive use.

Shell:

g=G                       # global variable
readonly c=C              # global constant

myfunc() {
  local x=X               # local variable
  readonly y=Y            # local constant

  x=mutated               # mutate local
  g=mutated               # mutate global
  newglobal=G             # create new global

  caller_var=mutated      # dynamic scope (Oil doesn't have this)
}

Oil:

var g = 'G'               # global variable
const c = 'C'             # global constant

proc myproc {
  var x = 'L'             # local variable
  const y = 'Y'           # local constant

  setvar x = 'mutated'    # mutate local
  setvar g = 'mutated'    # mutate global
  setvar newglobal = 'G'  # create new global

                          # For dynamic scope, Oil uses setref and an
                          # explicit ref param.  See below.
}

• var declares a new variable in the current scope (global or local)
• const is like var, except the binding can never be changed
• setvar x = 'y' is like x=y in shell (except that it doesn't obey dynamic scope.)
  • If a local x exists, it mutates it.
  • Otherwise it creates a new global x.
  • If you want stricter behavior, use set rather than setvar.

Oil's Stricter Style: const (optional), var, set/setglobal

• set mutates a local that's been declared (also setlocal)
• setglobal mutates a global that's been decalred
• c = 'X' is syntactic sugar for const c = 'X'. This is to make it more compact, i.e. for "Huffman coding" of programs.

c = 'X'  # syntactic sugar for const c = 'X'

proc myproc {
  var x = 'L'
  set x = 'mutated' 

  set notglobal = 'G'   # ERROR: neither a local or global
}

It's rarely necessary to mutate globals in shell scripts, but if you do, use the setglobal keyword:

var g = 'G'
proc myproc {
  setglobal g = 'mutated'

  setglobal notglobal = 'G'  # ERROR: not a global
}

Expressions Go on the Right

Just like with assignments.

= Pretty Prints an Expression

Useful interactively.

$ = 'foo'
(Str)   'foo'

$ = %(one two)
(StrArray)   ['one', 'two']

_ Ignores an Expression

Think of this:

_ f(x)

as a shortcut for:

_ = f(x)  # assign to "meh" variable

Other Kinds of Assignment

setref for "Out Params" (advanced)

To return a value. Like "named references" in bash.

proc decode (s, :out) {
  setref out = '123'
}

auto for Autovivification (future, not implemented)

auto count += 1

auto hist['key'] += 1

auto total += 3.5
auto hist['key'] += 4.6

Notes and Examples

Mutating Arrays

You can use setvar or set:

Shell:

a=(one two three)
a[0]=zz

Oil:

var a = %(one two three)
set a[0] = 'zz'

setvar a[0] = 'zz'  # also acceptable

Mutating Associative Arrays

Shell:

declare -A A=(['name']=foo ['type']='dir')
A['type']=file

Oil:

var A = {name: 'foo', type: 'dir'}
set A['type'] = 'file'

setvar A['type'] = 'file'  # also acceptable

proc Disables Dynamic Scope

Recall that procs are the way to declare shell-like functions in Oil.

proc p {
  echo one
  echo two
}

p > file.txt

They mostly look like and work like shell functions, but they change scoping rules.

Style

• local -> var
• readonly -> const
• x=mystr -> setvar x = 'mystr'
• x=(my array) -> setvar x = %(my array)

Advantage: you get expressions on the right.