nest

A simple, line-oriented data serialisation format
git clone https://git.torresjrjr.com/nest.git
Log | Files | Refs | README | LICENSE

tutorial.md (3230B)


      1 Nest Tutorial
      2 =============
      3 
      4 A Nest document is a UTF-8 encoded plaintext file. Maps and sequences
      5 are the primitive data structures for holding collections of strings,
      6 the sole scalar data type. Empty strings are permitted; there is no null
      7 type. A document is organised into blocks, which are tab-indented
      8 (nested) to signify scope, and prefixed with a type signifier.
      9 
     10 A comment is a line prefixed with optional whitespace followed by an
     11 octothorpe (`#`) (hash, pound). A comment can appear anywhere in a Nest
     12 document without disrupting other sections.
     13 
     14 	# Gemini computer
     15 	#Stat reports
     16 
     17 A nest block contains lines of text, equivalently tab-indented. An
     18 optional, equivalently tab-indented last line with a single period (`.`)
     19 to denote the end of a block is permitted.
     20 
     21 	# ...
     22 	# a nest block
     23 	# ...
     24 	.
     25 
     26 There are three block types: the map, sequence, and textwall.
     27 
     28 A textwall represents a multilined string scalar. Each line is prefixed
     29 with a pipe (`|`). The string scalar is equivalent to the textwall,
     30 excluding the pipe prefixes and including the terminating newline
     31 characters.
     32 
     33 Example of a textwall:
     34 
     35 	|Station:
     36 	|
     37 	|β Hyi
     38 	|	Type circumpolar
     39 		# 7.459 parsecs
     40 	|	Distance 24.33ly
     41 	.
     42 
     43 JSON equivalent:
     44 
     45 	"Station:\n\nβ Hyi\tType circumpolar\tDistance 24.33ly\n"
     46 
     47 A sequence holds elements, each either prefixed with a dash-space (`- `)
     48 for inline values, or preceded with a dash-dash (`--`) line for nested
     49 values. Whitespace surrounding inline string values is ignored. Any
     50 absent value, inline or nested, is considered an empty string.
     51 
     52 Example of a sequence, with a nested sequence:
     53 
     54 	- Alice Nestler
     55 	#dob
     56 	- 2038-01-19 03:14:07
     57 	--
     58 		- QEC
     59 		- Hyperspeed
     60 		.
     61 	-
     62 	--
     63 	-    Barycentric Celestial   
     64 	.
     65 
     66 JSON equivalent:
     67 
     68 	[
     69 		"Alice Nestler",
     70 		"2038-01-19 03:14:07",
     71 		[
     72 			"QEC",
     73 			"Hyperspeed"
     74 		],
     75 		"",
     76 		"",
     77 		"Barycentric Celestial"
     78 	]
     79 
     80 A map holds key-value pairs, each prefixed with a single period (`.`).
     81 Keys are terminated with a colon-space (`: `) for inline values, or
     82 colon-colon (`::`) for nested values. Whitespace between these
     83 signifiers and key strings is ignored. Whitespace surrounding inline
     84 string values is ignored. Any absent value, inline or nested, is
     85 considered an empty string.
     86 
     87 An example of a map, with one nested map:
     88 
     89 	.host: aurelis-38
     90 	# Gemini computer
     91 	.stat::
     92 		.frequency: 7.143
     93 		.power: 26 V DC
     94 		.
     95 	.reference system: barycentric celestial
     96 	.alpha:
     97 	.omega::
     98 	.   equinox   :   J2000.0 SOL   
     99 	.  : Christopher Null
    100 	.
    101 
    102 JSON equivalent:
    103 
    104 	{
    105 		"host": "aurelis-38",
    106 		"stat": {
    107 			"frequency": "7.143",
    108 			"power": "26 V DC"
    109 		},
    110 		"reference system": "barycentric celestial",
    111 		"alpha": "",
    112 		"omega": "",
    113 		"equinox": "J2000.0 SOL",
    114 		"": "Christopher Null"
    115 	}
    116 
    117 A block with mixed content types is invalid.
    118 
    119 	# invalid block
    120 	.name: Alice Nestler
    121 	- 382
    122 	|Circumpolar constellation
    123 
    124 Maps and sequences can contain (nest) other blocks in various ways.
    125 
    126 	.title: Nest Example
    127 	.map::
    128 		.alpha: red
    129 		.bravo: green
    130 		.charlie: blue
    131 	.sequence::
    132 		- Alice Nestler
    133 		--
    134 			- one
    135 			- two
    136 			- three
    137 		--
    138 			.alpha: red
    139 			.bravo: green
    140 			.charlie: blue
    141 		--
    142 			|The quick brown
    143 			|fox jumps over
    144 			|the lazy dog.
    145 	.textwall::
    146 		|The early bird
    147 		|catches the worm.
    148