| 1 | ---
|
| 2 | in_progress: yes
|
| 3 | all_docs_url: -
|
| 4 | ---
|
| 5 |
|
| 6 | All Docs
|
| 7 | ========
|
| 8 |
|
| 9 | This page links to all docs. A dagger † means a doc isn't finished.
|
| 10 |
|
| 11 | See [Published Docs](published.html) for those that are ready to read.
|
| 12 |
|
| 13 |
|
| 14 | <!--
|
| 15 | <div id="toc">
|
| 16 | </div>
|
| 17 | -->
|
| 18 |
|
| 19 | ## Good Places to Start
|
| 20 |
|
| 21 | - [A Tour of YSH](ysh-tour.html)
|
| 22 | - [YSH vs. Shell Idioms](idioms.html)
|
| 23 | - [**Oils Reference**](ref/index.html) - underlies the [help][] builtin
|
| 24 | - [FAQ on Docs](faq-doc.html). **Look here if you can't find
|
| 25 | something**.
|
| 26 |
|
| 27 | [help]: ref/chap-builtin-cmd.html#help
|
| 28 |
|
| 29 | ## Preliminaries
|
| 30 |
|
| 31 | - [INSTALL](INSTALL.html). How do I install Oils? This text file is also in
|
| 32 | the `oils-for-unix` tarball.
|
| 33 | - [Portability](portability.html)
|
| 34 | - [Getting Started](getting-started.html). How do I use the shell?
|
| 35 |
|
| 36 | ## Interactive Shell
|
| 37 |
|
| 38 | - [Headless Mode](headless.html). For alternative UIs on top of YSH.
|
| 39 | - [Completion](completion.html) †. We emulate bash completion.
|
| 40 |
|
| 41 | ## OSH is a Compatible Shell
|
| 42 |
|
| 43 | - [Shell Language Idioms](shell-idioms.html) has some advice for using any
|
| 44 | shell, not just Oils.
|
| 45 | - [OSH Standard Library](lib-osh.html) †. Small but useful enhancements.
|
| 46 |
|
| 47 | For sophisticated users:
|
| 48 |
|
| 49 | - [Known Differences Between OSH and Other Shells](known-differences.html)
|
| 50 | - [OSH Quirks](quirks.html) for compatibility.
|
| 51 |
|
| 52 | ## YSH is a New, Powerful Shell
|
| 53 |
|
| 54 | - [A Tour of YSH](ysh-tour.html). Explains YSH from scratch, without referring
|
| 55 | to shell's legacy.
|
| 56 | - [What Breaks When You Upgrade to YSH](upgrade-breakage.html). When you turn
|
| 57 | on YSH, there are some shell constructs you can no longer use. We try to
|
| 58 | minimize the length of this list.
|
| 59 | - [YSH Language FAQ](ysh-faq.html)
|
| 60 | - [YSH Style Guide](style-guide.html)
|
| 61 |
|
| 62 | ### Comparisons
|
| 63 |
|
| 64 | - [YSH vs. Shell Idioms](idioms.html). A list of code snippets.
|
| 65 | - [YSH vs. Shell](ysh-vs-shell.html). High-level descriptions: how does YSH
|
| 66 | differ from Bourne/POSIX shell?
|
| 67 | - [YSH Expressions vs. Python](ysh-vs-python.html). The expression language is
|
| 68 | borrowed from Python, with a few tweaks.
|
| 69 | - [Novelties in OSH and YSH](novelties.html). May be helpful for experienced
|
| 70 | programmers.
|
| 71 |
|
| 72 | ### Design Concepts
|
| 73 |
|
| 74 | - [YSH Language Influences](language-influences.html) - Shell, Python,
|
| 75 | JavaScript, Lisp, ...
|
| 76 | - Syntax
|
| 77 | - [A Feel For YSH Syntax](syntax-feelings.html)
|
| 78 | - [Syntactic Concepts](syntactic-concepts.html) may help you remember the
|
| 79 | language.
|
| 80 | - [Command vs. Expression Mode](command-vs-expression-mode.html).
|
| 81 | - [Warts](warts.html). Mostly for compatibility.
|
| 82 |
|
| 83 | YSH has 3 main sublanguages:
|
| 84 |
|
| 85 | - **Command** language, which now consistently uses `{ }` for blocks.
|
| 86 | - [Hay - Custom Languages for Unix Systems](hay.html). Use Ruby-like
|
| 87 | blocks to declare data and interleaved code.
|
| 88 | - **Word** language.
|
| 89 | - [Simple Word Evaluation](simple-word-eval.html). Written for shell
|
| 90 | experts.
|
| 91 | - **Expression** language on typed data.
|
| 92 | - [Egg Expressions](eggex.html). A new regex syntax, abbreviated *eggex*.
|
| 93 | - [YSH Regex API](ysh-regex-api.html). Convenient and powerful.
|
| 94 |
|
| 95 | Features:
|
| 96 |
|
| 97 | - [Guide to YSH Error Handling](ysh-error.html)
|
| 98 | - [Guide to Procs and Funcs](proc-func.html)
|
| 99 | - [Block Literals](block-literals.html) †
|
| 100 | - [Streams, Tables, Processes - awk, R, xargs](stream-table-process.html) †
|
| 101 |
|
| 102 | Crosscutting design issues:
|
| 103 |
|
| 104 | - [Variable Declaration, Mutation, and Scope](variables.html)
|
| 105 | - [Strings: Quotes, Interpolation, Escaping, and Buffers](strings.html) †
|
| 106 | - [Unicode](unicode.html) †. Oils supports and prefers UTF-8.
|
| 107 | - [YSH I/O Builtins](io-builtins.html) †
|
| 108 |
|
| 109 | ## Data Languages Avoid Ad-Hoc Parsing
|
| 110 |
|
| 111 | YSH programs "talk about" these data languages, also called interchange formats
|
| 112 | or protocols. In-memory data structures are *in service* of data languages on
|
| 113 | the wire, **not** the other way around.
|
| 114 |
|
| 115 | - [J8 Notation](j8-notation.html). An upgrade of JSON to bytes, strings,
|
| 116 | lines, and structured data.
|
| 117 | - [JSON](json.html). Some usage details.
|
| 118 | - [Framing](framing.html) †
|
| 119 | - [BYO Protocols](byo.html) - for testing and completion.
|
| 120 |
|
| 121 | ## The Shared Oils Runtime
|
| 122 |
|
| 123 | - [YSH Fixes Shell's Error Handling (`errexit`)](error-handling.html)
|
| 124 | - [Oils Error Catalog, With Hints](error-catalog.html)
|
| 125 | - [Tracing Execution](xtrace.html). YSH enhances shell's `set -x`.
|
| 126 | - [Options](options.html) †. Parsing and runtime options turn OSH into YSH.
|
| 127 |
|
| 128 | Internal details:
|
| 129 |
|
| 130 | - [Interpreter State](interpreter-state.html) †. What's inside a shell
|
| 131 | interpreter?
|
| 132 | - [Process Model](process-model.html) †. The shell language is a thin
|
| 133 | layer over the Unix kernel.
|
| 134 |
|
| 135 | ## For Contributors
|
| 136 |
|
| 137 | - [README.md](oils-repo/README.html). If you want to modify Oils, start here.
|
| 138 | We welcome contributions!
|
| 139 | - [Doc Toolchain](doc-toolchain.html) and [Doc Plugins](doc-plugins.html).
|
| 140 | - [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki)
|
| 141 | - [Old Docs](old/index.html). Drafts that may be deleted.
|
| 142 |
|
| 143 | Internal Architecture:
|
| 144 |
|
| 145 | - [Notes on Oils Architecture](architecture-notes.html)
|
| 146 | - [Parser Architecture](parser-architecture.html)
|
| 147 | - [Pretty Printing](pretty-printing.html) - March 2024 design notes.
|
| 148 | - [mycpp/README](oils-repo/mycpp/README.html) - How we translate typed Python to
|
| 149 | C++.
|
| 150 |
|
| 151 | ## More
|
| 152 |
|
| 153 | - [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki).
|
| 154 | - [The blog](https://www.oilshell.org/blog/) has useful background information,
|
| 155 | although older posts are more likely to have incorrect information.
|
| 156 | - [The home page](https://www.oilshell.org/) has links to docs for new users.
|
| 157 |
|
| 158 | Old:
|
| 159 |
|
| 160 | - [INSTALL-old](INSTALL-old.html) for the slow `oil-$VERSION` tarball, based on
|
| 161 | CPython.
|
| 162 |
|
| 163 | <!-- vim: set sw=2: -->
|