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

QSN: A Familiar String Interchange Format

Taglines:

Rough Analogy:

Javacript Literals : JSON :: Rust String Literals : QSN

Examples:

'my favorite song.mp3'
'bob\t1.0\ncarol\t2.0\n'  # TODO syntax highlight this
'byte: \xff character: \u{03bc}'

We want a single way to serialize and parse arbitrary byte strings (which may be encoded in UTF-8 or another encoding.)

TODO: copy content from this page: https://github.com/oilshell/oil/wiki/CSTR-Proposal

Table of Contents
Who Should Use QSN?
Use Case: set -x format (xtrace)
Design
Display Special Characters
Three options For Displaying Unicode
Special Chars Emitted
Extensions
Links

Who Should Use QSN?

Use Case: set -x format (xtrace)

Unquoted:

$ set -x
$ echo a b
+ echo a b

We need single quotes '1 2' to make arguments with spaces unambiguous:

$ set -x
$ x='a b'
$ echo "$x" c
+ echo 'a b' c

We need C-escaped strings $'1\n2' to make arguments with newlines fit on a line:

$ set -x
$ x=$'a\nb'
$ echo "$x" c
+ echo $'a\nb' 3

And to show unprintable characters safely on a terminal:

$ set -x
$ x=$'\e\001'
$ echo "$x"
echo $'\x1b\x01'

Design

$'\x01\n'  # shell-compatible (but confusing)
c'\x01\n'  # explicit CSTR
'\x01\n'   # implicit CSTR, which is similar ro Python format

Display Special Characters

Three options For Displaying Unicode

  1. Don't decode UTF-8. Just show bytes like '\xce\xbc'.
  2. Decode UTF-8. This could be useful for showing at a glance if we have valid UTF-8 strings. a. Show code points like '\u03bc'. ASCII friendly, so better for weird debugging situations. b. Show them literally. Depends on the terminal.

Special Chars Emitted

Extensions

Links


Generated on Thu May 21 12:33:04 PDT 2020