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