Why Sponsor Oils? | source | all docs for version 0.19.0 | all versions | oilshell.org

YSH FAQ

Here are some common questions about YSH. Many of the answers boil down to the fact that YSH is a smooth upgrade from bash.

Old and new constructs exist side-by-side. New constructs have fewer "gotchas".

What's the difference myvar, $myvar, and "$myvar" ?

YSH is more like Python/JavaScript rather than PHP/Perl, so it doesn't use the $ sigil as much.

Never use $ on the left-hand side:

var mystr = "foo"   # not var $mystr

Use $ to substitute vars into commands:

echo $mystr
echo $mystr/subdir  # no quotes in commands

or quoted strings:

echo "$mystr/subdir"
var x = "$mystr/subdir"

Rarely use $ on the right-hand side:

var x = mystr       # preferred
var x = $mystr      # ILLEGAL -- use remove $
var x = ${mystr:-}  # occasionally useful

var x = $?          # allowed

See Command vs. Expression Mode for more details.

How do I write ~/src or ~bob/git in a YSH assignment?

This should cover 80% of cases:

var path = "$HOME/src"  # equivalent to ~/src

The old shell style will cover the remaining cases:

declare path=~/src
readonly other=~bob/git

This is only in issue in expressions. The traditional shell idioms work in command mode:

echo ~/src ~bob/git
# => /home/alice/src /home/bob/git

The underlying design issue is that the YSH expression ~bob looks like a unary operator and a variable, not some kind of string substitution.

Also, quoted "~" is a literal tilde, and shells disagree on what ~"" means. The rules are subtle, so we avoid inventing new ones.

How do I write echo -e or echo -n?

To escape variables, you can use the string language, rather than echo:

echo $'tab \t newline \n'   # YES
echo j"tab \t newline \n"   # TODO: J8 notation

echo -e tab \t newline \n'  # NO

To omit the newline, use the write builtin:

write -n 'prefix'           # YES
write --end '' -- 'prefix'  # synonym

echo -n 'prefix'            # NO

Why Were -e and -n Removed?

Without the flags, you can write echo $flag without the 2 corner cases that are impossible to fix. Shell's echo doesn't accept --.

Note that write -- $x is equivalent to echo $x in YSH, so echo is superfluous. But we wanted the short and familiar echo $x to work.

What's the difference between $(dirname $x) and $[len(x)] ?

Superficially, both of these syntaxes take an argument x and return a string. But they are different:

• $(dirname $x) is a shell command substitution that returns a string, and starts another process.
• $[len(x)] is an expression sub containing a function call expression.
  • It doesn't need to start a process.
  • Note that len(x) evaluates to an integer, and $[len(x)] converts it to a string.

Why doesn't a raw string work here: ${array[r'\']} ?

This boils down to the difference between OSH and YSH, and not being able to mix the two. Though they look similar, ${array[i]} syntax (with braces) is fundamentally different than $[array[i]] syntax (with brackets).

• OSH supports ${array[i]}.
  • The index is legacy/deprecated shell arithmetic like ${array[i++]} or ${assoc["$key"]}.
  • The index cannot be a raw string like r'\'.
• YSH supports both, but expression substitution syntax $[array[i]] is preferred.
  • It accepts YSH expressions like $[array[i + 1] or $[mydict[key]].
  • A raw string like r'\' is a valid key, e.g. $[mydict[r'\']].

Of course, YSH style is preferred when compatibility isn't an issue.

No:

echo ${array[r'\']}

Yes:

echo $[array[r'\']]

A similar issue exists with arithmetic.

Old:

echo $((1 + 2))   # shell arithmetic

New:

echo $[1 + 2]     # YSH expression

Related

• Oil Language FAQ on the wiki has more answers. They may be migrated here at some point.