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

Strings: Quotes, Interpolation, Escaping, and Buffers

Strings are the most important data structure in shell. Oil makes them easier and safer!

This doc addresses these questions:

Shell Features:

Oil Features:

Table of Contents
Summary
For Python/JS/C Users
For Shell Users
Quick Reference
Use Unquoted Strings in Command Mode
Two Kinds of Single-Quoted Strings
Raw with r'C:\Program Files\'
C-Escaped With $'foo\n'
QSN For Data Interchange
Use Double-Quoted Strings For Interpolation
Implicit Safe Interpolation with $[x] (TODO)
Explicit Safe Interpolation With ${x|html} (TODO)
Raw Interpolation with $x (may be unsafe)
Command Sub $(echo hi)
Fast Command Sub ${.myproc} (stdout capture)
Escapers / Codecs (TODO)
Use Triple Quoted Strings Instead of Here Docs (TODO)
Concatenate With "$str1$str2"
Avoid Concatenation in a Loop
Append with Two Styles
echo, printf, write, and ${.myproc} (write_to_buffer)
push and join
Appendix A: Deprecated Shell Constructs
Appendix B: Related Documents

Summary

For Python/JS/C Users

For Shell Users

Preferences:

Quick Reference

echo unquoted          # bare words are allowed in command mode

echo 'with spaces'     # single quoted string
var s = 'with spaces'

# Raw single quoted string, to emphasize literal backslashes
var s = r'C:\Program Files\'

# C-escaped single quoted string
var line = $'foo\n'

# double quoted with safe interpolation (TODO)
echo "<p>hello $[name]</p>"       # default_escaper must be set
echo "<p>hello ${name|html}</p>"  # explicit escaper

# double quoted with unsafe interpolation
echo "hello $name"
echo "hello ${name}_suffix"       # braces delimit variable name

echo $(date +%x)                  # command sub

Still TODO:

echo ${.myproc arg1}

cat <<< '''
   one
   two
   '''

cat <<< $'''
   mu = \u{3bc}
   nul = \x00
   '''

var s = """
   multiline with ${vars}
   $(date +%x)
   ${.myproc arg1}
   """

Use Unquoted Strings in Command Mode

Shell is unique! You don't have to quote strings.

and quoted strings in expression mode

Two Kinds of Single-Quoted Strings

Raw with r'C:\Program Files\'

C-Escaped With $'foo\n'

QSN For Data Interchange

TODO: explain the difference.

This is different! It's data and not code. Analogy to JSON.

Use Double-Quoted Strings For Interpolation

Implicit Safe Interpolation with $[x] (TODO)

Explicit Safe Interpolation With ${x|html} (TODO)

Note you can have bugs if you use the wrong escaper!

Raw Interpolation with $x (may be unsafe)

Note that you should not use "${var}" in Oil code. Use $var or ${var} because of simple word evaluation.

Command Sub $(echo hi)

Fast Command Sub ${.myproc} (stdout capture)

Note that only words are allowed here; not full commands. Wrap other commands in a proc.

TODO:

echo ${.myproc foo|html} # I think this should be supported

Escapers / Codecs (TODO)

For ${x|html} and ${.myproc|html}

TODO

Use Triple Quoted Strings Instead of Here Docs (TODO)

TODO

Concatenate With "$str1$str2"

Or "${str1}${str2}"

Avoid Concatenation in a Loop

setvar s = "${s}${suffix}"

Append with Two Styles

Since there is no ++ operator, there is no ++= operator.

echo, printf, write, and ${.myproc} (write_to_buffer)

echo, printf, and write have their output captured.

proc p(arg) {
  ### A proc that has its output captured quickly.

  echo $arg
  write two

  const x = 'three'
  printf '%s\n' $x

  # newline for interactive testing, but not when captured
  if ! shopt -q write_to_buffer {
    echo  
  }
}

echo ${.p one}  # $'one\ntwo\nthree\n'

push and join

var buf = %()
push :buf 'one '
push :buf $'two\n'
echo $join(buf)

Appendix A: Deprecated Shell Constructs

Appendix B: Related Documents


Generated on Wed Dec 29 23:52:09 EST 2021