OSH User Manual

OSH is a Unix shell designed to run existing shell scripts. More precisely, it's

  1. POSIX-compatible
  2. Has features from GNU Bash, the most commonly used shell.

It's designed to be "stricter" than other shells. To avoid programs that don't behave as intended,

  1. It produces more errors.
  2. It produces them earlier — at parse time, if possible.

"Batch" programs are most likely to run unmodified under OSH. Interactive programs like .bashrc and bash completion scripts may require small changes.

This manual covers the differences between OSH and other shells. It leaves the details of each construct to the help builtin, which is also available online (Warning: incomplete). It also doesn't cover the Oil language, which is a newer part of the Oil project.

Existing educational materials for the Unix shell apply to OSH, because they generally don't teach the quirks that OSH disallows. For example, much of the information and advice in BashGuide can be used without worrying about which shell you're using. See the end of this manual for more resources.

Table of Contents
Downloading OSH
Setup
Startup Files
Global Execution Options
shopt -s strict:all is Recommended
List of Options
Features Unique to OSH
Dumping the AST
OSH_HIJACK_SHEBANG
--debug-file
Crash Dumps
Completion API
Exit Codes
Unicode
Program Encoding
Data Encoding
Bugs
Links

Downloading OSH

The releases page links to source tarballs for every release. It also links to the documentation tree, which includes this manual.

Setup

After running the instructions in INSTALL, run:

mkdir -p ~/.config/oil

Startup Files

On startup, the interactive shell sources only ~/.config/oil/oshrc.

Other shells have a confusing initialization sequence involving many files (original). It's very hard to tell when and if /etc/profile, ~/.bashrc, ~/.bash_profile, etc. are executed.

OSH intentionally avoids this. If you want those files, simply source them in your oshrc.

I describe my own oshrc file on the wiki: How To Test OSH.

Global Execution Options

All Unix shells have global options that affect execution. There are two kinds:

List them all with set -o and shopt -p. Other than syntax, there's no essential difference between the two kinds.

shopt -s strict:all is Recommended

OSH adds more options on top of those provided by POSIX and bash. It has a shortcut shopt -s strict:all which turns on many options at once:

If you want your script to be portable to other shells, use this line:

shopt -s strict:all 2>/dev/null || true  # suppress errors

You can also turn individual options on or off:

shopt -s strict_array  # Set this option.  I want more fatal errors.
shopt -u strict_array  # Unset it.  Ignore errors and keep executing.

List of Options

strict_arith. Strings that don't look like integers cause a fatal error in arithmetic expressions.

strict_argv. Empty argv arrays are disallowed since there's no practical use for them. For example, the second statement in x=''; $x results in a fatal error.

strict_array. No implicit conversions between string an array. In other words, turning this on gives you a "real" array type.

strict_control_flow. break and continue outside of a loop are fatal errors.

simple_eval_builtin. The eval builtin takes exactly one argument. It doesn't concatenate its arguments with spaces, or accept zero arguments.

strict_word_eval. More word evaluation errors are fatal.

For options affecting exit codes, see the errexit doc.

Features Unique to OSH

Dumping the AST

The -n flag tells OSH to parse the program rather than executing it. By default, it prints an abbreviated abstract syntax tree:

$ bin/osh -n -c 'ls | wc -l'
(command.Pipeline children:[(C {(ls)}) (C {(wc)} {(-l)})] negated:F)

You can also ask for the full text format:

$ bin/osh -n --ast-format text -c 'ls | wc -l'
(command.Pipeline
  children: [
    (command.Simple
      words: [
        (word.Compound
          parts: [(word_part.Literal
                   token:(token id:Lit_Chars val:ls span_id:0))]
        )
      ]
    )
    (command.Simple
      words: [
        (word.Compound
          parts: [(word_part.Literal
                   token:(token id:Lit_Chars val:wc span_id:4))]
        )
        (word.Compound
          parts: [(word_part.Literal
                   token:(token id:Lit_Chars val:-l span_id:6))]
        )
      ]
    )
  ]
  negated: F
  spids: [2]
)

This format is subject to change. It's there for debugging the parser, but sophisticated users may use it to interpret tricky shell programs without running them.

OSH_HIJACK_SHEBANG

This environment variable can be set to the path of a shell. Before OSH executes a program, it will inspect the shebang line to see if it looks like a shell script. If it does, it will use this shell instead of the one specified in the shebang line.

For example, suppose you have myscript.sh:

#!/bin/sh
# myscript.sh

./otherscript.sh --flag ...

and otherscript.sh:

#!/bin/sh
# otherscript.sh

echo 'hello world'

Then you can run myscript.sh like this:

OSH_HIJACK_SHEBANG=osh osh myscript.sh

and otherscript.sh will be executed with OSH rather than the /bin/sh.

Note that osh appears twice in that command line: once for the initial run, and once for all recursive runs.

(This is an environment variable rather than a flag because it needs to be inherited.)

--debug-file

Print internal debug logs to this file. It's useful to make it a FIFO:

mkfifo _tmp/debug
osh --debug-file _tmp/debug

Then run this in another window to see logs as you type:

cat _tmp/debug

Related:

Crash Dumps

This is implemented, but a JSON library isn't in the release build.

Completion API

The completion API is modeled after the bash completion API

However, an incompatibility is that it deals with argv entries and not command strings.

OSH moves the responsibility for quoting into the shell. Completion plugins should not do it.

Exit Codes

Unicode

Program Encoding

Shell programs should be encoded in UTF-8 (or its ASCII subset). Unicode characters can be encoded directly in the source:

echo 'μ'

or denoted in ASCII with C-escaped strings, i.e. $'':

echo $'[\u03bc]'

(This construct is preferred over echo -e because it's statically parsed.)

Data Encoding

Strings in OSH are arbitrary sequences of bytes. Caveats:

The GNU iconv program converts text from one encoding to another.

Also, see Notes on Unicode in Shell.

Bugs

Links

External:


Generated on Fri Apr 23 14:40:30 PDT 2021