From 8484220d8b364d118288cf204a1459f45b37cb1d Mon Sep 17 00:00:00 2001 From: Taylan Kammer Date: Wed, 3 Jun 2026 13:08:50 +0200 Subject: Last parser doc touch up before I move on. --- doc/c1/1-parse.md | 45 ++++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 21 deletions(-) (limited to 'doc/c1') diff --git a/doc/c1/1-parse.md b/doc/c1/1-parse.md index 4a8c22b..babf160 100644 --- a/doc/c1/1-parse.md +++ b/doc/c1/1-parse.md @@ -11,9 +11,27 @@ which is necessary to strategically construct more complex values: | E.G. | foobar | #name | (X & Y) | () | +-------+---------+--------+----------+------+ -The parser also recognizes various *syntax sugar* which typically results in a -pair beginning with a specific rune. A separate component called the *decoder* -transforms such data into a rich set of value types. +The parser recognizes various *syntax sugar* which abbreviates verbose syntax, +and may result in special data structures (typically, a pair with a rune in its +first, and payload in its second position) which another Zisp component called +the *decoder* can transform into a rich set of value types. + +The most ubiquitous syntax sugar is the list, which abbreviates a sequence of +tail-linked pairs, terminated with a special nil value represented as `()`: + + (x) -> (x & ()) + + (x y) -> (x & (y & ())) + + (x y z) -> (x & (y & (z & ()))) + +The following are so-called *improper lists*, ending in a non-nil value: + + (x y & z) -> (x & (y & z)) + + (x y z & t) -> (x & (y & (z & t))) + +More details about syntax sugar, and the decoder, are explained later. ## Character Encoding @@ -99,7 +117,8 @@ datum. In other words, a datum is a value that can be printed out as a byte sequence which the parser can turn back into an equivalent datum. A value that is not a datum may nevertheless be *encoded* into one, allowing it -to have an external representation. After parsing, it needs to be *decoded*. +to have an external representation. After parsing, it needs to be *decoded* to +actually become the expected value. One may speak of an *external representation of a value* where the value is not itself a datum, but can be encoded as one. The more strictly correct term for @@ -115,23 +134,7 @@ As an example, the expression `#(x y z)` is an abbreviation for the equivalent after parsing, both will yield values that are indistinguishable in all but their memory address. -The most ubiquitous syntax sugar is the list, which abbreviates a sequence of -tail-linked pairs, terminated with a special nil value represented as `()`: - - (x) -> (x & ()) - - (x y) -> (x & (y & ())) - - (x y z) -> (x & (y & (z & ()))) - -There are also so-called *improper lists* which are chains of pairs that end in -a value other than nil: - - (x y & z) -> (x & (y & z)) - - (x y z & t) -> (x & (y & (z & t))) - -An example of "syntax sugar" that is not a mere abbreviation is a quoted string +An example of syntax sugar that is not a mere abbreviation is a quoted string which contains bytes that could not appear in a *bare* string: "foo bar" -> (#DQUOTE & ) -- cgit v1.2.3