NOTE: This document is a work in progress!

OSH Quick Reference

Version 0.3.0

- Below is a list of topics, organized into [Sections].
- Features not yet implemented have an X prefix.
- View it on the web at https://www.oilshell.org/TODO

INTRO
  [Overview]      overview
  [Usage]         osh-usage   oil-usage   config   startup   line-editing
                  prompt

COMMAND LANGUAGE
  [Commands]      simple-command   semicolon ;
  [Conditional]   case   if   true   false   colon :
                  bang !   and &&   or ||   dbracket [[
  [Iteration]     while   until   for   for-expr ((
  [Control Flow]  break   continue   return
  [Grouping]      function   block {   subshell (
  [Concurrency]   pipe   |   X |&
                  ampersand &   X proc-sub
  [Redirects]     redir-file  >  >>  >|  <  <>   X &>
                  redir-desc  >&  <&
                  here-doc    <<  <<-  <<<
  [Other]         dparen ((   time   X coproc   X select

ASSIGNING VARIABLES
  [Keywords]      local   readonly   export   unset   shift
                  X declare   X typeset   X let
  [Operators]     assign        str='xyz'
                  append        str+='abc'
  [Compound Data] array         array=(a b c)   array[x]=b
                  X assoc       declare -A assoc=([a]=1 [b]=2)

WORD LANGUAGE
  [Quotes]        quotes        'abc'  $'\n'  "$var"
  [Substitutions] com-sub       $(command)   `command`
                  var-sub       ${var}
                  arith-sub     $((1 + 2))  $[1 + 2]
                  tilde-sub     ~/src
                  X proc-sub    diff <(sort L.txt) <(sort R.txt)
  [Special Vars]  special-vars  $?  $#  $PPID  $IFS  ...
  [Var Ops]       op-test       ${x:-default}  
                  op-unary      ${x%%suffix}  etc.
                  op-str        ${x/y/z}
                  X op-slice    ${a[@]:0:1}

OTHER SHELL SUBLANGUAGES
  [Arithmetic]    arith-intro   Contexts where math is allowed
                  num-literals  0xFF  0755  etc.
                  math          1 + 2*3
                  arith-logical !a && b
                  bitwise       ~a ^ b
                  arith-assign  a *= 2
  [Boolean]       dbracket      [[ $a == $b ]]
  [Patterns]      glob          *.py
                  X extglob     @(*.py|*.sh)
                  regex         [[ foo =~ [a-z]+ ]]
  [Brace Expand]  braces        {alice,bob}@example.com

BUILTIN COMMANDS
  [I/O]           read   echo 
                  X readarray   X mapfile
  [Run Code]      source .   eval
  [Set Options]   set   shopt
  [Working Dir]   cd   pwd   pushd   popd   dirs
  [Completion]    complete   X compgen   X compopt
  [Shell Process] exec   exit   X logout 
                  umask   X ulimit   X trap   X times
  [Child Process] jobs   wait   ampersand &
                  X fg   X bg   X disown 
  [External]      test [   X printf   getopts   X kill
  [Introspection] help   X hash   type   X caller
X [Word Lookup]   command   builtin
X [Interactive]   alias   unalias   bind   history   fc
X [Unsupported]   enable

SHELL OPTIONS
  [Errors]        nounset   errexit   pipefail
  [Globbing]      noglob   failglob   nullglob
  [Debugging]     xtrace   X verbose
  [Other]         X noclobber
  [Parsing]       TODO
  [OSH Strict]    TODO
  [OSH Sane]      TODO








Introduction


Overview


overview


OSH is a shell.


Usage


Usage of the OSH Binary

Usage: osh [OPTION]... SCRIPT [ARG]...
       osh [OPTION]... -c COMMAND [ARG]...

osh accepts POSIX sh flags, with the following differences:

  -n             only validate the syntax.  Also prints the AST.
  --show-ast     print the AST in addition to executing.
  --ast-format   what format the AST should be in


Usage of the Oil Binary

Usage: oil MAIN_NAME [ARG]...
       MAIN_NAME [ARG]...

oil behaves like busybox.  If it's invoked through a symlink, e.g. 'osh', then
it behaves like that binary.  Otherwise the binary name can be passed as the
first argument, e.g.:

    oil osh -c 'echo hi'


Configuration Files


Shell Startup


Line Editing


Customizing the Prompt String


Command Language


The command language is specified by the POSIX shell grammar.

Commands


Simple Commands

Simple commands are separated by words:
    ls /

Redirects can also appear anywhere
    echo hi 1>&2

Semi-colon ;

;  -- separate statements

Conditional Constructs


case



if


true false colon :


bang !


and && or ||


dbracket [[

For conditionals.

Iteration Constructs


while until


for for-expr


Grouping Constructs


function


block


subshell


Concurrency


pipe


ampersand &


Redirects


redir-file


redir-desc


here-doc


Other Commands


dparen ((


time


coproc



Assigning Variables


Assignment Keywords


Assignment Operators


Compound Data Structures



Word Language


Quotes


Substitutions


Special Variables


Operations on Variables



Other Shell Sublanguages


Arithmetic


Boolean


Patterns


Brace Expansion


Builtin Commands


OSH aims to have almost all of the builtins that bash does.  Here they are,
divided into sections.

I/O Builtins


These builtins take input and output.  They are often used with redirects[1].

[1] help redirects

read

Usage: read -p 

Or maybe get rid of #END -- it can just go until the next # command.  It's a
little bit like the spec tests honestly.  Can copy sh_specpy

Run Code

source .   eval

Set Shell Options

set   X shopt

Builtins - Working Dir

cd   pwd   pushd   popd   dirs

Completion

complete   X compgen   X compopt

Shell Process Control

exec   exit   X logout 
umask   X ulimit   X trap   X times

Child Process Control

jobs   wait   ampersand &
X fg   X bg   X disown 

Builtins That Introspect


help

Usage:
  help <topic>   -- show help on a given topic
  help toc       -- list help topics
  help osh-usage -- same as osh --help
  help oil-usage -- same as oil --help

View on the web: http://www.oilshell.org/$VERSION/doc/osh-quick-ref.html

hash


caller


type


Builtins That Are Like External Commands


External: bash has builtins that replace these external commands, but OSH
doesn't)

getopt


use /usr/bin/getopt

kill


bash accepts job control syntax

enable


Bash has this, but OSH won't implement it.

Shell Options



Parsing Options


Execution Options


Options Only in OSH




Generated on Thu Dec 21 23:41:14 PST 2017