~cricket/jazz

ref: 1783c2ca502b71708f1867ecdc9277fd3f76fa09 jazz/posts/ckt.ckt -rw-r--r-- 12.9 KiB
1783c2cac piapiac small formatting update 6 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
filename=ckt.html
title=A RANT OF CONFIGS
description=all config formats suck and how mine sucks a little less

pubdate="Tue, 20 Apr 2021 00:15:00 PDT"
lastbuilddate="Tue, 20 Apr 2021 8:50:00 PDT"
content=
    |<p>all configuration formats suck; they're either too complicated, not human readable, not machine readable, not complicated enough, or a combination of all of those.</p>
    |<p>keep in mind i am just critizing these as use for configuration files, and they may excel in other things (data serialization and the like), while ckt may not.</p>
    |<p>here are all my (least) favourite offenders.</p>
    |
    |<h2>XML</h2>
    |<h3>e<b>X</b>tensible <b>M</b>arkup <b>L</b>anguage</h3>
    |<p>i don't think i need to go too much into XML. i don't like it, and i don't think anyone really does. it's not machine or human readable by really any sense of the word.</p>
    |<p>i don't think a lot of people really disagree with me here, and i'm not gonna preach to the choir; nobody (not many) people use XML for simple configuration files.</p>
    |
    |<h2>JSON</h2>
    |<h3><b>J</b>ava<b>S</b>cript <b>O</b>bject <b>N</b>otation</h3>
    |<p>congrats! we've taken a big huge massive fat step up from XML! here's what i really like about JSON.</p>
    |<p><b>1</b>. it's human readable enough with a little bit of noise</p>
    |<p><b>2</b>. it's extremely machine readable!</p><br />
    |
    |<p>though of course, i have a few problems with it:</p>
    |<p><b>1</b>. it's not human typeable enough; that is, all the { " , }s get in the way when you're just trying to just write a damn config file. this isn't a problem for all things, but for little configuration files it can get in the way.</p>
    |<p><b>2</b>. nooo trailing commas! this is a small point but relates back to #1.</p>
    |<p><b>3</b>. though the opposite of what ive typed just a second ago, it is not extremely human readable!</p>
    |<p><b>4</b>. too many data types in its specification; while this might be the opposite of what you've heard / experienced with json, i am just talking about simple config formats here! id like to leave the data types up to the user rather than up to the specification. (in fact, many of these formats have the same issue, though i guess this is a highly opinionated one.)</p>
    |<p><b>5</b>. no comments!</p>
    |<p>here's a quick example in JSON that ill copy in other formats to show you how they look;</p>
    |<pre>
        |<code class="language-json">
            |{
            |   "firstName": "John",
            |   "lastName": "Smith",
            |   "isAlive": true,
            |   "age": 27,
            |   "phoneNumbers": [
            |       {
            |           "type": "home",
            |           "number": "212 555-1234"
            |       },
            |       {
            |           "type": "office",
            |           "number": "646 555-4567"
            |       }
            |   ]
            |}
        |</code>
    |</pre>
    |<p>so, what? should i make a superset of JSON? a JSON with the problems fixed?</p>
    |<p>no! i shouldn't do that. that's 1. too boring, 2. a bit pointless, 3. <a href="https://github.com/bevry/cson">has</a> <a href="https://github.com/lifthrasiir/cson">been</a> <a href="https://json5.org/">tried</a> <a href="https://rome.tools/#rome-json">too</a> <a href="https://github.com/ekon-org/ekon">many</a> <a href="https://github.com/lifthrasiir/cson">times</a><a href="https://yaml.org/">.</a>
    |
    |<h2>YAML</h2>
    |<h3><b>Y</b>aml <b>A</b>in't <b>M</b>arkup <b>L</b>anguage</h3>
    |<p>YAML is a strict superset of JSON that is a tad bit more readable. here's what i like about it:</p>
    |<p><b>1</b>. it is a tad bit more readable than JSON is, with much less noise</p>
    |<p><b>2</b>. it is much more human writable than JSON, making it much better for configuration!</p>
    |<p><b>3</b>. commmennntss :)</p><br />
    |
    |<p>here is what i really don't like about it:</p>
    |<p><b>1</b>. it is super complicated! (seriously. <a href="https://yaml.org/spec/1.2/spec.html">the spec</a> is fucking massive; i can't imagine trying to write a completely spec-compliant YAML parser.</p>
    |<p><b>2</b>. seriously the spec is too large!</p>
    |<p>while the JSON example works in YAML, ill put a more yaml-like example here for visuals</p>
    |<pre>
        |<code class="language-yaml">
            |firstName: John
            |lastName: Smith
            |isAlive: true
            |age: 27
            |
            |# john's phone numbers
            |phoneNumbers:
            |   - type: home
            |     number: "212 555-1234"
            |   - type: office
            |     number: "646 555-4567"
        |</code>
    |</pre>
    |<p>this is super readable and the syntax is almost intuitive! though i am not completely satisfied</p>
    |
    |<h2>TOML</h2>
    |<h3><b>T</b>om's <b>O</b>bvious, <b>M</b>inimal <b>L</b>anguage</h3>
    |<p>TOML isn't a superset of JSON! cool! and it's 'obvious' and 'minimal', so i should be happy with it! here is what i like about it:</p>
    |<p><b>1</b>. though minor, key = value is more obvious to me than key: value (or parent: child)</p>
    |<p><b>2</b>. it is designed to map unambiguously to a hash table!</p>
    |<p><b>3</b>. it has a single, formal specification, while ini has many differing competing variants (this isn't completely a good thing)</p>
    |<p><b>4</b>. it is easy enough to implement</p><br />
    |
    |<p>here's what i don't like about it:</p>
    |<p><b>1</b>. toml is <a href="https://toml.io/en/v1.0.0#keys">not</a> <a href="https://toml.io/en/v1.0.0#string">completely</a> <a href="https://toml.io/en/v1.0.0#array-of-tables">obvious</a>, indicating 'obvious' is merely part of a <a href="https://www.boringcactus.com/2021/03/21/coins.html">naming template</a> rather than an actual descriptor.</p>
    |<p><b>2</b>. the spec decides data types (as in JSON, YAML, but not INI) rather than the user/implementation</p>
    |<p><b>3</b>. less typeable than YAML; it is a bit more noisy</p>
    |<p>and of course, the example in TOML</p>
    |
    |<pre>
        |<code class="language-toml">
            |first_name="John"
            |last_name="Smith"
            |is_alive="true"
            |age=27
            |
            |# john's phone numbers
            |[[phone_numbers]]
            |type="home"
            |number="212 555-1234"
            |
            |[[phone_numbers]]
            |type="office"
            |number="646 555-4567"
        |</code>
    |</pre>
    |<p>it is really unobvious how to do array of tables like this, a not immediately clear from the syntax either.</p>
    |
    |<h2>ZZZ</h2>
    |<h3>boring human readable data format for <b>Z</b>ig</h3>
    |<p>zzz syntax describes a tree of strings. it has very little syntactic noise and is really easy to implement!</p>
    |<p>here is what i really really really really like about zzz</p>
    |<p><b>1</b>. it is super duper simple and lightweight - you can read its (sparse) spec in about 2-3 minutes</p>
    |<p><b>2</b>. the spec itself doesn't define any data-types, only a parent:child relationship</p>
    |<p><b>3</b>. super duper readable and typeable</p>
    |<p><b>4</b>. reference implementation is in zig!! (yay zig!)</p><br />
    |
    |<p>in fact, i really like zzz! its implementation is really great, and it's super nice and simple.</p>
    |<p>here is what i don't like about it:</p>
    |<p><b>1</b>. it doesn't always unambiguously map into a hash table. consider the following:</p>
    |<pre>
        |<code class="language-yaml">
            |popup:
            |  menuitem:
            |    : value: New
            |      onclick: CreateNewDoc()
            |    : value: Open
            |      onclick: OpenDoc()
            |    : value: Close
            |      onclick: CloseDoc()
        |</code>
    |</pre>
    |<p>how would i go about putting this into a hash map?</p>
    |<p>specifically "menuitem"; it is just a bunch of k-v pairs with empty keys. hash tables can't have repeating keys, so i would have to see if the key was empty or something and use that to make a list. this is not unambiguous and lead me to a little bit of headache while trying to use it.</p>
    |
    |<h2>RECAP / TL;DR</h2>
    |<p><b>1</b>. i hate <a href="https://www.w3.org/XML/">XML</a>.</p>
    |<p><b>2</b>. i hate using <a href="https://www.json.org/">JSON</a> for config.</p>
    |<p><b>3</b>. i hate implementing <a href="https://yaml.org/">YAML</a>.</p>
    |<p><b>4</b>. i hate the lies and unobviousness of <a href="https://toml.io">TOML</a>.</p>
    |<p><b>5</b>. i really like <a href="https://github.com/gruebite/zzz">ZZZ</a>, but i just want to parse some god damn thing into a hash table.</p>
    |
    |<h2>CKT</h2>
    |<h3><b>C</b>ric<b>K</b>et's <b>T</b>able notation</h3>
    |<p>here's some things i thought about and tried to perfect while ckt:</p>
    |<p><b>1</b>. supreme typeability (e.g. using [] rather than {} for tables means less shift holding)</p>
    |<p><b>2</b>. a sort-of specific spec? one that's specific enough for ckt files not to differ in syntax, but not specific enough to make it extremely complicated to implement properly</p>
    |<p><b>3</b>. supreme readability! config files are for humans to write, after all</p>
    |<p><b>4</b>. obviousness - a super short read of the spec or just reading a ckt file and you should know all about how to write a ckt file</p><br />
    |
    |<p>and here are some things i did not try to make ckt for:</p>
    |<p><b>1</b>. complex data types (if you want/need to use complex datatypes, i do not think ckt is the way to go)
    |<p><b>2</b>. speed - while i'm sure one could create a blazing fast static implementation or something, i didn't really have it in mind when designing the spec or writing my implementation</p>
    |<p><b>3</b>. other people - you might absolutely despise this format. that's okay. i made this format really only for myself; others are free to use, implement, fork, etc and that's great, but i had really only thought about myself while writing it. i only got opinion from <a href="https://github.com/luawtf">one other person</a>.
    |<h3>shut up and show me!</h3>
    |<p>ok! here's that repeated example as a ckt file</p>
    |<pre>
        |<code class="language-toml">
            |first_name=John
            |last_name=Smith
            |is_alive=true
            |age=27
            |
            |# john's phone numbers
            |phone_numbers = [
            |    [
            |        type=home
            |        number=212 555-1234
            |    ]
            |    [
            |        type=office
            |        number=646 555-4567
            |    ]
            |]
        |</code>
    |</pre>
    |<p>here is a little description of ckt:</p>
    |<pre>
        |<code class="language-toml">
            |# ckt files describe tables
            |# tables inside this top-level one are
            |# surrounded with square braces []
            |
            |# initializations are separated by
            |# newlines, commas, or semicolons
            |
            |# key value pairs are
            |# 'record style initializations'
            |
            |# keys are strings
            |# values are strings or tables
            |record style = woah isnt it cool ?
            |init table = [ key = value ]
            |
            |# surrounding whitespace is trimmed
            |# the below is equivelant to the above
            |"record style" = "woah isnt it cool ?"
            |
            |# duplicate keys are overwritten
            |x = 13
            |x = 161
            |# (x = 161)
            |
            |# bare values are
            |# "list style initializations"
            |value1, value2
            |table = [ list, style, initialization ]
            |
            |# the keys of list style initializations
            |# should be the previous list-style key+1,
            |# counting up in decimal
            |equivelant table = [
            |    0 = list,
            |    1 = style,
            |    2 = initialization
            |]
            |
            |# you can mix and match
            |polyline = [
            |    color= blue; thickness = 2
            |    [ x = 0;   y = 0 ]
            |    [ x = -10; y = 0 ]
            |    [ x = -10; y = 1 ]
            |    [ x = 0;   y = 1 ]
            |]
            |
            |# also, multiline strings
            |hehehe =
            |    |look at this COOL
            |    |MULTILINE
            |    |STRING
        |</code>
    |</pre>
    |<p>you can read the "complete" specification <a href="https://git.sr.ht/~cricket/ckt">here</a>.</p>
    |<p>if you want more examples, <a href="https://git.sr.ht/~cricket/jazz">this blog</a> uses ckt for its posts.</p>
    |<p>if you want to use it right away, i have a <a href="https://git.sr.ht/~cricket/zckt">small implementation</a> written in zig! (though ckt is designed to be as easy to implement as possible)</p>
    |<p><i>(do note that no actual hate is directed at any of the formats hated on above.)</i></p>