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

Oil Builtins

This is an overview of shell builtins that are unique to Oil. A full description of each builtin will be available in the help pages.

What are builtins? They look like external commands, but are included with the shell itself. They don't spawn an external process, and can modify the shell's memory.

Table of Contents
New Builtins in Oil
append appends strings to an array
pp pretty prints interpreter state
module
use
runproc
Shell Builtins Enhanced with Block
cd
shopt
Other Builtins That Take Blocks
fork, forkwait
argparse
I/O Builtins
More

New Builtins in Oil

append appends strings to an array

Example:

var a = %(1 '2 two')
append :a three four
echo @a  # prints 4 lines

Here's another way to write it:

setvar a = %( @a three four )

Note that you can append to a string like this:

var s = 'foo'
setvar s = "${s}suffix"

(Note: Oil doesn't currently support the equivalent of shell's s+=suffix.)

pp pretty prints interpreter state

module

use

runproc

Shell Builtins Enhanced with Block

Done:

Planned, but not implemented:

Examples of what we have in mind:

# this replaces an awkward idiom with eval I've seen a lot
shopt -u errexit {  # TODO: --unset
   false
   echo "temporary disable an option"
} 

# generalizes the 'NAME=value command' syntax and the 'env' prefix helps parsing
env PYTHONPATH=. {
  ./foo.py
  ./bar.py
}

# replaces sleep 5 &
fork { sleep 5 }

# replaces () syntax so we can use it for something else.
forkwait { echo subshell; sleep 5 }

# Probably used for a "syntactic pun" of Python-like "import as" functionality

use lib foo.sh {
  myfunc
  myalias otherfunc
}

cd

It now takes a block:

cd /tmp {
  echo $PWD  # prints /tmp
}
echo $PWD  # prints the original directory

This subsumes the functionality of bash builtins pushd and popd.

When a block is passed:

shopt

Other Builtins That Take Blocks

fork, forkwait

argparse

I/O Builtins

See IO Builtins.

And JSON.

More


Generated on Sun Jul 24 00:29:42 EDT 2022