| 1 | ---
|
| 2 | title: YSH and OSH Topics by Feature
|
| 3 | all_docs_url: ..
|
| 4 | default_highlighter: oils-sh
|
| 5 | preserve_anchor_case: yes
|
| 6 | ---
|
| 7 |
|
| 8 | YSH and OSH Topics by Feature
|
| 9 | ====
|
| 10 |
|
| 11 | <span class="in-progress">(in progress)</span>
|
| 12 |
|
| 13 | This page links to topics in the [Oils Reference](index.html). It's organized
|
| 14 | differently than the [YSH Table of Contents](toc-ysh.html) or [OSH Table of
|
| 15 | Contents](toc-osh.html).
|
| 16 |
|
| 17 | <div id="toc">
|
| 18 | </div>
|
| 19 |
|
| 20 | ## Where YSH Improves on OSH
|
| 21 |
|
| 22 | ### Errors
|
| 23 |
|
| 24 | YSH:
|
| 25 |
|
| 26 | - [`try`](chap-builtin-cmd.html#try)
|
| 27 | - [`_error`](chap-special-var.html#_error)
|
| 28 | - multiple processes
|
| 29 | - [`_pipeline_status`](chap-special-var.html#_pipeline_status)
|
| 30 | - [`_process_sub_status`](chap-special-var.html#_process_sub_status)
|
| 31 | - [Options](chap-option.html):
|
| 32 | - `strict_errexit`, `command_sub_errexit`, ...
|
| 33 |
|
| 34 | OSH:
|
| 35 |
|
| 36 | - [`$?`](chap-special-var.html#POSIX-special) - not idiomatic in YSH
|
| 37 | - [Options](chap-option.html):
|
| 38 | - `errexit`, `pipefail`, `inherit_errexit`
|
| 39 |
|
| 40 | ### Environment Variables
|
| 41 |
|
| 42 | YSH:
|
| 43 |
|
| 44 | - [`ENV`][ENV]
|
| 45 | - [`ysh-prefix-binding`][ysh-prefix-binding] - for `NAME=val` env bindings
|
| 46 | - [`simple-command`][simple-command] - external commands are started with an
|
| 47 | `environ`
|
| 48 | - [Options](chap-option.html):
|
| 49 | - `shopt --unset no_exported`
|
| 50 | - `shopt --set env_obj`
|
| 51 |
|
| 52 | [ENV]: chap-special-var.html#ENV
|
| 53 |
|
| 54 | <!--
|
| 55 | TODO: should we have a `envFromDict()` function that goes with `env -i`?
|
| 56 | -->
|
| 57 |
|
| 58 | OSH:
|
| 59 |
|
| 60 | - [`export`](chap-osh-assign.html#export)
|
| 61 | - [`prefix-binding`][prefix-binding] - for `NAME=val` env bindings
|
| 62 |
|
| 63 | [prefix-binding]: chap-cmd-lang.html#prefix-binding
|
| 64 | [ysh-prefix-binding]: chap-cmd-lang.html#ysh-prefix-binding
|
| 65 |
|
| 66 | [simple-command]: chap-cmd-lang.html#simple-command
|
| 67 |
|
| 68 |
|
| 69 | ### I/O
|
| 70 |
|
| 71 | YSH:
|
| 72 |
|
| 73 | - [`write`](chap-builtin-cmd.html#write)
|
| 74 | - [`ysh-echo`](chap-builtin-cmd.html#ysh-echo) is a shortcut for `write`
|
| 75 | - [`ysh-read`](chap-builtin-cmd.html#ysh-read) - `read --all`, etc.
|
| 76 | - [`redir`](chap-builtin-cmd.html#redir)
|
| 77 | - The [`io`](chap-type-method.html#io) object
|
| 78 |
|
| 79 | OSH:
|
| 80 |
|
| 81 | - [`printf`](chap-builtin-cmd.html#printf)
|
| 82 |
|
| 83 | ### Procs
|
| 84 |
|
| 85 | YSH:
|
| 86 |
|
| 87 | - [`proc`](chap-ysh-cmd.html#proc)
|
| 88 | - Invokable objects: [`__invoke__`][__invoke__], [`Obj`][Obj]
|
| 89 | - [`simple-command`][simple-command] is how you invoke procs
|
| 90 |
|
| 91 | OSH:
|
| 92 |
|
| 93 | - [`sh-func`](chap-cmd-lang.html#sh-func)
|
| 94 |
|
| 95 | ### Modules
|
| 96 |
|
| 97 | - [`use`](chap-builtin-cmd.html#use)
|
| 98 | - [`is-main`](chap-builtin-cmd.html#is-main)
|
| 99 | - provide (TODO)
|
| 100 | - [`_this_dir`](chap-special-var.html#_this_dir)
|
| 101 | - [`__provide__`](chap-special-var.html#__provide__)
|
| 102 | - An imported module is an [`Obj`][Obj] with an [`__invoke__`][__invoke__]
|
| 103 | method
|
| 104 |
|
| 105 | [Obj]: chap-type-method.html#Obj
|
| 106 | [__invoke__]: chap-type-method.html#__invoke__
|
| 107 |
|
| 108 | OSH:
|
| 109 |
|
| 110 | - [`source`](chap-builtin-cmd.html#source)
|
| 111 | - [`source-guard`](chap-builtin-cmd.html#source-guard)
|
| 112 |
|
| 113 | ### Interactive Shell
|
| 114 |
|
| 115 | - [`renderPrompt()`](chap-plugin.html#renderPrompt)
|
| 116 |
|
| 117 | OSH:
|
| 118 |
|
| 119 | - [`complete`][complete]
|
| 120 | - Oils enhancements: [`compexport`][compexport], [`compadjust`][compadjust]
|
| 121 |
|
| 122 | [complete]: chap-builtin-cmd.html#complete
|
| 123 | [compadjust]: chap-builtin-cmd.html#compadjust
|
| 124 | [compexport]: chap-builtin-cmd.html#compexport
|
| 125 |
|
| 126 | ### Job Control
|
| 127 |
|
| 128 | - [`ampersand &`](chap-cmd-lang.html#ampersand)
|
| 129 | - YSH has [`fork`](chap-builtin-cmd.html#fork)
|
| 130 | - [`wait`](chap-builtin-cmd.html#wait)
|
| 131 | - YSH adds `--all --verbose`: [`ysh-wait`](chap-builtin-cmd.html#ysh-wait)
|
| 132 | - [`fg`](chap-builtin-cmd.html#fg)
|
| 133 | - [`bg`](chap-builtin-cmd.html#bg)
|
| 134 | - [`$!`](chap-special-var.html#POSIX-Special)
|
| 135 |
|
| 136 | ### Tracing Execution
|
| 137 |
|
| 138 | - `set -x` aka `set -o xtrace`
|
| 139 | - [PS4][]
|
| 140 | - `SHX_*`
|
| 141 |
|
| 142 | [PS4]: chap-plugin.html#PS4
|
| 143 |
|
| 144 | ### Introspecting the Call Stack
|
| 145 |
|
| 146 | OSH Debug Stack:
|
| 147 |
|
| 148 | - [BASH_SOURCE](chap-special-var.html#BASH_SOURCE)
|
| 149 | - [FUNCNAME](chap-special-var.html#FUNCNAME)
|
| 150 | - [BASH_LINENO](chap-special-var.html#BASH_LINENO)
|
| 151 |
|
| 152 | YSH Debug Stack:
|
| 153 |
|
| 154 | - [DebugFrame](chap-type-method.html#DebugFrame)
|
| 155 | - [toString()](chap-type-method.html#toString) method
|
| 156 | - [vm.getDebugStack()](chap-type-method.html#getDebugStack)
|
| 157 |
|
| 158 | These may be combined with
|
| 159 |
|
| 160 | - [trap][] `ERR`
|
| 161 | - [set][] `-o errtrace` aka `set -E`
|
| 162 |
|
| 163 | [trap]: chap-builtin-cmd.html#trap
|
| 164 | [set]: chap-builtin-cmd.html#set
|
| 165 |
|
| 166 | ### Reflection
|
| 167 |
|
| 168 | Other YSH reflection:
|
| 169 |
|
| 170 | - The [`io`][io] object has `eval()` methods, etc.
|
| 171 | - The [`vm`][vm] object for inspecting interpreter structures
|
| 172 |
|
| 173 | [io]: chap-type-method.html#io
|
| 174 | [vm]: chap-type-method.html#vm
|
| 175 |
|
| 176 |
|
| 177 | ### Unicode
|
| 178 |
|
| 179 | - TODO: which functions respect Unicode?
|
| 180 |
|
| 181 | Also see [the Unicode doc](../unicode.html).
|
| 182 |
|
| 183 |
|
| 184 | ## YSH Only
|
| 185 |
|
| 186 | ### Objects
|
| 187 |
|
| 188 | - [`Obj`][Obj]
|
| 189 | - [`__invoke__`][__invoke__]
|
| 190 | - TODO: `__call__`
|
| 191 | - [`first()`][first] and [`rest()`][first]
|
| 192 | - [`ENV`][ENV] is an `Obj`
|
| 193 | - operator `.` [ysh-attr](chap-expr-lang.html#ysh-attr)
|
| 194 | - operator `->` [thin-arrow](chap-expr-lang.html#thin-arrow)
|
| 195 |
|
| 196 |
|
| 197 | [first]: chap-builtin-func.html#first
|
| 198 | [rest]: chap-builtin-func.html#rest
|
| 199 |
|
| 200 | ### Closures
|
| 201 |
|
| 202 | A **closure** is a way of bundling data and code. The idea originated in Lisp,
|
| 203 | and is widely used in JavaScript.
|
| 204 |
|
| 205 | YSH behaves much like JavaScript. Exception: YSH has flat function scope,
|
| 206 | **except** for the body of `for` loops.
|
| 207 |
|
| 208 | - Types that are closures:
|
| 209 | - [Command][] and [Expr][]
|
| 210 | - [Proc][] and [Func][]
|
| 211 | - [ysh-for][] creates new frames, which may be captured by any of the 4 closure
|
| 212 | types
|
| 213 | - This is enabled with `shopt --set for_loop_frames`, part of option group
|
| 214 | `ysh:all`
|
| 215 | - [var][] and [setvar][] determine if you're creating a new variable, or
|
| 216 | modifying one that's "closed over"
|
| 217 |
|
| 218 | [Command]: chap-type-method.html#Command
|
| 219 | [Expr]: chap-type-method.html#Expr
|
| 220 | [Proc]: chap-type-method.html#Proc
|
| 221 | [Func]: chap-type-method.html#Func
|
| 222 |
|
| 223 | [ysh-for]: chap-cmd-lang.html#ysh-for
|
| 224 |
|
| 225 | [var]: chap-ysh-cmd.html#var
|
| 226 | [setvar]: chap-ysh-cmd.html#setvar
|
| 227 |
|
| 228 | ### Funcs
|
| 229 |
|
| 230 | - [`func`](chap-ysh-cmd.html#func)
|
| 231 | - Callable objects: [`__call__`][__call__] and [`Obj`][Obj] (TODO)
|
| 232 | - [`ysh-func-call`](chap-expr-lang.html#ysh-func-call)
|
| 233 |
|
| 234 | [__call__]: chap-type-method.html#__call__
|
| 235 |
|
| 236 | ### Namespaces
|
| 237 |
|
| 238 | - [`ENV`](chap-special-var.html#ENV)
|
| 239 | - [`__builtins__`](chap-special-var.html#__builtins__)
|
| 240 |
|
| 241 | ### Purity
|
| 242 |
|
| 243 | - [`shell-flags`](chap-front-end.html#shell-flags) for `--eval-pure`
|
| 244 | - [`func/eval`](chap-builtin-func.html#func/eval) and
|
| 245 | [`func/evalExpr`](chap-builtin-func.html#func/evalExpr)
|
| 246 | - [`func`](chap-ysh-cmd.html#func) - functions are pure
|
| 247 | - [`io`](chap-type-method.html#io) and [`vm`](chap-type-method.html#vm) - impure
|
| 248 | behavior is attached to these objects
|
| 249 |
|
| 250 | ## OSH Features
|
| 251 |
|
| 252 | <!--
|
| 253 |
|
| 254 | TODO:
|
| 255 |
|
| 256 | - __modules__
|
| 257 | - does vm.getFrame() belong?
|
| 258 |
|
| 259 | -->
|
| 260 |
|
| 261 |
|