| 1 | ---
|
| 2 | in_progress: yes
|
| 3 | default_highlighter: oils-sh
|
| 4 | ---
|
| 5 |
|
| 6 | Oil Builtins
|
| 7 | ============
|
| 8 |
|
| 9 | <!-- TODO: This doc could be an alternative categorization to the auto-generated
|
| 10 | builtin-index.md ? -->
|
| 11 |
|
| 12 | This is an **overview** of [shell builtins]($xref:shell-builtin) that are
|
| 13 | unique to Oil. A full description of each builtin will be available in the
|
| 14 | [help pages](help-index.html).
|
| 15 |
|
| 16 | What are builtins? They look like external commands, but are included with the
|
| 17 | shell itself. They don't spawn an external process, and can modify the shell's
|
| 18 | memory.
|
| 19 |
|
| 20 | <div id="toc">
|
| 21 | </div>
|
| 22 |
|
| 23 | ## New Builtins in Oil
|
| 24 |
|
| 25 | ### [`append`]($help) appends strings to an array
|
| 26 |
|
| 27 | Example:
|
| 28 |
|
| 29 | var a = :| 1 '2 two' |
|
| 30 | append :a three four
|
| 31 | echo @a # prints 4 lines
|
| 32 |
|
| 33 | Here's another way to write it:
|
| 34 |
|
| 35 | setvar a = :| @a three four |
|
| 36 |
|
| 37 | Note that you can append to a string like this:
|
| 38 |
|
| 39 | var s = 'foo'
|
| 40 | setvar s = "${s}suffix"
|
| 41 |
|
| 42 | (Note: Oil doesn't currently support the equivalent of shell's `s+=suffix`.)
|
| 43 |
|
| 44 | ### [`pp`]($help) pretty prints interpreter state
|
| 45 |
|
| 46 | - `pp cell` - shows the value of a variable, for debugging
|
| 47 | - `pp proc` - shows doc strings
|
| 48 |
|
| 49 | ### `module`
|
| 50 |
|
| 51 | ### `use`
|
| 52 |
|
| 53 | ### `runproc`
|
| 54 |
|
| 55 | ## Shell Builtins Enhanced with Block
|
| 56 |
|
| 57 | Done:
|
| 58 |
|
| 59 | - [cd]($help)
|
| 60 | - [shopt]($help)
|
| 61 |
|
| 62 | Planned, but not implemented:
|
| 63 |
|
| 64 | - [fork]($help) for `&`
|
| 65 | - [forkwait]($help) for `()`
|
| 66 | - [env]($help) to replace `PYTHONPATH=. foo.py`
|
| 67 | - [each]($help) runs processes in parallel and replaces `xargs`
|
| 68 |
|
| 69 | Examples of what we have in mind:
|
| 70 |
|
| 71 | ```
|
| 72 | # this replaces an awkward idiom with eval I've seen a lot
|
| 73 | shopt -u errexit { # TODO: --unset
|
| 74 | false
|
| 75 | echo "temporary disable an option"
|
| 76 | }
|
| 77 |
|
| 78 | # generalizes the 'NAME=value command' syntax and the 'env' prefix helps parsing
|
| 79 | env PYTHONPATH=. {
|
| 80 | ./foo.py
|
| 81 | ./bar.py
|
| 82 | }
|
| 83 |
|
| 84 | # replaces sleep 5 &
|
| 85 | fork { sleep 5 }
|
| 86 |
|
| 87 | # replaces () syntax so we can use it for something else.
|
| 88 | forkwait { echo subshell; sleep 5 }
|
| 89 |
|
| 90 | # Probably used for a "syntactic pun" of Python-like "import as" functionality
|
| 91 |
|
| 92 | use lib foo.sh {
|
| 93 | myfunc
|
| 94 | myalias otherfunc
|
| 95 | }
|
| 96 | ```
|
| 97 |
|
| 98 | ### cd
|
| 99 |
|
| 100 | It now takes a block:
|
| 101 |
|
| 102 | cd /tmp {
|
| 103 | echo $PWD # prints /tmp
|
| 104 | }
|
| 105 | echo $PWD # prints the original directory
|
| 106 |
|
| 107 |
|
| 108 | This subsumes the functionality of bash builtins [pushd]($help) and
|
| 109 | [popd]($help).
|
| 110 |
|
| 111 | When a block is passed:
|
| 112 |
|
| 113 | - `cd` doesn't set The `OLDPWD` variable (which is used to implement the `cd -`
|
| 114 | shortcut.)
|
| 115 | - The directory stack for `pushd` and `popd` isn't cleared, as it is with a
|
| 116 | normal `cd` command.
|
| 117 |
|
| 118 | ### shopt
|
| 119 |
|
| 120 | ## Other Builtins That Take Blocks
|
| 121 |
|
| 122 | ### fork, forkwait
|
| 123 |
|
| 124 | ### argparse
|
| 125 |
|
| 126 | ## I/O Builtins
|
| 127 |
|
| 128 | See [IO Builtins](io-builtins.html).
|
| 129 |
|
| 130 | And [JSON](json.html).
|
| 131 |
|
| 132 | ## More
|
| 133 |
|
| 134 | - Not implemented: log, die
|