Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

Interpreter State

The Oils project has a single interpreter that supports both the OSH and YSH languages.

In other words, It's useful to think of Unix shell in historical layers:

Table of Contents
Example
Design Goals
Simplify and Rationalize bash
Add New Features and Types
High Level Description
Memory Is a Stack
Environment Variables Become Global Variables
Functions and Variables Are Separate
Variable Name Lookup with "Dynamic Scope"
Limitations of Arrays And Compound Data Structures
Integers and Coercion
Unix fork() Has Copy-On-Write Semantics
Key Data Types
cell
value
cmd_value for shell builtins
Printing State
Shell Builtins
pp in Oils
Modifying State
YSH Keywords
Shell Assignment Builtins: declare/typeset, readonly, export
unset
Other Builtins
Links
Appendix: Bash Issues
Strings and Arrays Are Confused
Indexed Arrays and Associative Arrays Are Confused
Empty and Unset Are Confused

Example

Shell has many syntaxes for the same semantics, which can be confusing. For example, in bash, these four statements do similar things:

$ foo='bar'
$ declare -g foo=bar
$ x='foo=bar'; typeset $x
$ printf -v foo bar

$ echo $foo
bar

In addition, YSH adds JavaScript-like syntax:

var foo = 'bar'

YSH syntax can express more data types, but it may also confuse new users.

So the sections below describe the shell from a semantic perspective, which should help users reason about their programs.

Quick tip: Use the pp builtin to inspect shell variables.

Design Goals

Simplify and Rationalize bash

POSIX shell has a fairly simple model: everything is a string, and "$@" is a special case.

Bash adds many features on top of POSIX, including arrays and associative arrays. Oils implements those features, and a few more.

However, it also significantly simplifies the model.

A primary difference is mentioned in Known Differences:

In other words, Oils "salvages" the confusing semantics of bash and produces something simpler, while still being very compatible.

Add New Features and Types

TODO

High Level Description

Memory Is a Stack

Environment Variables Become Global Variables

On initialization, environment variables like PYTHONPATH=. are copied into the shell's memory as global variables, with the export flag set.

Global variables are stored in the first stack frame, i.e. the one at index 0.

Functions and Variables Are Separate

There are two distinct namespaces. For example:

foo() {
  echo 'function named foo'
}
foo=bar   # a variable; doesn't affect the function

Variable Name Lookup with "Dynamic Scope"

OSH has it, but YSH limits it.

Limitations of Arrays And Compound Data Structures

Shell is a value-oriented language.

Example:

declare -a myarray=("${other_array[@]}")   # shell

var myarray = :| @other_array |            # Oils

Reason: There's no Garbage collection.

Integers and Coercion

Unix fork() Has Copy-On-Write Semantics

See the Process Model document.

Key Data Types

TODO: core/runtime.asdl

cell

TODO

value

Undef, Str, Sequential/Indexed Arrays, Associative Array

cmd_value for shell builtins

Another important type:

  assign_arg = (lvalue lval, value? rval, int spid)

  cmd_value =
    Argv(string* argv, int* arg_spids, command__BraceGroup? block)
  | Assign(builtin builtin_id,
           string* argv, int* arg_spids,
           assign_arg* pairs)

Printing State

Shell Builtins

Oils supports various shell and bash operations to view the interpreter state.

pp in Oils

Pretty prints a cell.

This is cleaner!

TODO: What about functions

Modifying State

YSH Keywords

TODO: See YSH Keywords doc.

Shell Assignment Builtins: declare/typeset, readonly, export

...

unset

You can't unset an array in OSH? But you can in bash.

Other Builtins

Links

Appendix: Bash Issues

Strings and Arrays Are Confused

Horrible

a=('1 2' 3)
b=(1 '2 3')  # two different elements

[[ $a == $b ]]
[[ ${a[0]} == ${b[0]} ]]

[[ ${a[@]} == ${b[@]} ]]

Associative arrays and being undefined

Indexed Arrays and Associative Arrays Are Confused

Empty and Unset Are Confused

Generated on Tue, 09 Jul 2024 16:09:03 +0000