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

Oil Keywords

Table of Contents
Two Styles for Declaration and Assignment
const, var, and setvar are shell-like and interactive
var and set/setglobal are Oil-like and stricter
Other Kinds of Assignment
Mutating Arrays
Mutating Associative Arrays
Advanced: setref is for "out parameters"
= pretty prints an expression
Defining "Functions"
proc declares a shell-like "function"
return is a keyword in Oil

Two Styles for Declaration and Assignment

const, var, and setvar are shell-like and interactive

Shell:

readonly c=C

myfunc() {
  local x=L
  x=mutated

  newglobal=G
}

OSH:

const c = 'C'

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

  setvar newglobal = 'G'
}

var and set/setglobal are Oil-like and stricter

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
}

Other Kinds of Assignment

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

Advanced: setref is for "out parameters"

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

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

= pretty prints an expression

Useful interactively.

$ = 'foo'
(Str)   'foo'

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

Defining "Functions"

proc declares a shell-like "function"

proc p {
  echo one
  echo two
}

p > file.txt

return is a keyword in Oil

It takes an expression, not a word. See command vs. expression mode.

proc p {
  var status = '1'

  echo 'hello'

  return status  # not $status
}

p
echo $?  # prints 1

(This is intended to be consistent with a future func.)


Generated on Mon Mar 23 14:42:04 PDT 2020