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
|