source | all docs for version 0.8.0 | 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

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 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.

var and set/setglobal are Oil-like and stricter

• set mutates a local that's been declared
• 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
}

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.)