~torresjrjr/nest

ref: HEAD nest/tutorial.md -rw-r--r-- 3.2 KiB
641f806cByron Torres ignore inline surrounding whitespace 5 months ago

#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 string scalar is equivalent to the textwall, excluding the pipe prefixes and including the terminating newline characters.

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 preceded with a dash-dash (--) line for nested values. Whitespace surrounding inline string values is ignored. Any absent value, inline or nested, 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",
	"2038-01-19 03:14:07",
	[
		"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 colon-colon (::) for nested values. Whitespace between these signifiers and key strings is ignored. Whitespace surrounding inline string values is ignored. Any absent value, inline or nested, is considered an empty string.

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
.map::
	.alpha: red
	.bravo: green
	.charlie: blue
.sequence::
	- 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.