commit 7485b67a9f570d762b2081743a20110e40331264
parent ee12542bcea762a51238de3a00d6e59bdbb84d8c
Author: Byron Torres <b@torresjrjr.com>
Date: Thu, 2 Dec 2021 16:28:04 +0000
add tutorial
Diffstat:
| M | README.md | | | 2 | ++ |
| A | tutorial.md | | | 148 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 150 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -9,6 +9,8 @@ prefixed with a signifer. Multilined strings and comments are supported.
Status: draft
+See [tutorial.md](tutorial.md).
+
Example:
# Gemini Spacecraft On-Board Computer (OBC)
diff --git a/tutorial.md b/tutorial.md
@@ -0,0 +1,148 @@
+Nest Tutorial
+=============
+
+A Nest document is a UTF-8 encoded plaintext file. Maps and sequences
+are the primitive data structures for holding collections of strings,
+the sole scalar data type. Empty strings are permitted; there is no null
+type. A document is organised into blocks, which are tab-indented
+(nested) to signify scope, and prefixed with a type signifier.
+
+A comment is a line prefixed with optional whitespace followed by an
+octothorpe `#` (hash, pound). A comment can appear anywhere in a Nest
+document without disrupting other sections.
+
+ # Gemini computer
+ #Stat reports
+
+A nest block contains lines of text, equivalently tab-indented. An
+optional, equivalently tab-indented last line with a single period `.`
+to denote the end of a block is permitted.
+
+ # ...
+ # a nest block
+ # ...
+ .
+
+There are three block types: the map, sequence, and textwall.
+
+A textwall represents a multilined string scalar. Each line is prefixed
+with a pipe `|`. The concatenation of each line, excluding the pipe
+prefix and including the terminating newline character, form the scalar
+string.
+
+Example of a textwall:
+
+ |Station:
+ |
+ |β Hyi
+ | Type circumpolar
+ # 7.459 parsecs
+ | Distance 24.33ly
+ .
+
+JSON equivalent:
+
+ "Station:\n\nβ Hyi\tType circumpolar\tDistance 24.33ly\n"
+
+A sequence holds elements, each either prefixed with a dash-space `- `
+for inline values, or a double-dash `--` for nested values. Inline
+string values start from the first character after `- ` up to and
+excluding the line's terminating newline character. Any element without
+an inline or nested value is considered an empty string.
+
+Example of a sequence, with a nested sequence:
+
+ - Alice Nestler
+ #dob
+ - 2038-01-19 03:14:07
+ --
+ - QEC
+ - Hyperspeed
+ .
+ -
+ --
+ - Barycentric Celestial
+ .
+
+JSON equivalent:
+
+ [
+ "Alice Nestler",
+ "194.22",
+ [
+ "QEC",
+ "Hyperspeed"
+ ],
+ "",
+ "",
+ " Barycentric Celestial ",
+ ]
+
+A map holds key-value pairs, each prefixed with a single period `.`.
+Keys are terminated with a colon-space `: ` for inline values, or
+double-colon `::` for nested values. Whitespace between these signifiers
+and key strings is ignored. Inline string values exist similarly like in
+sequences.
+
+An example of a map, with one nested map:
+
+ .host: aurelis-38
+ # Gemini computer
+ .stat::
+ .frequency: 7.143
+ .power: 26 V DC
+ .
+ .reference system: barycentric celestial
+ .alpha:
+ .omega::
+ . equinox : J2000.0 SOL
+ . : Christopher Null
+ .
+
+JSON equivalent:
+
+ {
+ "host": "aurelis-38",
+ "stat": {
+ "frequency": "7.143",
+ "power": "26 V DC"
+ },
+ "reference system": "barycentric celestial",
+ "alpha": "",
+ "omega": "",
+ " equinox ": " J2000.0 SOL ",
+ "": "Christopher Null"
+ }
+
+A block with mixed content types is invalid.
+
+ # invalid block
+ .name: Alice Nestler
+ - 382
+ |Circumpolar constellation
+
+Maps and sequences can contain (nest) other blocks in various ways.
+
+ .title: Nest Example
+ .maps::
+ .alpha: red
+ .bravo: green
+ .charlie: blue
+ .sequences::
+ - Alice Nestler
+ --
+ - one
+ - two
+ - three
+ --
+ .alpha: red
+ .bravo: green
+ .charlie: blue
+ --
+ |The quick brown
+ |fox jumps over
+ |the lazy dog.
+ .textwall::
+ |The early bird
+ |catches the worm.
+
