hclang 0.20.2 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/esm/cli/hc.js +6 -6
- package/esm/lib/bundle/hc-bundle.js +35 -0
- package/esm/lib/bundle/hc-sources.js +3878 -0
- package/esm/lib/execute/hc-eval.js +4 -3
- package/esm/lib/execute/resource-import.js +90 -5
- package/esm/lib/execute/syntax.js +1 -1
- package/esm/lib/frames/frame-blob.js +2 -2
- package/esm/lib/frames/frame-count.js +67 -0
- package/esm/lib/frames/frame-decimal.js +2 -2
- package/esm/lib/frames/frame-int.js +25 -34
- package/esm/lib/frames/frame-number.js +2 -2
- package/esm/lib/frames/frame-numeric.js +30 -13
- package/esm/lib/frames/frame-rational.js +3 -2
- package/esm/lib/frames/frame-resource.js +3 -3
- package/esm/lib/frames.js +2 -1
- package/esm/lib/version.js +1 -1
- package/package.json +1 -1
- package/esm/lib/modules/standard-modules.js +0 -36
- package/esm/lib/modules/standard-sources.js +0 -366
|
@@ -0,0 +1,3878 @@
|
|
|
1
|
+
// Generated by scripts/embed-hc.ts from hc/*.hc. Do not edit.
|
|
2
|
+
// Regenerate with `deno task bundle:embed`.
|
|
3
|
+
/**
|
|
4
|
+
* The source of every bundled `hc/*.hc`, by canonical key, each joined from
|
|
5
|
+
* its lines.
|
|
6
|
+
*/
|
|
7
|
+
export const HC_SOURCES = new Map([
|
|
8
|
+
[
|
|
9
|
+
"hc/BitScheme.hc",
|
|
10
|
+
[
|
|
11
|
+
"#!/usr/bin/env hc #",
|
|
12
|
+
"```",
|
|
13
|
+
"= BitScheme Tutorial/Specification",
|
|
14
|
+
"Draft 0.2, 2019-09-07",
|
|
15
|
+
"",
|
|
16
|
+
"Declaratively parse, manipulate and generate binary data",
|
|
17
|
+
"",
|
|
18
|
+
'BitScheme is a lightweight data format for describing arbitrary sequences of binary data ("bitstreams", like those used for programming FPGAs).footnote:[https://en.wikipedia.org/wiki/Field-programmable_gate_array[Field-Programmable Gate Array]] It also doubles as a scripting language for manipulating those bitstreams -- what is sometimes called a DREADFUL.footnote:[Declaratively Rendered Executable Abstract Data Format Un-Language]',
|
|
19
|
+
"",
|
|
20
|
+
'BitScheme files use "hc" (as in https://github.com/TheSwanFactory/hclang[Homoiconic C]) as the file extension, and must contain that string in an opening "!#" shebang.footnote:[https://en.wikipedia.org/wiki/Shebang_(Unix)[shebang], aka hashbang]',
|
|
21
|
+
"```",
|
|
22
|
+
"#!/use/bin/env hc",
|
|
23
|
+
"```",
|
|
24
|
+
"",
|
|
25
|
+
"While you can write parsers in other languages to read the BitScheme format, BitScheme files can also be executed directly from the command line to parse or generate bitstreams. BitScheme can also be run as a REPL.footnote:[https://en.wikipedia.org/wiki/Read–eval–print_loop[Read–Eval–Print Loop]]. The REPL uses ``; `` as the input prompt and ``# `` for the output (plus ``# # `` for multi-line prompts), which is also the format we will use for code examples in this document.",
|
|
26
|
+
"",
|
|
27
|
+
"== Syntax",
|
|
28
|
+
"",
|
|
29
|
+
"BitScheme syntax is mostly just Identifiers and Grouping.",
|
|
30
|
+
"",
|
|
31
|
+
"=== Identifiers",
|
|
32
|
+
"==== Literals",
|
|
33
|
+
"",
|
|
34
|
+
"The simplest Identifiers are Literals, e.g.:",
|
|
35
|
+
"```",
|
|
36
|
+
"; 12345 # Decimal",
|
|
37
|
+
"# 12345",
|
|
38
|
+
"; 0b101 # Binary",
|
|
39
|
+
"# 0b101",
|
|
40
|
+
"; 0xdeadbeef # Hexadecimal",
|
|
41
|
+
"# 0xdeadbeef",
|
|
42
|
+
"```",
|
|
43
|
+
"===== String (quoted, utf-8)",
|
|
44
|
+
"```",
|
|
45
|
+
"; `Hello`",
|
|
46
|
+
"# `Hello`",
|
|
47
|
+
";",
|
|
48
|
+
"```",
|
|
49
|
+
"===== ByteString",
|
|
50
|
+
"```",
|
|
51
|
+
"; \\5\\Hello",
|
|
52
|
+
"# \\5\\Hello",
|
|
53
|
+
"```",
|
|
54
|
+
"Byte-string lengths can also resolve an already evaluated integer symbol:",
|
|
55
|
+
"```",
|
|
56
|
+
"; .v 4;",
|
|
57
|
+
"; .h 2;",
|
|
58
|
+
"; .size (v * h);",
|
|
59
|
+
"; \\size\\01234567",
|
|
60
|
+
"# \\8\\01234567",
|
|
61
|
+
"```",
|
|
62
|
+
'You can also use triple-backquotes for docstrings in https://asciidoctor.org[asciidoc] format. If you pass a ".adoc" file to bitscheme, it will prepend the backquotes, execute the code blocks, and warn if the evaluated input does not match the expected output.',
|
|
63
|
+
"",
|
|
64
|
+
'Comment strings (using "#") are also considered a type of Literal:',
|
|
65
|
+
"```",
|
|
66
|
+
"; 1234 # trailing comment",
|
|
67
|
+
"# 1234",
|
|
68
|
+
"; # inline comment before # 4321",
|
|
69
|
+
"# 4321",
|
|
70
|
+
"```",
|
|
71
|
+
"",
|
|
72
|
+
"==== Expressions",
|
|
73
|
+
"",
|
|
74
|
+
"Identifiers can be combined into Expressions. The default behavior is concatenation:",
|
|
75
|
+
"```",
|
|
76
|
+
"; 0b1101 0b0110",
|
|
77
|
+
"# 0b11010110",
|
|
78
|
+
"; `Hello` ` World`",
|
|
79
|
+
"# “Hello World”",
|
|
80
|
+
"```",
|
|
81
|
+
"==== Symbols",
|
|
82
|
+
"",
|
|
83
|
+
"BitScheme also supports Symbolic Identifiers, which use prefix sigils for different usages:",
|
|
84
|
+
"===== .Name (setter)",
|
|
85
|
+
"```",
|
|
86
|
+
"; .the_answer 42;",
|
|
87
|
+
"```",
|
|
88
|
+
"===== Value (getter)",
|
|
89
|
+
"```",
|
|
90
|
+
"; the_answer",
|
|
91
|
+
"# 42",
|
|
92
|
+
"```",
|
|
93
|
+
"===== $Error",
|
|
94
|
+
"```",
|
|
95
|
+
"; ther_answer",
|
|
96
|
+
"# $!.name-missing...",
|
|
97
|
+
"```",
|
|
98
|
+
"===== Alias",
|
|
99
|
+
"```",
|
|
100
|
+
"; @the_answer 7;",
|
|
101
|
+
"; the_answer",
|
|
102
|
+
"# 7",
|
|
103
|
+
"```",
|
|
104
|
+
'Symbols with only non-alphanumeric characters (e.g., "+") are called Operators rather than Identifiers. There are four universal binary Operators in the standard library, which can be used with any Value:',
|
|
105
|
+
"",
|
|
106
|
+
'- "?" if-then',
|
|
107
|
+
'- ":" if-else',
|
|
108
|
+
'- "|" map',
|
|
109
|
+
'- "&" reduce',
|
|
110
|
+
"",
|
|
111
|
+
"The *|* and *&* operators operate over enumerable elements. Use *&&* to map over properties.",
|
|
112
|
+
"",
|
|
113
|
+
"See *Operator Syntax* below for more details.",
|
|
114
|
+
"",
|
|
115
|
+
"=== Grouping",
|
|
116
|
+
"==== Terminals",
|
|
117
|
+
"",
|
|
118
|
+
"Elements are separated using Terminals:",
|
|
119
|
+
"===== newline",
|
|
120
|
+
"```",
|
|
121
|
+
"; `Terminal Expression`",
|
|
122
|
+
"# `Terminal Expression`",
|
|
123
|
+
"```",
|
|
124
|
+
"===== comma",
|
|
125
|
+
"```",
|
|
126
|
+
"; `Expression1`,`Expression2`",
|
|
127
|
+
"# (`Expression1`, `Expression2`)",
|
|
128
|
+
"```",
|
|
129
|
+
"===== semicolon",
|
|
130
|
+
"```",
|
|
131
|
+
"; `Statement`;",
|
|
132
|
+
"```",
|
|
133
|
+
"",
|
|
134
|
+
"==== Delimiters",
|
|
135
|
+
"Elements are aggregated using pairs of Delimiters:",
|
|
136
|
+
"===== [] Boxed",
|
|
137
|
+
"```",
|
|
138
|
+
"; [1, 2, 3]",
|
|
139
|
+
"# [1, 2, 3]",
|
|
140
|
+
"```",
|
|
141
|
+
"===== () Unboxed",
|
|
142
|
+
"```",
|
|
143
|
+
"; (0b1 0b0)",
|
|
144
|
+
"# 0b10",
|
|
145
|
+
"```",
|
|
146
|
+
"===== <> Schema (i.e. type; see below)",
|
|
147
|
+
"```",
|
|
148
|
+
"; .Bit <0b0, 0b1>;",
|
|
149
|
+
"```",
|
|
150
|
+
"===== {} Deferred",
|
|
151
|
+
"```",
|
|
152
|
+
"; .AppendZero {_ 0b0};",
|
|
153
|
+
"; AppendZero",
|
|
154
|
+
"# { _ 0b0 }",
|
|
155
|
+
"; AppendZero 0b1",
|
|
156
|
+
"# 0b10",
|
|
157
|
+
"```",
|
|
158
|
+
"==== Properties",
|
|
159
|
+
"",
|
|
160
|
+
"Names can be used as properties to extract values from Groupings:",
|
|
161
|
+
"```",
|
|
162
|
+
"; .grp [.a 1; .b 2;];",
|
|
163
|
+
"; grp.a",
|
|
164
|
+
"# 1",
|
|
165
|
+
"```",
|
|
166
|
+
"",
|
|
167
|
+
"==== Operator Syntax",
|
|
168
|
+
"",
|
|
169
|
+
"Operators are actually just non-alphanumeric properties.",
|
|
170
|
+
"===== _nil_, the empty expression",
|
|
171
|
+
"```",
|
|
172
|
+
"; .false ();",
|
|
173
|
+
"```",
|
|
174
|
+
"===== _all_, the inclusive schema",
|
|
175
|
+
"```",
|
|
176
|
+
"; .true <>;",
|
|
177
|
+
"```",
|
|
178
|
+
"===== Conditional",
|
|
179
|
+
"```",
|
|
180
|
+
"; true ? {`Yes`}",
|
|
181
|
+
"# `Yes`",
|
|
182
|
+
"; () : {`No`}",
|
|
183
|
+
"# `No`",
|
|
184
|
+
"```",
|
|
185
|
+
"===== Map",
|
|
186
|
+
"```",
|
|
187
|
+
"; [0b101, 0b010] & AppendZero",
|
|
188
|
+
"# [0b1010, 0b0100]",
|
|
189
|
+
"```",
|
|
190
|
+
"===== Reduce",
|
|
191
|
+
"",
|
|
192
|
+
"Concatenation is what a blob does when applied, so reducing blobs joins them.",
|
|
193
|
+
"There is no empty-bit spelling to start from, so the head is the receiver and the",
|
|
194
|
+
"tail is the stream; a zero-width accumulator is `#375`.",
|
|
195
|
+
"```",
|
|
196
|
+
"; [0b0100] | 0b1010",
|
|
197
|
+
"# 0b10100100",
|
|
198
|
+
"```",
|
|
199
|
+
"",
|
|
200
|
+
"== Implementation Status",
|
|
201
|
+
"",
|
|
202
|
+
"This specification distinguishes four statuses:",
|
|
203
|
+
"",
|
|
204
|
+
"* *implemented* examples are executable assertions and must pass;",
|
|
205
|
+
"* *stale* syntax is shown only when explaining its current replacement;",
|
|
206
|
+
"* *aspirational* examples are executable assertions marked `$!.unimplemented`;",
|
|
207
|
+
"* *environment-dependent* operations, such as writing generated data files, remain non-executable documentation.",
|
|
208
|
+
"",
|
|
209
|
+
"The schema and capture gaps are tracked by https://github.com/TheSwanFactory/hclang/issues/310[#310]. The framebuffer example is tracked by https://github.com/TheSwanFactory/hclang/issues/311[#311], and the RISC-V example by https://github.com/TheSwanFactory/hclang/issues/312[#312].",
|
|
210
|
+
"",
|
|
211
|
+
"== Schemas",
|
|
212
|
+
"",
|
|
213
|
+
"Schemas can be thought of as a cross between type signatures and regular expressions. Each element of a schema is called a _capture_. Numeric enumeration constraints and the minimal deterministic retrieval and deconstruction forms are implemented. General alternatives, constructors, and deferred capture lengths remain aspirational.",
|
|
214
|
+
"",
|
|
215
|
+
"=== Numeric Constraints (implemented)",
|
|
216
|
+
"",
|
|
217
|
+
"The current declaration syntax binds a schema and an initial value in one expression:",
|
|
218
|
+
"```",
|
|
219
|
+
"; .enum123 <1,2,3> 2",
|
|
220
|
+
"# .enum123 2",
|
|
221
|
+
"; enum123",
|
|
222
|
+
"# 2",
|
|
223
|
+
"; @enum123 4",
|
|
224
|
+
"# $!.type-error .enum123 <1, 2, 3> 4",
|
|
225
|
+
"```",
|
|
226
|
+
"",
|
|
227
|
+
"=== Schema Retrieval and Captures (implemented, #310)",
|
|
228
|
+
"",
|
|
229
|
+
"The `<>` property retrieves the schema attached to the binding:",
|
|
230
|
+
"```",
|
|
231
|
+
"; enum123.<>",
|
|
232
|
+
"# <1, 2, 3>",
|
|
233
|
+
"```",
|
|
234
|
+
"",
|
|
235
|
+
"Fixed-width captures require an exact-width blob. A remainder capture consumes the complete blob:",
|
|
236
|
+
"```",
|
|
237
|
+
"; <8@Bit> 0xff",
|
|
238
|
+
"# 0xff",
|
|
239
|
+
"; <[@Bit]> 0b101",
|
|
240
|
+
"# 0b101",
|
|
241
|
+
"```",
|
|
242
|
+
"",
|
|
243
|
+
"=== Minimal Deconstructors (implemented, #310)",
|
|
244
|
+
"",
|
|
245
|
+
"Property selectors extract direct properties in schema order. A schema-only statement defines a callable deterministic bit splitter:",
|
|
246
|
+
"```",
|
|
247
|
+
"; <.x, .z> [.x 1; .y 2; .z 3;]",
|
|
248
|
+
"# [1, 3]",
|
|
249
|
+
"; .BitSplitter3 <[.head <3@Bit>; .tail <[@Bit]>;]>;",
|
|
250
|
+
"; BitSplitter3 0b10101100",
|
|
251
|
+
"# [.head 0b101; .tail 0b01100;]",
|
|
252
|
+
"```",
|
|
253
|
+
"",
|
|
254
|
+
"The declarations below remain non-executable because user-defined capture units and aliases are deferred:",
|
|
255
|
+
"",
|
|
256
|
+
"[source,hc]",
|
|
257
|
+
"----",
|
|
258
|
+
".Bit <0b0, 0b1>;",
|
|
259
|
+
".BitStream <[@Bit]>;",
|
|
260
|
+
".Byte <8@Bit>;",
|
|
261
|
+
"----",
|
|
262
|
+
"",
|
|
263
|
+
"=== Constructors and Deferred Captures (aspirational, #310)",
|
|
264
|
+
"",
|
|
265
|
+
"Constructors are intended to reverse schema flow by mapping capture keys into a value. The old dotted iterator spellings are stale; current HC uses `|` for map and `&` for reduce.",
|
|
266
|
+
"```",
|
|
267
|
+
"; BS3_sequence",
|
|
268
|
+
"# $!.unimplemented [0b000, 0b111]",
|
|
269
|
+
"; BS3_sequence & {. _}",
|
|
270
|
+
"# $!.unimplemented 0b000111",
|
|
271
|
+
"```",
|
|
272
|
+
"",
|
|
273
|
+
"The intended constructor remains non-executable until schema deconstruction exists:",
|
|
274
|
+
"",
|
|
275
|
+
"[source,hc]",
|
|
276
|
+
"----",
|
|
277
|
+
".BS3_sequence (BitSplitter3 | [.head 0b000; .tail 0b111;]);",
|
|
278
|
+
"----",
|
|
279
|
+
"",
|
|
280
|
+
"Deferred captures are intended to reuse the result of an earlier capture:",
|
|
281
|
+
"```",
|
|
282
|
+
"; NetString 0x548656c6c6f666666666",
|
|
283
|
+
"# $!.unimplemented [.n 0x5; .string 0x48656c6c6f;]",
|
|
284
|
+
"```",
|
|
285
|
+
"",
|
|
286
|
+
"[source,hc]",
|
|
287
|
+
"----",
|
|
288
|
+
".NetString <[.n <4@Bit>; .string {<n@Byte>};]>;",
|
|
289
|
+
"----",
|
|
290
|
+
"",
|
|
291
|
+
"== Example A: Symbolicated Frame Buffer (aspirational, #311)",
|
|
292
|
+
"",
|
|
293
|
+
"This design parses named and unnamed captures, reuses variables across scopes, and symbolicates output. Its declarations are non-executable because they depend on #310 and the parser-specific work in #311:",
|
|
294
|
+
"",
|
|
295
|
+
"[source,hc]",
|
|
296
|
+
"----",
|
|
297
|
+
".fb-start 0xf4m3b0ff3c;",
|
|
298
|
+
".op {.x 0xa; .y 0xb; .data 0xc;};",
|
|
299
|
+
".width <2@Byte>;",
|
|
300
|
+
".height <2@Byte>;",
|
|
301
|
+
".parse-x <op.x; @width>;",
|
|
302
|
+
".parse-y <op.y; @height>;",
|
|
303
|
+
".pixel <2@Byte>;",
|
|
304
|
+
".parse-data <op.data; .fb-data <width height pixel>>;",
|
|
305
|
+
".command <parse-x, parse-y, parse-data>;",
|
|
306
|
+
".fb-parse <fb-start, [command]>;",
|
|
307
|
+
".sizes {.mvga-x 0x0004; .mvga-y 0x0002;};",
|
|
308
|
+
".mvga-data [0x0000 0x0001 0x0010 0x0100 0xffff 0xfff0 0xff00 0xf000];",
|
|
309
|
+
".fb-bits (fb-start op.x mvga-x op.y mvga-y op.data mvga-data);",
|
|
310
|
+
".sym-x <parse-x |> sizes>;",
|
|
311
|
+
".sym-y <parse-y |> sizes>;",
|
|
312
|
+
".sym-commands <sym-x, sym-y, parse-data>;",
|
|
313
|
+
".fb-sym <fb-start |> @fb-start, [sym-commands]>;",
|
|
314
|
+
"----",
|
|
315
|
+
"",
|
|
316
|
+
"The parsing and symbolic-output targets remain authoritative aspirational assertions:",
|
|
317
|
+
"```",
|
|
318
|
+
"; fb-parse fb-bits",
|
|
319
|
+
"# $!.unimplemented [0xf4m3b0ff3c, @width 0x0004, @height 0x0002, .fb-data 0x0000000100100100fffffff0ff00f000]",
|
|
320
|
+
"; fb-sym fb-bits",
|
|
321
|
+
"# $!.unimplemented [{fb-start}, {@width mvga-x}, {@height mvga-y}, .fb-data 0x0000000100100100fffffff0ff00f000]",
|
|
322
|
+
"```",
|
|
323
|
+
"",
|
|
324
|
+
"== Example B: RISC-V (aspirational, #312)",
|
|
325
|
+
"",
|
|
326
|
+
"The following RV32I schema remains non-executable documentation because fixed-length captures and schema constructors are not implemented:",
|
|
327
|
+
"",
|
|
328
|
+
"[source,hc]",
|
|
329
|
+
"----",
|
|
330
|
+
".OP <7@Bit> (.Register <0b0110011>; .Load 0b0000011; .Math 0b0010011; .Immediate <Load, Math>; .Upper <0b0110111, 0b0010111>; .Store <0b0100011>; .Branch <0b1100011>; .Jump <0b1101111>;);",
|
|
331
|
+
".FUNCT3 (.funct3 <3@Bit>;);",
|
|
332
|
+
".FUNCT7 (.funct7 <7@Bit>;);",
|
|
333
|
+
".RD (.rd <5@Bit>);",
|
|
334
|
+
".RS1 (.rs1 <5@Bit>);",
|
|
335
|
+
".RS2 (.rs2 <5@Bit>);",
|
|
336
|
+
".SOURCE (RS2, RS1, FUNCT3);",
|
|
337
|
+
".Register <[FUNCT7, SOURCE, RD, OP.Register]>;",
|
|
338
|
+
".Immediate <[.imm11-0 <12@Bit>, RS1, FUNCT3, RD, .opcode OP.Immediate]>;",
|
|
339
|
+
".UpperImmediate <[.imm31-12 <20@Bit>, RD, .opcode OP.Upper]>;",
|
|
340
|
+
".Store <[.imm11-5 <7@Bit>, SOURCE, .imm4-0 <5@Bit>, .opcode OP.Store]>;",
|
|
341
|
+
".Branch <[.b12 <Bit>, .imm10-5 <6@Bit>, SOURCE, .imm4-1 <4@Bit>, .b11 <Bit>, .opcode OP.Branch]>;",
|
|
342
|
+
".Jump <[.b20 <Bit>, .imm10-1 <10@Bit>, .b11 <Bit>, .imm19-12 <8@Bit>, RD, .opcode OP.Jump]>;",
|
|
343
|
+
".RISC-V <Register, Immediate, UpperImmediate, Store, Branch, Jump>;",
|
|
344
|
+
".func (.add 0b000; .slt 0b010; .xor 0b100; .or 0b110; .and 0b111;);",
|
|
345
|
+
".addi <[.value, .source, .dest]> ^ {value source func.add dest OP.Math};",
|
|
346
|
+
"----",
|
|
347
|
+
"",
|
|
348
|
+
"Construction, parsing, and generation are tracked independently so each future result can remove one marker:",
|
|
349
|
+
"```",
|
|
350
|
+
"; addi[0b000000001011, 0b01010, 0b00111]",
|
|
351
|
+
"# $!.unimplemented 0b00000000101101010000001110010011",
|
|
352
|
+
"; RISC-V 0b00000000101101010000001110010011",
|
|
353
|
+
"# $!.unimplemented [.imm11-0 0b000000001011; .rs1 0b01010; .funct3 0b000; .rd 0b00111; .opcode 0b0010011;]",
|
|
354
|
+
"; RISC-V | [.imm11-0 0b000000001011; .rs1 0b01010; .funct3 0b000; .rd 0b00111; .opcode 0b0010011;]",
|
|
355
|
+
"# $!.unimplemented [0b000000001011, 0b01010, 0b000, 0b00111, 0b0010011]",
|
|
356
|
+
"```",
|
|
357
|
+
"",
|
|
358
|
+
"Writing the generated bytes to a data file is environment-dependent and intentionally remains non-executable documentation. The executable specification ends here.",
|
|
359
|
+
"```",
|
|
360
|
+
"",
|
|
361
|
+
].join("\n"),
|
|
362
|
+
],
|
|
363
|
+
[
|
|
364
|
+
"hc/apply.hc",
|
|
365
|
+
[
|
|
366
|
+
"#!/usr/bin/env hc",
|
|
367
|
+
"```",
|
|
368
|
+
"Apply and iterate: the decisions, and the corpus that holds them (#368)",
|
|
369
|
+
"",
|
|
370
|
+
"`apply-tutorial.md` states the model. This file states the decisions behind it",
|
|
371
|
+
"and pins each one to an expectation, so a claim cannot quietly rot into prose.",
|
|
372
|
+
"The tutorial explains behavior and carries no argument; the argument lives here.",
|
|
373
|
+
"",
|
|
374
|
+
"The model is implemented, so almost every expectation below is now an executable",
|
|
375
|
+
"assertion rather than a promise. The file that recorded v0.14.0's reversed",
|
|
376
|
+
"operator roles example by example was this one, and it has been replaced rather",
|
|
377
|
+
"than kept beside its own correction; git history holds it.",
|
|
378
|
+
"",
|
|
379
|
+
"How to read. An expectation prefixed with `$!.unimplemented` is a promise:",
|
|
380
|
+
"HCTest reports it without failing the suite, and fails deliberately if the",
|
|
381
|
+
"behavior arrives while the marker remains. An expectation without that prefix is",
|
|
382
|
+
"an invariant these decisions must not break. This file runs in",
|
|
383
|
+
"`deno task test:doc`.",
|
|
384
|
+
"",
|
|
385
|
+
"This file owns apply and iteration only. The wider property model — visibility,",
|
|
386
|
+
"schemas, handles, equality planes, and what a declaration does beyond writing a",
|
|
387
|
+
"property — was worked out in the a11.1 to a11.4 notes, which have been removed",
|
|
388
|
+
"now that their conclusions live here and in `spec/a11`. Those parts of the model",
|
|
389
|
+
"that iteration does not touch are therefore unspecified rather than settled, and",
|
|
390
|
+
"the notes are in git history.",
|
|
391
|
+
"",
|
|
392
|
+
"Five decisions below were taken after those notes and reverse them. They are",
|
|
393
|
+
"collected at the end under what diverges, so a reader who remembers the earlier",
|
|
394
|
+
"design is corrected rather than left to notice.",
|
|
395
|
+
"",
|
|
396
|
+
"## Application is the one verb",
|
|
397
|
+
"",
|
|
398
|
+
"What a family answers when applied is the whole of its behavior. Every decision",
|
|
399
|
+
"below rests on these",
|
|
400
|
+
"```",
|
|
401
|
+
"; “a” “b”",
|
|
402
|
+
"# “ab”",
|
|
403
|
+
"; “” “h”",
|
|
404
|
+
"# “h”",
|
|
405
|
+
"; 2 3",
|
|
406
|
+
"# 6",
|
|
407
|
+
"; 2 “a”",
|
|
408
|
+
"# “aa”",
|
|
409
|
+
"; [] 1",
|
|
410
|
+
"# [1]",
|
|
411
|
+
"; [1] 2",
|
|
412
|
+
"# [1, 2]",
|
|
413
|
+
"; [] ()",
|
|
414
|
+
"# []",
|
|
415
|
+
"; {_ + 1} 2",
|
|
416
|
+
"# 3",
|
|
417
|
+
"; './out.txt' “hello”",
|
|
418
|
+
"# 5",
|
|
419
|
+
"```",
|
|
420
|
+
"Two of those answers decide the shape of iteration. An array answers itself, so",
|
|
421
|
+
"applying to one accumulates in place. Text answers a new value, so applying to",
|
|
422
|
+
"it produces something to carry forward.",
|
|
423
|
+
"",
|
|
424
|
+
"## Iteration is application, twice",
|
|
425
|
+
"",
|
|
426
|
+
"A map applies each element to the value on its right and collects the answers. A",
|
|
427
|
+
"reduce applies each element and keeps the answer as the receiver for the next",
|
|
428
|
+
"one. That is the only difference, and neither adds a verb.",
|
|
429
|
+
"",
|
|
430
|
+
"The direction never varies: the right operand is the receiver and the element is",
|
|
431
|
+
"the argument. A map with a text receiver is therefore as ordinary as a map with",
|
|
432
|
+
"a closure, which is worth pinning — a closure-only map would make the operator a",
|
|
433
|
+
"special form rather than an application",
|
|
434
|
+
"```",
|
|
435
|
+
"; [1, 2, 3] & {_ * 2}",
|
|
436
|
+
"# [2, 4, 6]",
|
|
437
|
+
"; [1, 2, 3] & “n=”",
|
|
438
|
+
"# [“n=1”, “n=2”, “n=3”]",
|
|
439
|
+
"```",
|
|
440
|
+
"A reduce threads instead of collecting, so the family it starts from supplies",
|
|
441
|
+
"the combining rule and no rule has to be specified",
|
|
442
|
+
"```",
|
|
443
|
+
"; [1, 2, 3] | []",
|
|
444
|
+
"# [1, 2, 3]",
|
|
445
|
+
"; [1, 2, 3] | “”",
|
|
446
|
+
"# “123”",
|
|
447
|
+
"; [1, 2, 4] | 1",
|
|
448
|
+
"# 8",
|
|
449
|
+
"```",
|
|
450
|
+
"## A name applies like the value it names",
|
|
451
|
+
"",
|
|
452
|
+
"**Decision.** Naming a receiver does not change what applying it answers, so a",
|
|
453
|
+
"named seed starts a reduce exactly as its literal does (#386).",
|
|
454
|
+
"",
|
|
455
|
+
"A name bound to an aggregate reads it through a handle, and before v0.17.1 the",
|
|
456
|
+
"handle answered the argument instead of collecting it: `xs 3` was `3`, and a",
|
|
457
|
+
"named array seed was skipped, so `[2, 3] | e` multiplied. A collect through a",
|
|
458
|
+
"name lands on a fresh aggregate holding the same elements, so the name is never",
|
|
459
|
+
"written, mutable or not, and every element keeps its identity",
|
|
460
|
+
"```",
|
|
461
|
+
"; .xs [1, 2];",
|
|
462
|
+
"; xs 3",
|
|
463
|
+
"# [1, 2, 3]",
|
|
464
|
+
"; xs",
|
|
465
|
+
"# [1, 2]",
|
|
466
|
+
"; .e [];",
|
|
467
|
+
"; [[2, 3] | e, [2, 3] | []]",
|
|
468
|
+
"# [[2, 3], [2, 3]]",
|
|
469
|
+
"; e",
|
|
470
|
+
"# []",
|
|
471
|
+
"; .ys_ [1];",
|
|
472
|
+
"; [ys_ 2, ys_]",
|
|
473
|
+
"# [[1, 2], [1]]",
|
|
474
|
+
"; .row [xs, xs];",
|
|
475
|
+
"; [((row xs) .2) === xs, (row xs) === row]",
|
|
476
|
+
"# [<>, ()]",
|
|
477
|
+
"```",
|
|
478
|
+
"Concatenation therefore needs no operator of its own: reduce one aggregate into",
|
|
479
|
+
"another, named or computed",
|
|
480
|
+
"```",
|
|
481
|
+
"; .cat {(_ .1) | (_ .0)};",
|
|
482
|
+
"; cat [xs, [3, 4]]",
|
|
483
|
+
"# [1, 2, 3, 4]",
|
|
484
|
+
"```",
|
|
485
|
+
"## There is no closure form of reduce",
|
|
486
|
+
"",
|
|
487
|
+
"**Decision.** `|` threads, always. It does not inspect what it was handed, and",
|
|
488
|
+
"there is no second calling convention in which a closure holds position while",
|
|
489
|
+
"the running value travels in the dot parameter.",
|
|
490
|
+
"",
|
|
491
|
+
"An earlier draft had that convention, and it was a special form wearing an",
|
|
492
|
+
"operator's clothes. Threading means the answer of one step is the receiver of",
|
|
493
|
+
"the next, so a receiver only carries a rule across elements if it answers",
|
|
494
|
+
"something that still holds the rule. An array answers itself. Text answers new",
|
|
495
|
+
"text. A closure answers whatever its body answers, so it is spent after one",
|
|
496
|
+
"element and the rest of the source applies to that answer. Both outcomes are",
|
|
497
|
+
"ordinary application: either the answer accumulates, or the receiver has to",
|
|
498
|
+
"answer itself.",
|
|
499
|
+
"",
|
|
500
|
+
"So the reduce rules are exactly the ones the families already provide — collect,",
|
|
501
|
+
"join, multiply — and a custom rule needs a receiver that answers itself while",
|
|
502
|
+
"carrying state in its own properties. The next section settles what such a",
|
|
503
|
+
"receiver declares.",
|
|
504
|
+
"",
|
|
505
|
+
"Nothing has to refuse a closure in the operator slot. It threads like any other",
|
|
506
|
+
"receiver and is merely useless, which is why no `$!.needs-a-value` refusal",
|
|
507
|
+
"appears anywhere in this design.",
|
|
508
|
+
"",
|
|
509
|
+
"## An aggregate may declare its own application",
|
|
510
|
+
"",
|
|
511
|
+
"**Decision.** Applying an aggregate collects unless it declares a method named",
|
|
512
|
+
"`apply`, or `apply_` when the rule writes the receiver. Then applying the",
|
|
513
|
+
"aggregate calls that method with the argument, and the answer is the next",
|
|
514
|
+
"receiver (#375).",
|
|
515
|
+
"",
|
|
516
|
+
"This is a rule about application, not about `|`, so a reduce needs no special",
|
|
517
|
+
"case: it applies each element, and the receiver says what applying means. The",
|
|
518
|
+
"method is found on the aggregate and its declared parents, the chain a class's",
|
|
519
|
+
"methods come from, and never in the scope around it, so a plain array collects",
|
|
520
|
+
"wherever it is written. A summing accumulator is an ordinary class",
|
|
521
|
+
"```",
|
|
522
|
+
"; .Summer {[.total _; .apply_ {@total (total + _);}]};",
|
|
523
|
+
"; ([1, 2, 4] | (Summer 0)) .total",
|
|
524
|
+
"# 7",
|
|
525
|
+
"```",
|
|
526
|
+
"The accumulated result is the receiver itself, and its state is read by name.",
|
|
527
|
+
"Writes follow the effect axis exactly as a method call does, because a declared",
|
|
528
|
+
"application is a method call. `apply_` reached through an immutable name updates",
|
|
529
|
+
"a copy, so the name keeps its value. Reached through a mutable name, it fills",
|
|
530
|
+
"the receiver in place. Without the declaration, application writes neither",
|
|
531
|
+
"```",
|
|
532
|
+
"; .summer (Summer 0);",
|
|
533
|
+
"; [([1, 2, 4] | summer) .total, summer.total]",
|
|
534
|
+
"# [7, 0]",
|
|
535
|
+
"; .running_ (Summer 0);",
|
|
536
|
+
"; [1, 2, 4] | running_;",
|
|
537
|
+
"; running_.total",
|
|
538
|
+
"# 7",
|
|
539
|
+
"```",
|
|
540
|
+
"A non-mutating `apply` answers whatever its body answers, usually a new",
|
|
541
|
+
"instance. A step that answers nil leaves the receiver as it was, the same way an",
|
|
542
|
+
"aggregate ignores a nil argument, so a step can decline an element",
|
|
543
|
+
"```",
|
|
544
|
+
"; .Max {[.best _; .apply {(_ .> best) ? {Max __}}]};",
|
|
545
|
+
"; ([3, 9, 4] | (Max 0)) .best",
|
|
546
|
+
"# 9",
|
|
547
|
+
"; .Count {[.n _; .apply {Count (n + 1)}]};",
|
|
548
|
+
"; ([“a”, “b”, “c”] | (Count 0)) .n",
|
|
549
|
+
"# 3",
|
|
550
|
+
"```",
|
|
551
|
+
"The declaration is inherited like any method, and an `apply` in the surrounding",
|
|
552
|
+
"scope is not a declaration",
|
|
553
|
+
"```",
|
|
554
|
+
"; .Tick [.apply_ {@n (n + 1);}];",
|
|
555
|
+
"; .Ticks {[.^ Tick; .n 0]};",
|
|
556
|
+
"; ([7, 7, 7] | (Ticks())) .n",
|
|
557
|
+
"# 3",
|
|
558
|
+
"; .apply {_};",
|
|
559
|
+
"; [1] 2",
|
|
560
|
+
"# [1, 2]",
|
|
561
|
+
"```",
|
|
562
|
+
"",
|
|
563
|
+
"## An empty reduce answers its receiver; an empty map is empty",
|
|
564
|
+
"",
|
|
565
|
+
"**Decision.** An empty source reduces to the receiver it started from, and maps",
|
|
566
|
+
"to an empty array (v0.19.0).",
|
|
567
|
+
"",
|
|
568
|
+
"The receiver is the accumulator before any element arrives, so a fold over",
|
|
569
|
+
"nothing is that accumulator. Every built-in seed is its rule's identity, so the",
|
|
570
|
+
"empty answers are the familiar ones: an empty collect is `[]`, an empty join is",
|
|
571
|
+
"`“”`, and an empty product is `1`. A map answers a collection of answers, and no",
|
|
572
|
+
"answers is an empty collection",
|
|
573
|
+
"```",
|
|
574
|
+
"; [] | “seed”",
|
|
575
|
+
"# “seed”",
|
|
576
|
+
"; [] | []",
|
|
577
|
+
"# []",
|
|
578
|
+
"; [] | 1",
|
|
579
|
+
"# 1",
|
|
580
|
+
"; [] & {_}",
|
|
581
|
+
"# []",
|
|
582
|
+
"; [] && {_}",
|
|
583
|
+
"# []",
|
|
584
|
+
"```",
|
|
585
|
+
"This is the answer every seeded fold gives, from Haskell's `foldl` and Lisp's",
|
|
586
|
+
"`reduce :initial-value` to Python, JavaScript, and Smalltalk, and the reason is",
|
|
587
|
+
"one law. Folding a whole stream must equal folding its first part and then",
|
|
588
|
+
"continuing from that answer, so `(xs ++ ys) | s` is `ys | (xs | s)`. When `xs`",
|
|
589
|
+
"is empty, that requires `[] | s` to be `s`",
|
|
590
|
+
"```",
|
|
591
|
+
"; .xs [1, 2];",
|
|
592
|
+
"; [[1, 2, 3] | [], [3] | (xs | []), [3] | ([] | [])]",
|
|
593
|
+
"# [[1, 2, 3], [1, 2, 3], [3]]",
|
|
594
|
+
"```",
|
|
595
|
+
"Before v0.19.0 an empty reduce answered nil, on the ground that a seed which met",
|
|
596
|
+
"no element never took part. That broke the law, so code that collected and then",
|
|
597
|
+
"compared had to guard the empty case, the way SQL code wraps an empty `SUM` in",
|
|
598
|
+
"`COALESCE`. The cost of the change is that nil no longer reports an empty source:",
|
|
599
|
+
"compare the answer with the seed instead. An empty resource read is still",
|
|
600
|
+
"distinct from an absent one, which answers a refusal.",
|
|
601
|
+
"",
|
|
602
|
+
"## Properties are not elements",
|
|
603
|
+
"",
|
|
604
|
+
"The dominant HC object is a list with configuration in its property plane. The",
|
|
605
|
+
"single operators walk the elements only, so a property never reaches a receiver",
|
|
606
|
+
"and a value whose contents are all properties has nothing to iterate.",
|
|
607
|
+
"",
|
|
608
|
+
"Reading a property or an index is application, and is spelled as application",
|
|
609
|
+
"```",
|
|
610
|
+
"; [.meta 1; 2, 3] .meta",
|
|
611
|
+
"# 1",
|
|
612
|
+
"; [.meta 1; 2, 3] .0",
|
|
613
|
+
"# 2",
|
|
614
|
+
"; [.meta 1; 2, 3] & {_}",
|
|
615
|
+
"# [2, 3]",
|
|
616
|
+
"; [.a 1] & {_}",
|
|
617
|
+
"# []",
|
|
618
|
+
"```",
|
|
619
|
+
"**Decision.** Canonical rendering puts the properties first, then the elements.",
|
|
620
|
+
"This reverses the spelling this file carried before. It makes print order agree",
|
|
621
|
+
"with the order the doubled operators iterate, and it leaves canonical output",
|
|
622
|
+
"re-readable as input, which elements-first rendering did not.",
|
|
623
|
+
"",
|
|
624
|
+
"A declaration prints once, from the property plane it wrote, rather than also as",
|
|
625
|
+
"the data-plane echo an evaluated aggregate retains. Printing both put one value in",
|
|
626
|
+
"two places, and re-reading it declared the same name twice. The echo does print",
|
|
627
|
+
"when this value does not hold the property, because a declaration into an",
|
|
628
|
+
"enclosing scope leaves its echo here and its property there",
|
|
629
|
+
"```",
|
|
630
|
+
"; [.a 1; a, 2]",
|
|
631
|
+
"# [.a 1; 1, 2]",
|
|
632
|
+
"```",
|
|
633
|
+
"Whether a property written twice keeps the last write is a separate subject, and",
|
|
634
|
+
"is parked rather than answered here.",
|
|
635
|
+
"",
|
|
636
|
+
"## Tuples restore the index a map withholds",
|
|
637
|
+
"",
|
|
638
|
+
"`&` exposes only the element, so there is no address in the parameter slot. The",
|
|
639
|
+
"doubled operators widen the stream to the properties a caller can see, in",
|
|
640
|
+
"declaration order, then the elements by index, each synthesized as a",
|
|
641
|
+
"`[key, value]` tuple. The tuple is what `&&` forces, since a map hands its",
|
|
642
|
+
"receiver one argument, and it is an iteration argument only: no pair is stored",
|
|
643
|
+
"",
|
|
644
|
+
"**Decision.** The key half of a tuple is the symbol that addresses the member,",
|
|
645
|
+
"not a spelling of it: `.meta` and `.0`, never `“meta”` and `0`",
|
|
646
|
+
"```",
|
|
647
|
+
"; [10, 20] && {_}",
|
|
648
|
+
"# [[.0, 10], [.1, 20]]",
|
|
649
|
+
"; [.meta 9; 10, 20] && {_}",
|
|
650
|
+
"# [[.meta, 9], [.0, 10], [.1, 20]]",
|
|
651
|
+
"; [10, 20, 30] && {_ .0}",
|
|
652
|
+
"# [.0, .1, .2]",
|
|
653
|
+
"```",
|
|
654
|
+
"A symbol is an address a caller can use, and the evaluator already resolves one",
|
|
655
|
+
"against both planes. Given `.pair [.meta, 9];` then `[.meta 1; 2, 3] (pair .0)`",
|
|
656
|
+
"answers `1`, and given `.ipair [.1, 20];` then `[10, 20] (ipair .0)` answers",
|
|
657
|
+
"`20`. Text is only a description of an address, and no legitimate operation turns",
|
|
658
|
+
"it back into one.",
|
|
659
|
+
"",
|
|
660
|
+
"The cost is named rather than denied. A symbol argument addresses rather than",
|
|
661
|
+
"contributing its spelling, so `“n=” (pair .0)` answers `$!.name-missing` today,",
|
|
662
|
+
"and the position arrives as `.0` rather than `0`. Neither the spelling nor the",
|
|
663
|
+
"number is reachable from a tuple key. Both are additive later, and",
|
|
664
|
+
"recoverability runs only this way: an accessor can expose what a symbol spells,",
|
|
665
|
+
"while nothing short of evaluation promotes text to an address.",
|
|
666
|
+
"",
|
|
667
|
+
"Canonical rendering therefore has to print the dot. `[meta, 9]` re-read is a",
|
|
668
|
+
"name lookup rather than a symbol, so dropping it costs the re-readability that",
|
|
669
|
+
"properties-first rendering was chosen for. v0.14.0 printed every symbol without",
|
|
670
|
+
"its dot, and the fix is narrower than reversing that: a symbol *in value",
|
|
671
|
+
"position* prints the dot, while one still awaiting lookup prints as written,",
|
|
672
|
+
"because `a` is exactly how a lookup is spelled",
|
|
673
|
+
"```",
|
|
674
|
+
"; .meta",
|
|
675
|
+
"# .meta",
|
|
676
|
+
"; {a + b}",
|
|
677
|
+
"# { a + b }",
|
|
678
|
+
"```",
|
|
679
|
+
"",
|
|
680
|
+
"`||` reduces that same stream, threading the answer exactly as `|` does, so it",
|
|
681
|
+
"needs no calling convention of its own",
|
|
682
|
+
"```",
|
|
683
|
+
"; [.meta 9; 10, 20] || []",
|
|
684
|
+
"# [[.meta, 9], [.0, 10], [.1, 20]]",
|
|
685
|
+
"```",
|
|
686
|
+
"**Decision.** The vocabulary of this design is map and reduce, values and",
|
|
687
|
+
"tuples, properties and elements; `fold` and `entry` are retired, including",
|
|
688
|
+
"inside refusal names.",
|
|
689
|
+
"",
|
|
690
|
+
"The complete view has no inverse. Folding tuples back does not rebuild the",
|
|
691
|
+
"value, because applying a pair to a frame does not merge it. Reconstruction is a",
|
|
692
|
+
"job for parsed syntax, not for iteration.",
|
|
693
|
+
"",
|
|
694
|
+
"## The one refusal the surface depends on",
|
|
695
|
+
"",
|
|
696
|
+
"`.0` already addresses the first element, so a `.0` property would be a second",
|
|
697
|
+
"meaning for an address that is taken, and would put two members under one key in",
|
|
698
|
+
"a doubled stream. Refusing it is what makes one key slot well-formed, whether or",
|
|
699
|
+
"not the index exists yet",
|
|
700
|
+
"```",
|
|
701
|
+
"; .0 9",
|
|
702
|
+
"# $!.numeric-key .0",
|
|
703
|
+
"```",
|
|
704
|
+
"A literal is answered by that refusal rather than holding it as a failed",
|
|
705
|
+
"statement, because the key collides with the addresses the aggregate itself",
|
|
706
|
+
"assigns: the value cannot be well-formed at all, so there is nothing to hand back.",
|
|
707
|
+
"",
|
|
708
|
+
"That is narrow on purpose. A refused *write* — a schema mismatch, a constant, a",
|
|
709
|
+
"visibility grade — leaves a well-formed value with one write undone, and a caller",
|
|
710
|
+
"can still inspect it. Only an ill-formed key is promoted",
|
|
711
|
+
"```",
|
|
712
|
+
"; [.0 9; 1, 2]",
|
|
713
|
+
"# $!.numeric-key .0",
|
|
714
|
+
"; [.A 1; .A 2; 3]",
|
|
715
|
+
"# [.A 1; ($error{$is-constant .A}); 3]",
|
|
716
|
+
"```",
|
|
717
|
+
"## Resources are character reduces",
|
|
718
|
+
"",
|
|
719
|
+
"Writing is application and answers the characters written. Reading supplies",
|
|
720
|
+
"characters, so what the read starts from is what shapes them",
|
|
721
|
+
"```",
|
|
722
|
+
"; './out.txt' | “”",
|
|
723
|
+
"# “hello”",
|
|
724
|
+
"; './out.txt' | []",
|
|
725
|
+
"# [“h”, “e”, “l”, “l”, “o”]",
|
|
726
|
+
"; './out.txt' & {_}",
|
|
727
|
+
"# [“h”, “e”, “l”, “l”, “o”]",
|
|
728
|
+
"```",
|
|
729
|
+
"A resource publishes its RFC 3986 components as readable properties, but they",
|
|
730
|
+
"describe the reference the value is rather than contents it holds, so they are",
|
|
731
|
+
"not part of the stream. A doubled read is indexed characters, and identity",
|
|
732
|
+
"metadata never leaks into content",
|
|
733
|
+
"```",
|
|
734
|
+
"; './out.txt' .path",
|
|
735
|
+
"# “./out.txt”",
|
|
736
|
+
"; './out.txt' && {_}",
|
|
737
|
+
"# [[.0, “h”], [.1, “e”], [.2, “l”], [.3, “l”], [.4, “o”]]",
|
|
738
|
+
"```",
|
|
739
|
+
"**Decision.** A refusal reaching a receiver mid-stream is collected by an",
|
|
740
|
+
"aggregate and consumed by nothing else. An operation on an error is an error, so",
|
|
741
|
+
"a refusal poisons a join or a multiply and answers itself; collecting is not such",
|
|
742
|
+
"an operation, and an aggregate that dropped the refusal would answer as though",
|
|
743
|
+
"the read had succeeded. This is what a10 relies on, and it is the same thing an",
|
|
744
|
+
"aggregate already did with a missing-name note",
|
|
745
|
+
"```",
|
|
746
|
+
"; './missing.txt' | []",
|
|
747
|
+
"# [$!.resource-absent './missing.txt']",
|
|
748
|
+
"; './missing.txt' | “”",
|
|
749
|
+
"# $!.resource-absent './missing.txt'",
|
|
750
|
+
"```",
|
|
751
|
+
"Only a resource read is a character source. A string is one element and does not",
|
|
752
|
+
"enumerate its characters, and neither does anything else that is not an",
|
|
753
|
+
"aggregate",
|
|
754
|
+
"```",
|
|
755
|
+
"; “abc” & {_}",
|
|
756
|
+
"# [“abc”]",
|
|
757
|
+
"; 1 & {_}",
|
|
758
|
+
"# [1]",
|
|
759
|
+
"```",
|
|
760
|
+
"## Where this reverses the earlier design",
|
|
761
|
+
"",
|
|
762
|
+
"The removed notes specified each of these the other way. Listed so that a reader",
|
|
763
|
+
"who learned the earlier design gets corrected, and so a later reconciliation has",
|
|
764
|
+
"a list rather than a diff:",
|
|
765
|
+
"",
|
|
766
|
+
"- **There is no closure form of reduce.** The notes gave a single fold",
|
|
767
|
+
" first-element seeding with the accumulator in the parameter slot, and refused",
|
|
768
|
+
" a block form of the doubled fold. Both rules go: `|` and `||` thread, and",
|
|
769
|
+
" nothing refuses.",
|
|
770
|
+
"- **Canonical rendering puts properties first.** Both the notes' spellings and",
|
|
771
|
+
" this file's earlier ones rendered elements first.",
|
|
772
|
+
"- **A tuple key is a symbol**, not a spelling. The notes paired a value with a",
|
|
773
|
+
" key or an index, which put `“meta”` and `0` in that slot.",
|
|
774
|
+
"- **`&` carries no address.** The notes left this open. Position is reachable",
|
|
775
|
+
" only as `.0` by tuple projection under `&&`.",
|
|
776
|
+
"",
|
|
777
|
+
"## What this file does not decide",
|
|
778
|
+
"",
|
|
779
|
+
"- whether an aggregate in a map refuses. The notes refused it, on the ground",
|
|
780
|
+
" that one accumulator cannot serve one answer per input. But `[1, 2, 3] & []`",
|
|
781
|
+
" is ordinary application — each element collects into the array, which answers",
|
|
782
|
+
" itself, so the map answers three references to one array. That is useless",
|
|
783
|
+
" rather than incoherent, and refusing it is the same paternalism the closure",
|
|
784
|
+
' form was retired for. It needs an argument beyond "you probably meant `|`";',
|
|
785
|
+
"- whether a string should enumerate characters, closing a11's asymmetry;",
|
|
786
|
+
"- what a receiver answering nil mid-reduce does when it declares no",
|
|
787
|
+
" application. A declared application keeps its receiver on nil, but a closure",
|
|
788
|
+
" that answers nil still hands the next element the role of receiver;",
|
|
789
|
+
"- whether a stream's receiver contributes named entries;",
|
|
790
|
+
"- whether `()` becomes an ordered set, which is #374;",
|
|
791
|
+
"- what a property written twice does, which is parked above.",
|
|
792
|
+
"```",
|
|
793
|
+
"",
|
|
794
|
+
].join("\n"),
|
|
795
|
+
],
|
|
796
|
+
[
|
|
797
|
+
"hc/class-support.hc",
|
|
798
|
+
[
|
|
799
|
+
"#!/usr/bin/env hc",
|
|
800
|
+
"`Class support is an interpretation of ordinary frames, closures, visibility,",
|
|
801
|
+
"effects, and parent lookup. These examples intentionally use no class-specific",
|
|
802
|
+
"runtime primitive.`",
|
|
803
|
+
"",
|
|
804
|
+
"`A mutable singleton shares identity through its trailing-underscore handle.",
|
|
805
|
+
"The same trailing underscore declares the method allowed to write it, so one",
|
|
806
|
+
"marker spells the whole effect axis: an underscore touches identity.`",
|
|
807
|
+
"; .counter_ [._value 1; .get {value}; .set_ {@value _;}];",
|
|
808
|
+
"; counter_.get()",
|
|
809
|
+
"# 1",
|
|
810
|
+
"; counter_.set_ 2;",
|
|
811
|
+
"; counter_.get()",
|
|
812
|
+
"# 2",
|
|
813
|
+
"",
|
|
814
|
+
"`Both halves of that axis coexist on one aggregate without interference: here a",
|
|
815
|
+
"trailing underscore names a mutable field, declares the method that replaces it,",
|
|
816
|
+
"and marks the receiver each is reached through.`",
|
|
817
|
+
"; .box_ [.slot_ [.n 1]; .fill_ {@slot_ _;}; .read {slot_.n}];",
|
|
818
|
+
"; box_.read()",
|
|
819
|
+
"# 1",
|
|
820
|
+
"; box_.fill_ [.n 7];",
|
|
821
|
+
"; box_.read()",
|
|
822
|
+
"# 7",
|
|
823
|
+
"",
|
|
824
|
+
"`A class is a reusable closure that returns a fresh aggregate. Uppercase fields",
|
|
825
|
+
"prove that constructor state does not leak between repeated instances.`",
|
|
826
|
+
"; .Point {[.X _; .getX {X}]};",
|
|
827
|
+
"; .first (Point 3);",
|
|
828
|
+
"; .second (Point 5);",
|
|
829
|
+
"; first.getX()",
|
|
830
|
+
"# 3",
|
|
831
|
+
"; second.getX()",
|
|
832
|
+
"# 5",
|
|
833
|
+
"",
|
|
834
|
+
"`Mutating methods return their receiver, but assignment failures remain errors.`",
|
|
835
|
+
"; .constant_ [.Value 1; .change_ {@Value _;}];",
|
|
836
|
+
"; [constant_.change_ 2]",
|
|
837
|
+
"# [($error{$is-constant .Value});]",
|
|
838
|
+
"; constant_.Value",
|
|
839
|
+
"# 1",
|
|
840
|
+
"",
|
|
841
|
+
"`A mutating method reached through an immutable handle is a functional update:",
|
|
842
|
+
"the call evaluates to the new value, and the original is untouched at any depth.`",
|
|
843
|
+
"; .pair [.inner_ [.n 1; .set-n_ {@n _;}]; .bump_ {inner_.set-n_ _}];",
|
|
844
|
+
"; (pair.bump_ 5).inner_.n",
|
|
845
|
+
"# 5",
|
|
846
|
+
"; pair.inner_.n",
|
|
847
|
+
"# 1",
|
|
848
|
+
"",
|
|
849
|
+
"`The functional copy holds its own declarations, so it prints, iterates, and",
|
|
850
|
+
"compares exactly as the same value written out would.`",
|
|
851
|
+
"; .point [.v 1; .set_ {@v _;}];",
|
|
852
|
+
"; point.set_ 2",
|
|
853
|
+
"# [.v 2; .set_ { @v _ };]",
|
|
854
|
+
"; [(point.set_ 2) & {_}, (point.set_ 2) = [.v 2; .set_ {@v _;}]]",
|
|
855
|
+
"# [[], <>]",
|
|
856
|
+
"",
|
|
857
|
+
"`A bare sibling mutator remains functional inside a non-mutating method.`",
|
|
858
|
+
"; .sibling-owner [.value 1; .write_ {@value _;}; .sneak {write_ _}];",
|
|
859
|
+
"; .sibling-copy (sibling-owner.sneak(9));",
|
|
860
|
+
"; sibling-owner.value",
|
|
861
|
+
"# 1",
|
|
862
|
+
"; sibling-copy.value",
|
|
863
|
+
"# 9",
|
|
864
|
+
"",
|
|
865
|
+
"`Built-in control-flow blocks retain the active receiver capability.`",
|
|
866
|
+
"; .callback-owner_ [.value 1; .write_ {1 ? {@value 9}}];",
|
|
867
|
+
"; callback-owner_.write_ 9;",
|
|
868
|
+
"; callback-owner_.value",
|
|
869
|
+
"# 9",
|
|
870
|
+
"",
|
|
871
|
+
"`A mutable receiver takes no copy, so the nested identity it declares is shared.`",
|
|
872
|
+
"; .live_ [.inner_ [.n 1; .set-n_ {@n _;}]; .bump_ {inner_.set-n_ _}];",
|
|
873
|
+
"; live_.bump_ 9;",
|
|
874
|
+
"; live_.inner_.n",
|
|
875
|
+
"# 9",
|
|
876
|
+
"",
|
|
877
|
+
"`A parent declaration uses the existing up relationship. Descendants inherit",
|
|
878
|
+
"public and protected values, while private values remain inaccessible.`",
|
|
879
|
+
"; .base [.public 42; ._protected 21; .__private 7];",
|
|
880
|
+
"; .Derived {[.^ base; .values {[public, protected, private]}]};",
|
|
881
|
+
"; .derived (Derived());",
|
|
882
|
+
"; derived.values()",
|
|
883
|
+
"# [42, 21, $!.is-private .private]",
|
|
884
|
+
"; derived.public",
|
|
885
|
+
"# 42",
|
|
886
|
+
"; derived.protected",
|
|
887
|
+
"# $!.is-protected .protected",
|
|
888
|
+
"",
|
|
889
|
+
"`Visibility grades the declared parent chain, not lexical nesting. A method",
|
|
890
|
+
"reaches every property of its own receiver, including private ones.`",
|
|
891
|
+
"; .owner [.open 42; ._shared 21; .__secret 7; .own-method {[open, shared, secret]}];",
|
|
892
|
+
"; owner.own-method()",
|
|
893
|
+
"# [42, 21, 7]",
|
|
894
|
+
"",
|
|
895
|
+
"`That access survives nesting: a scope inside a method body still runs against",
|
|
896
|
+
"the same receiver.`",
|
|
897
|
+
"; .nester [.__deep 3; .via-group {(deep)}; .via-block {[deep] & {_}}];",
|
|
898
|
+
"; nester.via-group()",
|
|
899
|
+
"# 3",
|
|
900
|
+
"; nester.via-block()",
|
|
901
|
+
"# [3]",
|
|
902
|
+
"",
|
|
903
|
+
"`An unrelated peer is refused, whether it asks directly or from inside its own",
|
|
904
|
+
"method, because it declares no parent.`",
|
|
905
|
+
"; .thief [.steal {owner.shared}];",
|
|
906
|
+
"; thief.steal()",
|
|
907
|
+
"# $!.is-protected .shared",
|
|
908
|
+
"; owner.shared",
|
|
909
|
+
"# $!.is-protected .shared",
|
|
910
|
+
"",
|
|
911
|
+
"`A merely nested aggregate is a peer, not a descendant: containment grants no",
|
|
912
|
+
"protected access.`",
|
|
913
|
+
"; .outer [._inner-secret 21; .nested [.read {inner-secret}]];",
|
|
914
|
+
"; outer.nested.read()",
|
|
915
|
+
"# $!.is-protected .inner-secret",
|
|
916
|
+
"",
|
|
917
|
+
"`A mutating method re-parents a mutable receiver in place.`",
|
|
918
|
+
"; .old-parent [.marker 1];",
|
|
919
|
+
"; .new-parent [.marker 2];",
|
|
920
|
+
"; .mutable-child_ [.^ old-parent; .reparent_ {.^ _;}];",
|
|
921
|
+
"; mutable-child_.reparent_ new-parent;",
|
|
922
|
+
"; mutable-child_.marker",
|
|
923
|
+
"# 2",
|
|
924
|
+
"",
|
|
925
|
+
"`The same mutating method reached through an immutable handle re-parents only",
|
|
926
|
+
"its functional copy; the original keeps its declared parent.`",
|
|
927
|
+
"; .immutable-child [.^ old-parent; .reparent_ {.^ _;}];",
|
|
928
|
+
"; .updated-child (immutable-child.reparent_ new-parent);",
|
|
929
|
+
"; immutable-child.marker",
|
|
930
|
+
"# 1",
|
|
931
|
+
"; updated-child.marker",
|
|
932
|
+
"# 2",
|
|
933
|
+
"",
|
|
934
|
+
"`A non-mutating method has no authority to re-parent even a mutable receiver.`",
|
|
935
|
+
"; .blocked-child_ [.^ old-parent; .reparent {.^ _;}];",
|
|
936
|
+
"; [blocked-child_.reparent(new-parent)]",
|
|
937
|
+
"# [($!.method-not-mutating .^);]",
|
|
938
|
+
"",
|
|
939
|
+
"`The language-level writer rejects direct and indirect cycles.`",
|
|
940
|
+
"; .self_ [.reparent_ {.^ _;}];",
|
|
941
|
+
"; [self_.reparent_ self_]",
|
|
942
|
+
"# [($!.cyclic-parent .^);]",
|
|
943
|
+
"; .left_ [.reparent_ {.^ _;}];",
|
|
944
|
+
"; .right_ [.^ left_];",
|
|
945
|
+
"; [left_.reparent_ right_]",
|
|
946
|
+
"# [($!.cyclic-parent .^);]",
|
|
947
|
+
"",
|
|
948
|
+
"`Multiple-base behavior is ordinary user-defined composition, not inheritance",
|
|
949
|
+
"syntax or a built-in policy.`",
|
|
950
|
+
"; .compose { [.left _.0.left; .right _.1.right] };",
|
|
951
|
+
"; .combined (compose [[.left 1], [.right 2]]);",
|
|
952
|
+
"; combined.left",
|
|
953
|
+
"# 1",
|
|
954
|
+
"; combined.right",
|
|
955
|
+
"# 2",
|
|
956
|
+
"",
|
|
957
|
+
"`A class declares how text spells its instances with a toText method. Text that",
|
|
958
|
+
"receives an instance contributes that method's answer; an aggregate without one",
|
|
959
|
+
"contributes its spelling, and the printer always shows the spelling.`",
|
|
960
|
+
"; .Pair {[.X (_ .0); .Y (_ .1); .toText {“(” X “, ” Y “)”}]};",
|
|
961
|
+
"; “at ” (Pair [3, 5])",
|
|
962
|
+
"# “at (3, 5)”",
|
|
963
|
+
"; “” [.x 1; 2]",
|
|
964
|
+
"# “[.x 1; 2]”",
|
|
965
|
+
"",
|
|
966
|
+
"`A functional update copies only what it writes. A member the call never writes",
|
|
967
|
+
"is shared with the original, so it keeps its identity.`",
|
|
968
|
+
"; .shelf [.item [.n 1]; .count 0; .tick_ {@count (count + 1);}];",
|
|
969
|
+
"; [(shelf.tick_ ()).count, shelf.count, (shelf.tick_ ()).item === shelf.item]",
|
|
970
|
+
"# [1, 0, <>]",
|
|
971
|
+
"",
|
|
972
|
+
].join("\n"),
|
|
973
|
+
],
|
|
974
|
+
[
|
|
975
|
+
"hc/cqml.hc",
|
|
976
|
+
[
|
|
977
|
+
".hc 0.6.0",
|
|
978
|
+
"",
|
|
979
|
+
"```Composable Query Meta-Language",
|
|
980
|
+
"",
|
|
981
|
+
"A simple, easily-parseable format for specifying and composing:",
|
|
982
|
+
"- queries",
|
|
983
|
+
"- configuration",
|
|
984
|
+
"- data",
|
|
985
|
+
"and abstractions thereof",
|
|
986
|
+
"",
|
|
987
|
+
"It has its own runtime and native integrations, but can also emit CSV, SQL, and YAML for use with legacy tools. Because it is a simple tree data structure, it can also be losslessly visualized and edited by graphical UIs.",
|
|
988
|
+
"",
|
|
989
|
+
'CQML builds on HCSV, a strict, strongly typed format for specifying comma-separated values. HCSV is itself a "congram" of Homoiconic C, a small but powerful language for expressing data manipulation.',
|
|
990
|
+
"",
|
|
991
|
+
"## Tablea",
|
|
992
|
+
"",
|
|
993
|
+
"Conceptually, we can think of tables as rows of property lists. Importantly, CQML only specifies the external semantics. The underlying runtime can use whatever storage representation, mechanisms and policy it wants (or has been configured to use).",
|
|
994
|
+
"",
|
|
995
|
+
"Everything in CQML is",
|
|
996
|
+
"just grouped expressions of values, names, and operators. Queries can operate directly on rows, or be mapped across tables.",
|
|
997
|
+
"",
|
|
998
|
+
"## Queries",
|
|
999
|
+
"```",
|
|
1000
|
+
"; user .name",
|
|
1001
|
+
"# “Jane”",
|
|
1002
|
+
"; user (.name, .role)",
|
|
1003
|
+
"# (.name “Jane”, .role “Boss”)",
|
|
1004
|
+
"",
|
|
1005
|
+
"; Users & .name",
|
|
1006
|
+
"# [ “Jane”, “Joe”]",
|
|
1007
|
+
"; Users & (.name, .role)",
|
|
1008
|
+
"[",
|
|
1009
|
+
"# (.name “Jane”, .role “Boss”)",
|
|
1010
|
+
"# (.name “Joe”, .role “Freelancer”)",
|
|
1011
|
+
"]",
|
|
1012
|
+
"```",
|
|
1013
|
+
"## Filters",
|
|
1014
|
+
"",
|
|
1015
|
+
"Filters are just lazy predicates:",
|
|
1016
|
+
"```",
|
|
1017
|
+
"; Users | {role = “Boss”}",
|
|
1018
|
+
"# (.name “Jane”, .role “Boss”)",
|
|
1019
|
+
"```",
|
|
1020
|
+
"Note that equal is an operator. Assignment is done directly by names, which can be evaluated anywhere in an expression.",
|
|
1021
|
+
"```",
|
|
1022
|
+
"; .is-boss {role = “Boss”};",
|
|
1023
|
+
"; Users | is-boss",
|
|
1024
|
+
"# (.name “Jane”, .role “Boss”)",
|
|
1025
|
+
"```",
|
|
1026
|
+
"## Joins",
|
|
1027
|
+
"```",
|
|
1028
|
+
"; .uc-name (.u,.c) ^ {u.name = c.name};",
|
|
1029
|
+
"; <Users,Contacts> | uc-name",
|
|
1030
|
+
"[",
|
|
1031
|
+
"# (.name “Jane”, .role “Boss”, .phone 555.1212)",
|
|
1032
|
+
"]",
|
|
1033
|
+
"```",
|
|
1034
|
+
'Where <> is the type operator, usually pronounced "all."',
|
|
1035
|
+
"```",
|
|
1036
|
+
"",
|
|
1037
|
+
].join("\n"),
|
|
1038
|
+
],
|
|
1039
|
+
[
|
|
1040
|
+
"hc/figures.hc",
|
|
1041
|
+
[
|
|
1042
|
+
"#!/usr/bin/env hc",
|
|
1043
|
+
"```",
|
|
1044
|
+
"Figures (#382, #395)",
|
|
1045
|
+
"",
|
|
1046
|
+
"Relational Construction Theory has one generative operation: construct a Figure",
|
|
1047
|
+
"out of zero or more already constructed Figures, its children. This module",
|
|
1048
|
+
'ports History 005.30c, "The Figure class as idiomatic HC", in',
|
|
1049
|
+
"`quilt+s3://protology#package=occurrence/history`.",
|
|
1050
|
+
"",
|
|
1051
|
+
"`Figure` is a constructor closure, and the object it returns is the class: each",
|
|
1052
|
+
"method below is documented by the paragraph above it. A paragraph ends in `;`,",
|
|
1053
|
+
"so it is a statement of the object rather than one of its elements, and it",
|
|
1054
|
+
"never affects `=`. Every observer answers a Figure, never a number or a",
|
|
1055
|
+
"Boolean: `A`, with no children, means no, and `B` means yes. So every answer can",
|
|
1056
|
+
"be a child, a receiver, or an argument, and the class is closed under its own",
|
|
1057
|
+
"methods. Only Form and Text leave the class, on purpose: they answer a plain",
|
|
1058
|
+
"bracket tree and its text, for reading a Figure rather than computing with it.",
|
|
1059
|
+
"",
|
|
1060
|
+
"A method names its own Figure `_^`, because a bare name is looked up on the",
|
|
1061
|
+
"argument first (spec 7), and the argument is usually another Figure. For the",
|
|
1062
|
+
"same reason, a block inside a method reads only names the method bound",
|
|
1063
|
+
"```",
|
|
1064
|
+
".Figure {[",
|
|
1065
|
+
"```",
|
|
1066
|
+
"**Children.** `Figure [c, …]` keeps exactly the Figures in the bracket, in",
|
|
1067
|
+
"order, each one itself rather than a copy, so `(x.children .0) === c`",
|
|
1068
|
+
"```;",
|
|
1069
|
+
" .children (_ | []);",
|
|
1070
|
+
"```",
|
|
1071
|
+
"**Application**, `x y` (#375): a new Figure with x's children followed by y.",
|
|
1072
|
+
"It leaves x unchanged and forgets nothing, so `ys | x` joins two Figures and",
|
|
1073
|
+
"`cs | (Figure [])` constructs one out of a stream",
|
|
1074
|
+
"```;",
|
|
1075
|
+
" .apply {Figure ((_^.children | []) _)};",
|
|
1076
|
+
"```",
|
|
1077
|
+
"**Manyness**, `x.many()`: a tally with one mark `B` per immediate child. It",
|
|
1078
|
+
"keeps how many children there are and forgets what they are, everything below",
|
|
1079
|
+
"them, their order and their identity",
|
|
1080
|
+
"```;",
|
|
1081
|
+
" .many {Figure (_^.children & {B})};",
|
|
1082
|
+
"```",
|
|
1083
|
+
"**Size**, `x.size()`: a tally with one unit cell `U` per cell. Any Figure shaped",
|
|
1084
|
+
"like `U` is a cell; every other Figure adds up the Sizes of its children by",
|
|
1085
|
+
"joining them into `Tally Z`. It keeps the cell count and forgets shape, nesting,",
|
|
1086
|
+
"order, reuse and identity. The unit case comes first, because a unit's only",
|
|
1087
|
+
"child is `Z`",
|
|
1088
|
+
"```;",
|
|
1089
|
+
" .size {.kids _^.children;",
|
|
1090
|
+
" (kids = U.children) ? {Figure [U]} : {((kids & {_.size()}) | (Tally Z)).row}};",
|
|
1091
|
+
"```",
|
|
1092
|
+
"**Multiplication**, `x.mul y`: y once for every cell of x, and `Z` when y is",
|
|
1093
|
+
"`Z`. It keeps y's identity in every position and forgets x's shape",
|
|
1094
|
+
"```;",
|
|
1095
|
+
" .mul {.y _; .cells ((_^.size()).children);",
|
|
1096
|
+
" (y = Z) ? {Z} : {Figure (cells & {y})}};",
|
|
1097
|
+
"```",
|
|
1098
|
+
"**Tally multiplication**, `x.size_mul y`: the Size of a Figure holding y once",
|
|
1099
|
+
"per child of x. It keeps the cell count and forgets both shapes",
|
|
1100
|
+
"```;",
|
|
1101
|
+
" .size_mul {.y _; (Figure (_^.children & {y})).size()};",
|
|
1102
|
+
"```",
|
|
1103
|
+
"**Size-equivalence**, `x.size_equivalent y`: `U` when the two Sizes agree and",
|
|
1104
|
+
"`Z` otherwise. It keeps only whether the cell counts agree",
|
|
1105
|
+
"```;",
|
|
1106
|
+
" .size_equivalent {((_^.size()) = (_.size())) ? {U} : {Z}};",
|
|
1107
|
+
"```",
|
|
1108
|
+
"**Sameness of form**, `x.sameform y`: `B` when `x = y`. It compares child by",
|
|
1109
|
+
"child and forgets identity and reuse",
|
|
1110
|
+
"```;",
|
|
1111
|
+
" .sameform {(_^ = _) ? {B} : {A}};",
|
|
1112
|
+
"```",
|
|
1113
|
+
"**Sameness**, `x.sameness y`: `B` when `x === y`, the same constructed Figure.",
|
|
1114
|
+
"It keeps identity only and forgets form",
|
|
1115
|
+
"```;",
|
|
1116
|
+
" .sameness {(_^ === _) ? {B} : {A}};",
|
|
1117
|
+
"```",
|
|
1118
|
+
"**Withness**, `x.withness [f, …]`: `B` when every f is an immediate child of x,",
|
|
1119
|
+
"the same Figure rather than an equal-looking one. It is relative to one parent,",
|
|
1120
|
+
"the receiver, and forgets the children's order, repeats, and everything below",
|
|
1121
|
+
"them. A requested Figure is absent when no child is identical to it",
|
|
1122
|
+
"```;",
|
|
1123
|
+
" .withness {.kids _^.children;",
|
|
1124
|
+
" .absent ((_ & {.f _;",
|
|
1125
|
+
" .found ((kids & {(_ === f) ? {f}}) | []);",
|
|
1126
|
+
" (found = []) ? {f}}) | []);",
|
|
1127
|
+
" (absent = []) ? {B} : {A}};",
|
|
1128
|
+
"```",
|
|
1129
|
+
"**Form**, `x.form()`: the plain bracket tree of x, one bracket per Figure, the",
|
|
1130
|
+
"way 005.30c wrote Figures before they were a class. It keeps shape and order,",
|
|
1131
|
+
"and forgets identity and the methods",
|
|
1132
|
+
"```;",
|
|
1133
|
+
" .form {_^.children & {_.form()}};",
|
|
1134
|
+
"```",
|
|
1135
|
+
"**Text**, `“” x`: the form spelled as text, so a Figure interpolates as",
|
|
1136
|
+
"`[[], [[]]]` rather than as every method it declares (#398). Printing x still",
|
|
1137
|
+
"shows its full spelling, which reads back",
|
|
1138
|
+
"```;",
|
|
1139
|
+
" .toText {“” (_^.form())}",
|
|
1140
|
+
"]};",
|
|
1141
|
+
"```",
|
|
1142
|
+
"**Tally** is a helper receiver, not a Figure. Its `row` starts at `Z`, and",
|
|
1143
|
+
"applying a tally to it appends that tally's units, one at a time, through",
|
|
1144
|
+
"`x y`, so a reduce into `Tally Z` adds counts",
|
|
1145
|
+
"```",
|
|
1146
|
+
".Tally {[.row _; .apply {Tally (_.children | _^.row)}]};",
|
|
1147
|
+
"```",
|
|
1148
|
+
"**The marks.** The observers answer `A`, the Figure with no children, for no",
|
|
1149
|
+
"and `B`, the Figure holding `A`, for yes. Size counts in the same two: `Z`",
|
|
1150
|
+
"reuses `A` as the additive zero and `U` reuses `B` as the unit cell. The class",
|
|
1151
|
+
"reads all four, so they are declared with it rather than in the examples below",
|
|
1152
|
+
"```",
|
|
1153
|
+
".A (Figure []); .B (Figure [A]); .Z A; .U B;",
|
|
1154
|
+
"```",
|
|
1155
|
+
"## Construction",
|
|
1156
|
+
"",
|
|
1157
|
+
"The example family reuses one `A` under both `B` and `E`. Indexing reaches a",
|
|
1158
|
+
"child itself, not a copy",
|
|
1159
|
+
"```",
|
|
1160
|
+
"; .C (Figure [B]); .D (Figure [C]);",
|
|
1161
|
+
"; .E (Figure [A, B]); .F (Figure [B, C]); .G (Figure [E, F]);",
|
|
1162
|
+
"; [(G.children .0) === E, (E.children .1) === B, (F.children .0) === B, (E.children .0) === (B.children .0)]",
|
|
1163
|
+
"# [<>, <>, <>, <>]",
|
|
1164
|
+
"```",
|
|
1165
|
+
"Form is the bracket tree a Figure is built as, and text spells it",
|
|
1166
|
+
"```",
|
|
1167
|
+
"; [(E.form()) = [[], [[]]], (E.form()) = [A.form(), B.form()], ((Figure []).form()) = []]",
|
|
1168
|
+
"# [<>, <>, <>]",
|
|
1169
|
+
"; [(“” E) = “[[], [[]]]”, (“G is ” G) = “G is [[[], [[]]], [[[]], [[[]]]]]”]",
|
|
1170
|
+
"# [<>, <>]",
|
|
1171
|
+
"```",
|
|
1172
|
+
"Equal children make equal Figures, but each construction is a different Figure",
|
|
1173
|
+
"```",
|
|
1174
|
+
"; [E = (Figure [A, B]), E == (Figure [A, B]), E === (Figure [A, B]), E = (Figure [B, A])]",
|
|
1175
|
+
"# [<>, <>, (), ()]",
|
|
1176
|
+
"```",
|
|
1177
|
+
"Application appends one child and leaves the receiver alone, so a reduce into",
|
|
1178
|
+
"an empty Figure constructs, and a map extends one Figure per element",
|
|
1179
|
+
"```",
|
|
1180
|
+
"; [(E B) = (Figure [A, B, B]), ((E B).children .2) === B, E = (Figure [A, B])]",
|
|
1181
|
+
"# [<>, <>, <>]",
|
|
1182
|
+
"; [([A, B] | (Figure [])) = E, ([A, B] | (Figure [])) === E]",
|
|
1183
|
+
"# [<>, ()]",
|
|
1184
|
+
"; ([A, B] & (Figure [C])) = [Figure [C, A], Figure [C, B]]",
|
|
1185
|
+
"# <>",
|
|
1186
|
+
"```",
|
|
1187
|
+
"## Manyness and Size",
|
|
1188
|
+
"",
|
|
1189
|
+
"Manyness marks the immediate children and looks no deeper",
|
|
1190
|
+
"```",
|
|
1191
|
+
"; [(A.many()) = A, (E.many()) = (Figure [B, B]), (G.many()) = (E.many()), (E.many()) = (B.many())]",
|
|
1192
|
+
"# [<>, <>, <>, ()]",
|
|
1193
|
+
"```",
|
|
1194
|
+
"Size is recursive cell volume. `Z` is `A` and `U` is `B`, the same mark",
|
|
1195
|
+
"Manyness uses, so a count is itself a Figure of units. Size maps each child to its Size and joins them into",
|
|
1196
|
+
"`Tally Z`; the unit case comes first because a unit's only child is `Z`, and it",
|
|
1197
|
+
"tests form, so any Figure shaped like `U` is a cell",
|
|
1198
|
+
"```",
|
|
1199
|
+
"; [Z === A, U === B]",
|
|
1200
|
+
"# [<>, <>]",
|
|
1201
|
+
"; [(Z.size()) = Z, (U.size()) = (Figure [U]), ((Figure [U]).size()) = ((Figure [Figure [A]]).size())]",
|
|
1202
|
+
"# [<>, <>, <>]",
|
|
1203
|
+
"; .row2 (Figure [U, U]); .row3 (Figure [U, U, U]); .row4 (Figure [U, U, U, U]);",
|
|
1204
|
+
"; .deep4 (Figure [Figure [Figure [row4]]]); .two_fours (Figure [row4, row4]);",
|
|
1205
|
+
"; [(row4.size()) = row4, (deep4.size()) = row4, (two_fours.size()) = (row4.children | row4)]",
|
|
1206
|
+
"# [<>, <>, <>]",
|
|
1207
|
+
"; [(row4.many()) = (row4.size()), (deep4.many()) = (deep4.size()), (two_fours.many()) = row2]",
|
|
1208
|
+
"# [<>, (), <>]",
|
|
1209
|
+
"; ((Tally Z).row) = Z",
|
|
1210
|
+
"# <>",
|
|
1211
|
+
"```",
|
|
1212
|
+
"A tally is its own Size, so Size is idempotent",
|
|
1213
|
+
"```",
|
|
1214
|
+
"; ((two_fours.size()).size()) = (two_fours.size())",
|
|
1215
|
+
"# <>",
|
|
1216
|
+
"```",
|
|
1217
|
+
"## The semiring",
|
|
1218
|
+
"",
|
|
1219
|
+
"The carrier is not raw Figures. Let `F` be the finite, well-founded Figures,",
|
|
1220
|
+
"with the form of `U` as the unit cell, and write `x ≈ y` when",
|
|
1221
|
+
"`(x.size()) = (y.size())`. The carrier is the quotient `F/≈`, with zero `Z` and",
|
|
1222
|
+
"one `U`. Addition is construction, `Figure [x, y]`. Multiplication maps every",
|
|
1223
|
+
"cell of `x.size()` to `y`, so a product reuses `y` once per cell of `x`. A",
|
|
1224
|
+
"product by `Z` is `Z`, because one row of nothing, `Figure [Z]`, has the form of",
|
|
1225
|
+
"`U` and would count as a cell",
|
|
1226
|
+
"```",
|
|
1227
|
+
"; [(U.mul Z) = Z, ((Figure [Z]).size()) = (Figure [U])]",
|
|
1228
|
+
"# [<>, <>]",
|
|
1229
|
+
"```",
|
|
1230
|
+
"A non-square product is two occurrences of one three-cell row, and both",
|
|
1231
|
+
"positions are the same `row3`. Manyness sees two rows, while Size counts six",
|
|
1232
|
+
"```",
|
|
1233
|
+
"; .rectangle23 (row2.mul row3);",
|
|
1234
|
+
"; [rectangle23 = (Figure [row3, row3]), (rectangle23.children .0) === row3, (rectangle23.children .1) === row3]",
|
|
1235
|
+
"# [<>, <>, <>]",
|
|
1236
|
+
"; [(rectangle23.many()) = row2, (rectangle23.size()) = (Figure [U, U, U, U, U, U])]",
|
|
1237
|
+
"# [<>, <>]",
|
|
1238
|
+
"```",
|
|
1239
|
+
"Size takes construction to joining and multiplication to `size_mul`, so both",
|
|
1240
|
+
"recipes respect `≈`; the checks also use differently nested, equal-Size inputs",
|
|
1241
|
+
"```",
|
|
1242
|
+
"; [((Figure [row2, row3]).size()) = (Figure [U, U, U, U, U]), (rectangle23.size()) = ((row2.size()).size_mul (row3.size()))]",
|
|
1243
|
+
"# [<>, <>]",
|
|
1244
|
+
"; .deep2 (Figure [Figure [row2]]); .deep3 (Figure [Figure [Figure [row3]]]);",
|
|
1245
|
+
"; [row2.size_equivalent deep2, row3.size_equivalent deep3, (Figure [row2, row3]).size_equivalent (Figure [deep2, deep3]), (row2.mul row3).size_equivalent (deep2.mul deep3)] = [U, U, U, U]",
|
|
1246
|
+
"# <>",
|
|
1247
|
+
"```",
|
|
1248
|
+
"Tallies are the natural numbers in unary, so induction gives every semiring law",
|
|
1249
|
+
"on tallies, and transport along Size gives them on `F/≈`. The raw product is not",
|
|
1250
|
+
"commutative: `row2` by `row3` is two rows of three, `row3` by `row2` three rows",
|
|
1251
|
+
"of two, and they agree only in Size. These instances witness each law without",
|
|
1252
|
+
"replacing the proof",
|
|
1253
|
+
"```",
|
|
1254
|
+
"; [(row2.mul row3) = (row3.mul row2), ((row2.mul row3).size_equivalent (row3.mul row2)) = U]",
|
|
1255
|
+
"# [(), <>]",
|
|
1256
|
+
"; [(Figure [Z, row2]).size_equivalent row2, (Figure [row2, Z]).size_equivalent row2, (U.mul row2).size_equivalent row2, (row2.mul U).size_equivalent row2] = [U, U, U, U]",
|
|
1257
|
+
"# <>",
|
|
1258
|
+
"; [(Figure [Figure [row2, row3], row4]).size_equivalent (Figure [row2, Figure [row3, row4]]), (Figure [row2, row3]).size_equivalent (Figure [row3, row2])] = [U, U]",
|
|
1259
|
+
"# <>",
|
|
1260
|
+
"; (((row2.mul row3).mul row4).size_equivalent (row2.mul (row3.mul row4))) = U",
|
|
1261
|
+
"# <>",
|
|
1262
|
+
"; [(row2.mul (Figure [row3, row4])).size_equivalent (Figure [row2.mul row3, row2.mul row4]), ((Figure [row2, row3]).mul row4).size_equivalent (Figure [row2.mul row4, row3.mul row4])] = [U, U]",
|
|
1263
|
+
"# <>",
|
|
1264
|
+
"; [(Z.mul row3).size_equivalent Z, (row3.mul Z).size_equivalent Z] = [U, U]",
|
|
1265
|
+
"# <>",
|
|
1266
|
+
"```",
|
|
1267
|
+
"## Sameness and Withness",
|
|
1268
|
+
"",
|
|
1269
|
+
"Sameness of form is `=` and sameness of the constructed Figure is `===`",
|
|
1270
|
+
"```",
|
|
1271
|
+
"; .B2 (Figure [A]);",
|
|
1272
|
+
"; [B.sameform B2, B.sameness B, B.sameness B2, (E.children .0).sameness A] = [B, B, A, B]",
|
|
1273
|
+
"# <>",
|
|
1274
|
+
"```",
|
|
1275
|
+
"Withness asks whether every requested Figure is an immediate child of the",
|
|
1276
|
+
"receiver, by identity rather than form: `B` is reused under both `E` and `F`,",
|
|
1277
|
+
"while the separately constructed `B2` is a child of neither. An empty parent",
|
|
1278
|
+
"holds nothing, and every one of no Figures is a child of any parent",
|
|
1279
|
+
"```",
|
|
1280
|
+
"; [E.withness [A, B], F.withness [A, B], G.withness [E, F], E.withness [B2]] = [B, A, B, A]",
|
|
1281
|
+
"# <>",
|
|
1282
|
+
"; [A.withness [B], B.withness []] = [A, B]",
|
|
1283
|
+
"# <>",
|
|
1284
|
+
"```",
|
|
1285
|
+
"## The Fano plane",
|
|
1286
|
+
"",
|
|
1287
|
+
"Seven originals of identical form, each a fresh `Figure []`, and seven triples",
|
|
1288
|
+
"of identical form `[[], [], []]`. The incidence lives only in which originals",
|
|
1289
|
+
"each triple reuses, so only Withness, by identity, can see it. `b_copy` equals",
|
|
1290
|
+
"every original in form and is a child of no triple",
|
|
1291
|
+
"```",
|
|
1292
|
+
"; .a (Figure []); .b (Figure []); .c (Figure []); .d (Figure []); .e (Figure []); .f (Figure []); .g (Figure []);",
|
|
1293
|
+
"; .originals (Figure [a, b, c, d, e, f, g]);",
|
|
1294
|
+
"; .abd (Figure [a, b, d]); .bce (Figure [b, c, e]); .cdf (Figure [c, d, f]);",
|
|
1295
|
+
"; .deg (Figure [d, e, g]); .efa (Figure [e, f, a]); .fgb (Figure [f, g, b]); .gac (Figure [g, a, c]);",
|
|
1296
|
+
"; .fano (Figure [abd, bce, cdf, deg, efa, fgb, gac]);",
|
|
1297
|
+
"; .Three (Figure [U, U, U]); .b_copy (Figure []);",
|
|
1298
|
+
"; [(originals.many()) = (fano.many()), (fano.children & {_.many()}) = (fano.children & {Three})]",
|
|
1299
|
+
"# [<>, <>]",
|
|
1300
|
+
"; [abd = bce, abd === bce, b = b_copy, b === b_copy]",
|
|
1301
|
+
"# [<>, (), <>, ()]",
|
|
1302
|
+
"; [abd.withness [a, b, d], abd.withness [a, c], abd.withness [b_copy]] = [B, A, A]",
|
|
1303
|
+
"# <>",
|
|
1304
|
+
"```",
|
|
1305
|
+
"`on` answers one Withness mark per triple, so its Size counts the triples that",
|
|
1306
|
+
"hold every requested original. Over every ordered pair, generated rather than",
|
|
1307
|
+
"listed, two distinct originals lie in exactly one triple and each lies in three",
|
|
1308
|
+
"```",
|
|
1309
|
+
"; .on {.points _; Figure (fano.children & {_.withness points})};",
|
|
1310
|
+
"; .point_table (originals.children & {.p _; originals.children & {(on [p, _]).size()}});",
|
|
1311
|
+
"; point_table = (originals.children & {.p _; originals.children & {(p === _) ? {Three} : {Figure [U]}}})",
|
|
1312
|
+
"# <>",
|
|
1313
|
+
"```",
|
|
1314
|
+
"Dually, `meet` counts the originals two triples share: multiplying their two",
|
|
1315
|
+
"Withness marks leaves one cell exactly when both hold it. The two tables are",
|
|
1316
|
+
"equal, which is the plane's self-duality",
|
|
1317
|
+
"```",
|
|
1318
|
+
"; .meet {.lines _; (Figure (originals.children & {.o _; ((lines .0).withness [o]).mul ((lines .1).withness [o])})).size()};",
|
|
1319
|
+
"; .line_table (fano.children & {.l _; fano.children & {meet [l, _]}});",
|
|
1320
|
+
"; [line_table = (fano.children & {.l _; fano.children & {(l === _) ? {Three} : {Figure [U]}}}), point_table = line_table]",
|
|
1321
|
+
"# [<>, <>]",
|
|
1322
|
+
"```",
|
|
1323
|
+
"`a, b, c, f` are four originals with no three in a triple",
|
|
1324
|
+
"```",
|
|
1325
|
+
"; ([[a, b, c], [a, b, f], [a, c, f], [b, c, f]] & {(on _).size()}) = [Z, Z, Z, Z]",
|
|
1326
|
+
"# <>",
|
|
1327
|
+
"```",
|
|
1328
|
+
"## Closure",
|
|
1329
|
+
"",
|
|
1330
|
+
"Every answer is a Figure, so it can be observed again or become a child, and",
|
|
1331
|
+
"observing does not mutate, even with a local name inside a map",
|
|
1332
|
+
"```",
|
|
1333
|
+
"; [((E.many()).many()) = (E.many()), ((Figure [E.many(), F.size()]).size()) = row4]",
|
|
1334
|
+
"# [<>, <>]",
|
|
1335
|
+
"; .E5 (Figure [A, Figure [A]]);",
|
|
1336
|
+
"; E5.children & {.o _; o};",
|
|
1337
|
+
"; [E5 = (Figure [A, B]), A = (Figure [])]",
|
|
1338
|
+
"# [<>, <>]",
|
|
1339
|
+
"```",
|
|
1340
|
+
"## Names",
|
|
1341
|
+
"",
|
|
1342
|
+
"A bare name inside a block that a map applies to Figures reads each Figure's",
|
|
1343
|
+
"own members first (spec 7), so it cannot reach the method's. That is why a",
|
|
1344
|
+
"method names its own Figure `_^` and binds `kids` before its blocks read it",
|
|
1345
|
+
"```",
|
|
1346
|
+
"; (E.children & {children}) = [A.children, B.children]",
|
|
1347
|
+
"# <>",
|
|
1348
|
+
"```",
|
|
1349
|
+
"A method's own locals come ahead of any binding where it is called, and a",
|
|
1350
|
+
"Figure passed as an argument contributes only its members, never the names of",
|
|
1351
|
+
"the scope that built it. The Fano plane above already binds `f`, the name",
|
|
1352
|
+
"Withness uses inside its blocks; these bind the other locals",
|
|
1353
|
+
"```",
|
|
1354
|
+
"; .kids 9; .y 9; .cells 9; .found 9; .absent 9;",
|
|
1355
|
+
"; [(E.withness [A, B]) = B, (row2.mul row3) = rectangle23, (E.size()) = (Figure [U])]",
|
|
1356
|
+
"# [<>, <>, <>]",
|
|
1357
|
+
"```",
|
|
1358
|
+
"A method's free names resolve where the method was written, never where its",
|
|
1359
|
+
"receiver was read (#400). So a scope that binds its own `B` and reads a Figure",
|
|
1360
|
+
"by name there still gets the class's `B` back from Manyness",
|
|
1361
|
+
"```",
|
|
1362
|
+
"; .theB B;",
|
|
1363
|
+
"; .rebinds {.B 5; .mine (Figure [A]); ((mine.many()).children .0) === theB};",
|
|
1364
|
+
"; rebinds()",
|
|
1365
|
+
"# <>",
|
|
1366
|
+
"```",
|
|
1367
|
+
"## Functional updates",
|
|
1368
|
+
"",
|
|
1369
|
+
"A mutating method reached through an immutable handle is a functional update,",
|
|
1370
|
+
"and it copies only what it writes (#401). A Figure the receiver holds is never",
|
|
1371
|
+
"written, so the result holds the very same Figure, and identity observers",
|
|
1372
|
+
"answer about it",
|
|
1373
|
+
"```",
|
|
1374
|
+
"; .keeper [.fig E; .touch_ {@fig fig;}];",
|
|
1375
|
+
"; .kept ((keeper.touch_ ()).fig);",
|
|
1376
|
+
"; [kept === E, (kept.children .0) === A]",
|
|
1377
|
+
"# [<>, <>]",
|
|
1378
|
+
"; [kept.sameness kept, kept.withness [kept.children .0]] = [B, B]",
|
|
1379
|
+
"# <>",
|
|
1380
|
+
"```",
|
|
1381
|
+
"A write that constructs answers a new Figure, which is a Figure like any other",
|
|
1382
|
+
"```",
|
|
1383
|
+
"; .grower [.fig E; .grow_ {@fig (fig B);}];",
|
|
1384
|
+
"; .grown ((grower.grow_ ()).fig);",
|
|
1385
|
+
"; [(grown.sameness grown) = B, (grown.withness [grown.children .2]) = B, grown === E]",
|
|
1386
|
+
"# [<>, <>, ()]",
|
|
1387
|
+
"```",
|
|
1388
|
+
"## Spelling",
|
|
1389
|
+
"",
|
|
1390
|
+
"`(x)` is `x`, so `Figure (B)` collects B's elements, of which an object with",
|
|
1391
|
+
"only properties has none. Write `Figure [B]`",
|
|
1392
|
+
"```",
|
|
1393
|
+
"; [(Figure (B)) = A, (Figure [B]) = C]",
|
|
1394
|
+
"# [<>, <>]",
|
|
1395
|
+
"; (Figure [A, B]) = E",
|
|
1396
|
+
"# <>",
|
|
1397
|
+
"```",
|
|
1398
|
+
"Importing this file skips its examples and answers its last form, which the",
|
|
1399
|
+
"hosts' smoke tests read, so the file ends on code that holds however the rest of",
|
|
1400
|
+
"it changes",
|
|
1401
|
+
"```",
|
|
1402
|
+
"B = (Figure [A])",
|
|
1403
|
+
"",
|
|
1404
|
+
].join("\n"),
|
|
1405
|
+
],
|
|
1406
|
+
[
|
|
1407
|
+
"hc/format.hc",
|
|
1408
|
+
[
|
|
1409
|
+
"#!/usr/bin/env hc",
|
|
1410
|
+
"`Executable canonical-rendering coverage. Each source line is evaluated and its",
|
|
1411
|
+
"printed result is checked by HCTest; this is not a parse-only formatter suite.`",
|
|
1412
|
+
"",
|
|
1413
|
+
"; {1}",
|
|
1414
|
+
"# { 1 }",
|
|
1415
|
+
"; {_}",
|
|
1416
|
+
"# { _ }",
|
|
1417
|
+
"; { _ + 1 }",
|
|
1418
|
+
"# { _ + 1 }",
|
|
1419
|
+
"",
|
|
1420
|
+
"; [1,2,3]",
|
|
1421
|
+
"# [1, 2, 3]",
|
|
1422
|
+
"",
|
|
1423
|
+
"; { { _ + __ } } 10 5",
|
|
1424
|
+
"# 15",
|
|
1425
|
+
"; {_^.value} (.value 9;)",
|
|
1426
|
+
"# $!.name-missing...",
|
|
1427
|
+
"",
|
|
1428
|
+
"; 0xabc",
|
|
1429
|
+
"# 0xabc",
|
|
1430
|
+
"",
|
|
1431
|
+
].join("\n"),
|
|
1432
|
+
],
|
|
1433
|
+
[
|
|
1434
|
+
"hc/gerbil.hc",
|
|
1435
|
+
[
|
|
1436
|
+
"#!/usr/bin/env hclang",
|
|
1437
|
+
".hc 1.0.0; # Version",
|
|
1438
|
+
". <- .com.drernie.ths.ipa; # Import Module",
|
|
1439
|
+
"",
|
|
1440
|
+
"# Create Simulation",
|
|
1441
|
+
"",
|
|
1442
|
+
".Seuss Population[.Gerbil, .Horton, .Lorax, 24 .Who];",
|
|
1443
|
+
"",
|
|
1444
|
+
"# Declarations",
|
|
1445
|
+
"",
|
|
1446
|
+
"Seuss.Resource .R_BUCKS .R_HAIR;",
|
|
1447
|
+
"Seuss.Value .V_EXERCISE .V_REST;",
|
|
1448
|
+
"Who.Value .LOVES_GERBIL .IS_HORTONSY;",
|
|
1449
|
+
"Who.Capability .C_SHOE .C_SEAT;",
|
|
1450
|
+
"",
|
|
1451
|
+
"# Games",
|
|
1452
|
+
"",
|
|
1453
|
+
"Who.< .Hortian, .Loroid >;",
|
|
1454
|
+
"",
|
|
1455
|
+
"Hortian.Game { R_BUCKS(V_REST C_SEAT R_HAIR) };",
|
|
1456
|
+
"Loroid.Game { R_BUCKS(V_EXERCISE C_SHOE R_HAIR) };",
|
|
1457
|
+
"",
|
|
1458
|
+
"Hortian.Game { Status IS_HORTONSY };",
|
|
1459
|
+
"Loroid.Game { Status -IS_HORTONSY };",
|
|
1460
|
+
"",
|
|
1461
|
+
"Hortian.Game { Status C_SEAT };",
|
|
1462
|
+
"Loroid.Game { Status LOVES_GERBIL };",
|
|
1463
|
+
"",
|
|
1464
|
+
"Who.Game { Status R_BUCKS };",
|
|
1465
|
+
"Horton.Game { Status N(Hortian) };",
|
|
1466
|
+
"Lorax.Game { Status N(Loroid) };",
|
|
1467
|
+
"",
|
|
1468
|
+
"# Scenarios",
|
|
1469
|
+
"",
|
|
1470
|
+
"Gerbil.Scenario { R_HAIR(V_EXERCISE).latency 10 };",
|
|
1471
|
+
"Gerbil.Scenario { R_HAIR(V_REST).latency 10 };",
|
|
1472
|
+
"",
|
|
1473
|
+
].join("\n"),
|
|
1474
|
+
],
|
|
1475
|
+
[
|
|
1476
|
+
"hc/hcsv.hc",
|
|
1477
|
+
[
|
|
1478
|
+
".hc 0.6.0",
|
|
1479
|
+
"",
|
|
1480
|
+
"```",
|
|
1481
|
+
"### HCSV",
|
|
1482
|
+
"",
|
|
1483
|
+
"Homoiconic C may finally provide a well-defined alternative to the",
|
|
1484
|
+
'ubiquitous CSV[@Cite] file. A properly-structured ".hcsv" file is just as compact',
|
|
1485
|
+
"as CSV, with two important differences:",
|
|
1486
|
+
"* The header row, if any, consists of a list of names",
|
|
1487
|
+
"* Strings must be (smart) quoted",
|
|
1488
|
+
"```",
|
|
1489
|
+
".first-name, .last-name, .phone-number",
|
|
1490
|
+
"“John”, “Doe”, +1.408.555.1212",
|
|
1491
|
+
"“Jane”, “Smith”, +1.650.555.1212",
|
|
1492
|
+
"```",
|
|
1493
|
+
"",
|
|
1494
|
+
"### HCSON",
|
|
1495
|
+
"",
|
|
1496
|
+
"HC can also emulate the popular JSON[@Cite] format, or more precisely its",
|
|
1497
|
+
"CoffeeScript cousin CSON[@Cite].",
|
|
1498
|
+
"```",
|
|
1499
|
+
".first-name “John”, .last-name “Doe”, .phone-number +1.408.555.1212",
|
|
1500
|
+
".first-name “Jane”, .last-name “Smith”, .phone-number +1.650.555.1212",
|
|
1501
|
+
"",
|
|
1502
|
+
].join("\n"),
|
|
1503
|
+
],
|
|
1504
|
+
[
|
|
1505
|
+
"hc/led_blink.hc",
|
|
1506
|
+
[
|
|
1507
|
+
".hc 0.6.0",
|
|
1508
|
+
"",
|
|
1509
|
+
". <- <>.hcdl.fpga",
|
|
1510
|
+
"",
|
|
1511
|
+
".blinker <",
|
|
1512
|
+
" .-clock <fpga.clock>;",
|
|
1513
|
+
" .-reset <fpga.button>;",
|
|
1514
|
+
" .led- <2 fpga.led>;",
|
|
1515
|
+
"> ^ {",
|
|
1516
|
+
" .count fpga.reg(27);",
|
|
1517
|
+
" count.26 .=> led-.0;",
|
|
1518
|
+
" count.25 .=> led-.1;",
|
|
1519
|
+
"",
|
|
1520
|
+
" -reset.posedge .=> { count .<= 0};",
|
|
1521
|
+
" -clock.posedge .=> { count .<=+ 1};",
|
|
1522
|
+
" .run {",
|
|
1523
|
+
" -clock.start();",
|
|
1524
|
+
" };",
|
|
1525
|
+
"};",
|
|
1526
|
+
"",
|
|
1527
|
+
"",
|
|
1528
|
+
".demo blinker(",
|
|
1529
|
+
" .-clock fpga.clock(100.mega.hz);",
|
|
1530
|
+
" .-reset fpga.button();",
|
|
1531
|
+
" .led- fpga.led(2);",
|
|
1532
|
+
");",
|
|
1533
|
+
"demo.run();",
|
|
1534
|
+
"",
|
|
1535
|
+
"```verilog",
|
|
1536
|
+
"module led_simple(",
|
|
1537
|
+
" input clock,",
|
|
1538
|
+
" input reset,",
|
|
1539
|
+
" output led, led2, led3, led4, led5",
|
|
1540
|
+
" );",
|
|
1541
|
+
"",
|
|
1542
|
+
"reg [26:0] count; //A sizable 27 bit register so that the blink can be seen and is visible, too small a register will make the",
|
|
1543
|
+
" //register stay on as it will blink extremely fast.",
|
|
1544
|
+
"",
|
|
1545
|
+
"always@ (posedge clock or posedge reset)",
|
|
1546
|
+
" begin",
|
|
1547
|
+
" if (reset)",
|
|
1548
|
+
" count <= 0; //if reset button is pressed, initialize or reset the register",
|
|
1549
|
+
" else",
|
|
1550
|
+
" count <= count + 1; //otherwise increment the register",
|
|
1551
|
+
" end",
|
|
1552
|
+
"",
|
|
1553
|
+
"assign led = count[26]; //MSB connected to output led. and the other outputs connected as below",
|
|
1554
|
+
"assign led2 = count[25];",
|
|
1555
|
+
"assign led3 = count[24];",
|
|
1556
|
+
"assign led4 = count[23];",
|
|
1557
|
+
"assign led5 = count[22];",
|
|
1558
|
+
"endmodule",
|
|
1559
|
+
"```",
|
|
1560
|
+
"",
|
|
1561
|
+
].join("\n"),
|
|
1562
|
+
],
|
|
1563
|
+
[
|
|
1564
|
+
"hc/modules.hc",
|
|
1565
|
+
[
|
|
1566
|
+
"#!/usr/bin/env hc",
|
|
1567
|
+
"```",
|
|
1568
|
+
"Modules",
|
|
1569
|
+
"A module is HC source read through a resource. `name <- resource` evaluates",
|
|
1570
|
+
"that source in a fresh namespace and binds the namespace to `name` only once",
|
|
1571
|
+
"every form has succeeded, so everything the module declares is reached here",
|
|
1572
|
+
"qualified, through `Figures`, and nothing it declares lands in this file.",
|
|
1573
|
+
"",
|
|
1574
|
+
"Every file in the repository's `hc/` folder ships with the package, so a",
|
|
1575
|
+
"session can include any of them. `'./hc/figures.hc'` names one. The path is",
|
|
1576
|
+
"relative to the root binding, not to this file or to the working directory. The",
|
|
1577
|
+
"CLI's root is a fresh temporary directory, and the harness lays the bundled",
|
|
1578
|
+
"files over it read-only, so this import reads the bytes of `hc/figures.hc`,",
|
|
1579
|
+
"which every host compiles in, so the same import works in the compiled binary,",
|
|
1580
|
+
"the npm package, and the browser playground. That file is a testdoc too: its",
|
|
1581
|
+
"claims count when it is run directly, and none of them count here. Importing",
|
|
1582
|
+
"skips its examples, the lines that begin `; ` outside prose, so only its code",
|
|
1583
|
+
"runs and the namespace holds only what the module declares",
|
|
1584
|
+
"```",
|
|
1585
|
+
"; Figures <- './hc/figures.hc';",
|
|
1586
|
+
"```",
|
|
1587
|
+
"`Figure [c, …]` is the constructor, and every observer is a method that answers",
|
|
1588
|
+
"a Figure. Size answers a tally, one unit cell `U` for every cell, while Manyness",
|
|
1589
|
+
"marks only the immediate children",
|
|
1590
|
+
"```",
|
|
1591
|
+
"; [(Figures.Z.size()) = Figures.Z, (Figures.U.size()) = (Figures.Figure [Figures.U])]",
|
|
1592
|
+
"# [<>, <>]",
|
|
1593
|
+
"; ((Figures.Figure [Figures.U, Figures.U]).many()) = (Figures.Figure [Figures.B, Figures.B])",
|
|
1594
|
+
"# <>",
|
|
1595
|
+
"; ((Figures.Figure [Figures.B]).children .0) === Figures.B",
|
|
1596
|
+
"# <>",
|
|
1597
|
+
"; (“E is ” (Figures.Figure [Figures.A, Figures.B])) = “E is [[], [[]]]”",
|
|
1598
|
+
"# <>",
|
|
1599
|
+
"```",
|
|
1600
|
+
"Sameness of form is `=` and sameness of the constructed Figure is `===`, so `B`",
|
|
1601
|
+
"and a fresh `Figure [A]` agree in form and in Size but are not the same Figure",
|
|
1602
|
+
"```",
|
|
1603
|
+
"; .fresh (Figures.Figure [Figures.A]);",
|
|
1604
|
+
"; [Figures.B.sameform fresh, Figures.B.size_equivalent fresh, Figures.B.sameness Figures.B, Figures.B.sameness fresh] = [Figures.B, Figures.U, Figures.B, Figures.A]",
|
|
1605
|
+
"# <>",
|
|
1606
|
+
"```",
|
|
1607
|
+
"Imported methods compose with Figures built in this file, each with",
|
|
1608
|
+
"`Figures.Figure`. Size counts the cells of a Figure sum and of a Figure product.",
|
|
1609
|
+
"On tallies, joining is a reduce, `ys | x`. `size_mul` multiplies, and `Tally Z`",
|
|
1610
|
+
"collects a reduce",
|
|
1611
|
+
"```",
|
|
1612
|
+
"; .duo (Figures.Figure [Figures.U, Figures.U]);",
|
|
1613
|
+
"; .trio (Figures.Figure [Figures.U, Figures.U, Figures.U]);",
|
|
1614
|
+
"; .six (Figures.Figure [Figures.U, Figures.U, Figures.U, Figures.U, Figures.U, Figures.U]);",
|
|
1615
|
+
"; [(duo.size()) = duo, ((duo.mul trio).size()) = six, (duo.size_mul trio) = six]",
|
|
1616
|
+
"# [<>, <>, <>]",
|
|
1617
|
+
"; (trio.children | (Figures.Figure [Figures.U])) = (Figures.Figure [Figures.U, Figures.U, Figures.U, Figures.U])",
|
|
1618
|
+
"# <>",
|
|
1619
|
+
"; (([Figures.Figure [Figures.U], Figures.Figure [Figures.U]] | (Figures.Tally Figures.Z)).row) = duo",
|
|
1620
|
+
"# <>",
|
|
1621
|
+
"```",
|
|
1622
|
+
"Identity crosses the import boundary. Withness asks for immediate containment",
|
|
1623
|
+
"by `===`, so the module's own `A` is with a parent built here, while a fresh",
|
|
1624
|
+
"`Figure []` of the same form is not",
|
|
1625
|
+
"```",
|
|
1626
|
+
"; .pair (Figures.Figure [Figures.A, Figures.B]);",
|
|
1627
|
+
"; [pair.withness [Figures.A], pair.withness [Figures.Figure []]] = [Figures.B, Figures.A]",
|
|
1628
|
+
"# <>",
|
|
1629
|
+
"```",
|
|
1630
|
+
"The overlay grants reads of the bundled files and nothing else. Writing to one is",
|
|
1631
|
+
"refused,",
|
|
1632
|
+
"and every other path still resolves inside the fresh root, including",
|
|
1633
|
+
"`deno.json`, which exists in the working directory whether the CLI runs from the",
|
|
1634
|
+
"repository root or from `cli/`, and a path under `hc/` that ships no file",
|
|
1635
|
+
"```",
|
|
1636
|
+
"; './hc/figures.hc' “overwrite”",
|
|
1637
|
+
"# $!.resource-read-only './hc/figures.hc'",
|
|
1638
|
+
"; './deno.json' | “”",
|
|
1639
|
+
"# $!.resource-absent './deno.json'",
|
|
1640
|
+
"; './hc/other.hc' | “”",
|
|
1641
|
+
"# $!.resource-absent './hc/other.hc'",
|
|
1642
|
+
"",
|
|
1643
|
+
].join("\n"),
|
|
1644
|
+
],
|
|
1645
|
+
[
|
|
1646
|
+
"hc/numerics.hc",
|
|
1647
|
+
[
|
|
1648
|
+
"#!/usr/bin/env hc",
|
|
1649
|
+
"```",
|
|
1650
|
+
"Rationalizing numbers (#355)",
|
|
1651
|
+
"",
|
|
1652
|
+
"These examples are the executable acceptance corpus for spec a08. Integers,",
|
|
1653
|
+
"decimals, and rationals are numeric; dotted sequences preserve spelling but are",
|
|
1654
|
+
"not numeric.",
|
|
1655
|
+
"",
|
|
1656
|
+
"Syntactic ladder",
|
|
1657
|
+
"```",
|
|
1658
|
+
"; 3",
|
|
1659
|
+
"# 3",
|
|
1660
|
+
"; 3.14",
|
|
1661
|
+
"# 3.14",
|
|
1662
|
+
"; 1.408.055.1212",
|
|
1663
|
+
"# 1.408.055.1212",
|
|
1664
|
+
"; 0",
|
|
1665
|
+
"# 0",
|
|
1666
|
+
"; 0.5",
|
|
1667
|
+
"# 0.5",
|
|
1668
|
+
"```",
|
|
1669
|
+
"Exact arithmetic",
|
|
1670
|
+
"```",
|
|
1671
|
+
"; 12345678901234567890 + 1",
|
|
1672
|
+
"# 12345678901234567891",
|
|
1673
|
+
"; 1.1 + 2.2",
|
|
1674
|
+
"# 3.3",
|
|
1675
|
+
"; (1 / 3) + (1 / 3) + (1 / 3)",
|
|
1676
|
+
"# 1",
|
|
1677
|
+
"; 3 2",
|
|
1678
|
+
"# 6",
|
|
1679
|
+
"```",
|
|
1680
|
+
"Division follows the divisor's rung",
|
|
1681
|
+
"```",
|
|
1682
|
+
"; 1 / 2",
|
|
1683
|
+
"# 1/2",
|
|
1684
|
+
"; 3 / 2",
|
|
1685
|
+
"# 3/2",
|
|
1686
|
+
"; 4 / 2",
|
|
1687
|
+
"# 2",
|
|
1688
|
+
"; 10.50 / 2",
|
|
1689
|
+
"# 21/4",
|
|
1690
|
+
"; 1 / 2.0",
|
|
1691
|
+
"# 0.5",
|
|
1692
|
+
"; 1.5 / 3",
|
|
1693
|
+
"# 1/2",
|
|
1694
|
+
"; 1.5 / (5 / 2)",
|
|
1695
|
+
"# 3/5",
|
|
1696
|
+
"; 0.3 / 0.1",
|
|
1697
|
+
"# 2.9999999999999996",
|
|
1698
|
+
"```",
|
|
1699
|
+
"Signs and common factors canonicalize",
|
|
1700
|
+
"```",
|
|
1701
|
+
"; (1 - 2) / 4",
|
|
1702
|
+
"# -1/4",
|
|
1703
|
+
"; 2 / (1 - 5)",
|
|
1704
|
+
"# -1/2",
|
|
1705
|
+
"```",
|
|
1706
|
+
"Exponentiation stays exact when its exponent is integral",
|
|
1707
|
+
"```",
|
|
1708
|
+
"; 2 ** 64",
|
|
1709
|
+
"# 18446744073709551616",
|
|
1710
|
+
"; 2 ** (1 - 2)",
|
|
1711
|
+
"# 1/2",
|
|
1712
|
+
"; 2 ** 1.5",
|
|
1713
|
+
"# 2.8284271247461903",
|
|
1714
|
+
"```",
|
|
1715
|
+
"Numeric equality is exact. `=` asks for the same value, `==` also asks for the",
|
|
1716
|
+
"same rung, and `===` asks for the same frame, which for a number is `==`",
|
|
1717
|
+
"```",
|
|
1718
|
+
"; 3 = 3.0",
|
|
1719
|
+
"# <>",
|
|
1720
|
+
"; 3 == 3.0",
|
|
1721
|
+
"# ()",
|
|
1722
|
+
"; 0123 = 123",
|
|
1723
|
+
"# <>",
|
|
1724
|
+
"; 0123 == 123",
|
|
1725
|
+
"# <>",
|
|
1726
|
+
"; 3 === 3.0",
|
|
1727
|
+
"# ()",
|
|
1728
|
+
"; 3 === 3",
|
|
1729
|
+
"# <>",
|
|
1730
|
+
"; 1.408.055.1212 = 1.408.055.1212",
|
|
1731
|
+
"# <>",
|
|
1732
|
+
"```",
|
|
1733
|
+
"Integer-only repetition remains available",
|
|
1734
|
+
"```",
|
|
1735
|
+
"; 3“Hello”",
|
|
1736
|
+
"# “HelloHelloHello”",
|
|
1737
|
+
"",
|
|
1738
|
+
"```",
|
|
1739
|
+
"Cross-rung promotion and integer-only modulo",
|
|
1740
|
+
"```",
|
|
1741
|
+
"; 1 + 2.5",
|
|
1742
|
+
"# 3.5",
|
|
1743
|
+
"; 1.5 + (1 / 3)",
|
|
1744
|
+
"# 11/6",
|
|
1745
|
+
"; 3.%%2",
|
|
1746
|
+
"# 1",
|
|
1747
|
+
"; 3.0 %% 2",
|
|
1748
|
+
"# $!.numeric-domain %% FrameDecimal FrameCount",
|
|
1749
|
+
"```",
|
|
1750
|
+
"Zero and unsupported domains return stable errors",
|
|
1751
|
+
"```",
|
|
1752
|
+
"; 1 / (1 - 1)",
|
|
1753
|
+
"# $!.division-by-zero /",
|
|
1754
|
+
"; 1 %% (1 - 1)",
|
|
1755
|
+
"# $!.modulo-by-zero %%",
|
|
1756
|
+
"; 1.408.555 + 1",
|
|
1757
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1758
|
+
"; 1.408.555.< 2",
|
|
1759
|
+
"# $!.numeric-domain < FrameSequence FrameCount",
|
|
1760
|
+
"; 1.408.555 = 1",
|
|
1761
|
+
"# ()",
|
|
1762
|
+
"; -1.408.555",
|
|
1763
|
+
"# $!.numeric-domain property FrameDecimal",
|
|
1764
|
+
"```",
|
|
1765
|
+
"Repetition and exact powers fail before unsafe allocation",
|
|
1766
|
+
"```",
|
|
1767
|
+
"; 3.14“Hello”",
|
|
1768
|
+
"# $!.repetition-domain FrameDecimal",
|
|
1769
|
+
"; 1.408.555“Hi”",
|
|
1770
|
+
"# $!.repetition-domain FrameSequence",
|
|
1771
|
+
"; 65537“x”",
|
|
1772
|
+
"# $!.repetition-limit 65536",
|
|
1773
|
+
"; 2 ** 1000000",
|
|
1774
|
+
"# $!.numeric-range ** FrameCount",
|
|
1775
|
+
"```",
|
|
1776
|
+
"Counts (#407). Every nonnegative integer literal is a `FrameCount`, the root of",
|
|
1777
|
+
"the ladder, and prints as the same integer does. A sequence's refusal names the",
|
|
1778
|
+
"class of its other operand, which is how these examples observe the rung",
|
|
1779
|
+
"```",
|
|
1780
|
+
"; 1.408.555 + 0",
|
|
1781
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1782
|
+
"; 1.408.555 + 1234567890",
|
|
1783
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1784
|
+
"; 1.408.555 + -1",
|
|
1785
|
+
"# $!.numeric-domain + FrameSequence FrameInt",
|
|
1786
|
+
"```",
|
|
1787
|
+
"Counts are closed under `+`, `*`, `%%`, and a nonnegative integral `**`",
|
|
1788
|
+
"```",
|
|
1789
|
+
"; 1.408.555 + (2 + 3)",
|
|
1790
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1791
|
+
"; 1.408.555 + (2 3)",
|
|
1792
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1793
|
+
"; 1.408.555 + (7 %% 3)",
|
|
1794
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1795
|
+
"; 1.408.555 + (2 ** 3)",
|
|
1796
|
+
"# $!.numeric-domain + FrameSequence FrameCount",
|
|
1797
|
+
"```",
|
|
1798
|
+
"Negation and subtraction answer `FrameInt` whatever the sign of the result, and",
|
|
1799
|
+
"division answers a ratio, which collapses to `FrameInt` when it is whole",
|
|
1800
|
+
"```",
|
|
1801
|
+
"; 5 - 3",
|
|
1802
|
+
"# 2",
|
|
1803
|
+
"; 1.408.555 + (5 - 3)",
|
|
1804
|
+
"# $!.numeric-domain + FrameSequence FrameInt",
|
|
1805
|
+
"; 1.408.555 + -0",
|
|
1806
|
+
"# $!.numeric-domain + FrameSequence FrameInt",
|
|
1807
|
+
"; 1.408.555 + (6 / 3)",
|
|
1808
|
+
"# $!.numeric-domain + FrameSequence FrameInt",
|
|
1809
|
+
"; 7 / 2",
|
|
1810
|
+
"# 7/2",
|
|
1811
|
+
"```",
|
|
1812
|
+
"Mixed operands follow the ladder",
|
|
1813
|
+
"```",
|
|
1814
|
+
"; 1.408.555 + (2 + (0 - 3))",
|
|
1815
|
+
"# $!.numeric-domain + FrameSequence FrameInt",
|
|
1816
|
+
"; 1.408.555 + (2 * 1.5)",
|
|
1817
|
+
"# $!.numeric-domain + FrameSequence FrameDecimal",
|
|
1818
|
+
"; 7 %% (0 - 3)",
|
|
1819
|
+
"# -2",
|
|
1820
|
+
"```",
|
|
1821
|
+
"Comparison and `=` compare values across rungs, so a count and a FrameInt of the",
|
|
1822
|
+
"same value are `=`. `==`, `===` and `~~` compare exact types, so the two are",
|
|
1823
|
+
"not `==`, just as `2` and `2.0` are not",
|
|
1824
|
+
"```",
|
|
1825
|
+
"; 2 = (5 - 3)",
|
|
1826
|
+
"# <>",
|
|
1827
|
+
"; (5 - 3) = 2",
|
|
1828
|
+
"# <>",
|
|
1829
|
+
"; 2 == (5 - 3)",
|
|
1830
|
+
"# ()",
|
|
1831
|
+
"; (5 - 3) == 2",
|
|
1832
|
+
"# ()",
|
|
1833
|
+
"; 2 === (5 - 3)",
|
|
1834
|
+
"# ()",
|
|
1835
|
+
"; 2 == 2.0",
|
|
1836
|
+
"# ()",
|
|
1837
|
+
"; ~~2 (5 - 3)",
|
|
1838
|
+
"# $!.type-error ~~2 2",
|
|
1839
|
+
"; ~~(5 - 3) 2",
|
|
1840
|
+
"# $!.type-error ~~2 2",
|
|
1841
|
+
"; (0 - 1).< 0",
|
|
1842
|
+
"# <>",
|
|
1843
|
+
"; 2.<= (5 - 3)",
|
|
1844
|
+
"# <>",
|
|
1845
|
+
"; 2.< 2.5",
|
|
1846
|
+
"# <>",
|
|
1847
|
+
"```",
|
|
1848
|
+
"Within one rung, `==` and `~~` hold as they always have",
|
|
1849
|
+
"```",
|
|
1850
|
+
"; 2 == (1 + 1)",
|
|
1851
|
+
"# <>",
|
|
1852
|
+
"; (5 - 3) == (4 - 2)",
|
|
1853
|
+
"# <>",
|
|
1854
|
+
"; ~~2 3",
|
|
1855
|
+
"# 3",
|
|
1856
|
+
"; ~~(0 - 1) (0 - 5)",
|
|
1857
|
+
"# -5",
|
|
1858
|
+
"",
|
|
1859
|
+
].join("\n"),
|
|
1860
|
+
],
|
|
1861
|
+
[
|
|
1862
|
+
"hc/resources.hc",
|
|
1863
|
+
[
|
|
1864
|
+
"#!/usr/bin/env hc",
|
|
1865
|
+
"```",
|
|
1866
|
+
"Resource references (#348)",
|
|
1867
|
+
"",
|
|
1868
|
+
"These examples are the executable acceptance corpus for the `'…'` resource",
|
|
1869
|
+
"primitive. A resource identifier is the resource: when a root binding is",
|
|
1870
|
+
"reachable in the invocation context, applying the identifier writes and",
|
|
1871
|
+
"enumerating it reads. There is no I/O primitive to name.",
|
|
1872
|
+
"",
|
|
1873
|
+
"The Deno CLI installs a root binding at a fresh temp directory, so these",
|
|
1874
|
+
"examples write and read real files without naming a real path anywhere.",
|
|
1875
|
+
"",
|
|
1876
|
+
"Writing is application, and it answers with the characters written rather than",
|
|
1877
|
+
"with the receiver, so a refusal cannot hide inside a successful-looking result",
|
|
1878
|
+
"```",
|
|
1879
|
+
"; './out.txt' “hello”",
|
|
1880
|
+
"# 5",
|
|
1881
|
+
"```",
|
|
1882
|
+
"Reading is a reduce over characters, so what the read starts from is what shapes",
|
|
1883
|
+
"them. Text joins them back into whole content; an aggregate keeps them apart. No",
|
|
1884
|
+
"part of the reading is a property of the resource",
|
|
1885
|
+
"```",
|
|
1886
|
+
"; './out.txt' | “”",
|
|
1887
|
+
"# “hello”",
|
|
1888
|
+
"; './out.txt' | []",
|
|
1889
|
+
"# [“h”, “e”, “l”, “l”, “o”]",
|
|
1890
|
+
"; './out.txt' & {_}",
|
|
1891
|
+
"# [“h”, “e”, “l”, “l”, “o”]",
|
|
1892
|
+
"```",
|
|
1893
|
+
"A write replaces, since there is no receiver to chain from",
|
|
1894
|
+
"```",
|
|
1895
|
+
"; './out.txt' “goodbye”",
|
|
1896
|
+
"# 7",
|
|
1897
|
+
"; './out.txt' | “”",
|
|
1898
|
+
"# “goodbye”",
|
|
1899
|
+
"```",
|
|
1900
|
+
"Path extension is attenuation: a longer reference names a location inside the",
|
|
1901
|
+
"root by construction, and intermediate directories are created on the way",
|
|
1902
|
+
"```",
|
|
1903
|
+
"; './notes/day/1.txt' “deep”",
|
|
1904
|
+
"# 4",
|
|
1905
|
+
"; './notes/day/1.txt' | “”",
|
|
1906
|
+
"# “deep”",
|
|
1907
|
+
"```",
|
|
1908
|
+
"`./`, `/`, and a bare path all name the same location. There is no ambient",
|
|
1909
|
+
"working directory to make them differ, because that would be ambient authority",
|
|
1910
|
+
"```",
|
|
1911
|
+
"; '/out.txt' | “”",
|
|
1912
|
+
"# “goodbye”",
|
|
1913
|
+
"; 'out.txt' | “”",
|
|
1914
|
+
"# “goodbye”",
|
|
1915
|
+
"```",
|
|
1916
|
+
"Evaluating an identifier still performs no access, so an identifier the root",
|
|
1917
|
+
"binding could never reach is still an ordinary printable, decomposable value",
|
|
1918
|
+
"```",
|
|
1919
|
+
"; 'https://theswanfactory.com/hc?v=1'",
|
|
1920
|
+
"# 'https://theswanfactory.com/hc?v=1'",
|
|
1921
|
+
"; 'https://theswanfactory.com/hc'.authority",
|
|
1922
|
+
"# “theswanfactory.com”",
|
|
1923
|
+
"```",
|
|
1924
|
+
"Those components describe the reference the value is rather than contents it",
|
|
1925
|
+
"holds, so they are readable by name and never part of the stream. A doubled read",
|
|
1926
|
+
"is therefore indexed characters, with no identity metadata mixed in",
|
|
1927
|
+
"```",
|
|
1928
|
+
"; './out.txt' .path",
|
|
1929
|
+
"# “./out.txt”",
|
|
1930
|
+
"; './out.txt' && {_}",
|
|
1931
|
+
"# [[.0, “g”], [.1, “o”], [.2, “o”], [.3, “d”], [.4, “b”], [.5, “y”], [.6, “e”]]",
|
|
1932
|
+
"```",
|
|
1933
|
+
"Refusal is a value. A parent reference is refused at normalization, before any",
|
|
1934
|
+
"host call",
|
|
1935
|
+
"```",
|
|
1936
|
+
"; '../escape' “no”",
|
|
1937
|
+
"# $!.resource-parent-escape '../escape'",
|
|
1938
|
+
"; './a/../b' “no”",
|
|
1939
|
+
"# $!.resource-parent-escape './a/../b'",
|
|
1940
|
+
"```",
|
|
1941
|
+
"So is an escape that would reintroduce a separator or a dot segment",
|
|
1942
|
+
"```",
|
|
1943
|
+
"; './%2e%2e/escape' “no”",
|
|
1944
|
+
"# $!.resource-encoded-separator './%2e%2e/escape'",
|
|
1945
|
+
"; './a%2fb' “no”",
|
|
1946
|
+
"# $!.resource-encoded-separator './a%2fb'",
|
|
1947
|
+
"```",
|
|
1948
|
+
"A scheme is dispatched through a handler table, and a scheme with no entry is an",
|
|
1949
|
+
"empty slot, so it fails closed with a nameable refusal rather than reaching the",
|
|
1950
|
+
"network. This harness binds one scheme, so every other one refuses",
|
|
1951
|
+
"```",
|
|
1952
|
+
"; 'https://example.com/x' “no”",
|
|
1953
|
+
"# $!.resource-scheme-unbound 'https://example.com/x'",
|
|
1954
|
+
"; 'jsr:@swanfactory/hclang' “no”",
|
|
1955
|
+
"# $!.resource-scheme-unbound 'jsr:@swanfactory/hclang'",
|
|
1956
|
+
"; 'file:///etc/passwd' | “”",
|
|
1957
|
+
"# $!.resource-scheme-unbound 'file:///etc/passwd'",
|
|
1958
|
+
"```",
|
|
1959
|
+
"The bound one is the clock, which is a grant rather than a literal. Reading it",
|
|
1960
|
+
"answers one instant; writing it is refused, because an observation is not a",
|
|
1961
|
+
"setting; and no other location under the scheme names anything",
|
|
1962
|
+
"```",
|
|
1963
|
+
"; ('clock:now' | []) .0 .> %2000-01-01T00:00:00Z%",
|
|
1964
|
+
"# <>",
|
|
1965
|
+
"; 'clock:now' “2020-01-01”",
|
|
1966
|
+
"# $!.clock-read-only 'clock:now'",
|
|
1967
|
+
"; 'clock:tomorrow' | []",
|
|
1968
|
+
"# [$!.clock-unreadable 'clock:tomorrow']",
|
|
1969
|
+
"```",
|
|
1970
|
+
"Presence of a scheme is the whole discriminator, and the colon is never",
|
|
1971
|
+
"consulted: the same character inside a path is an ordinary path character",
|
|
1972
|
+
"```",
|
|
1973
|
+
"; 'clock:now' .scheme",
|
|
1974
|
+
"# “clock”",
|
|
1975
|
+
"; './a:b.txt' “colon”",
|
|
1976
|
+
"# 5",
|
|
1977
|
+
"; './a:b.txt' | “”",
|
|
1978
|
+
"# “colon”",
|
|
1979
|
+
"```",
|
|
1980
|
+
"A single letter is a legal RFC 3986 scheme, and drive-letter heuristics do not",
|
|
1981
|
+
"belong in the trusted base. RFC 3986 §4.2 already supplies the remedy: `./`",
|
|
1982
|
+
"```",
|
|
1983
|
+
"; 'C:/tmp/x' “no”",
|
|
1984
|
+
"# $!.resource-scheme-unbound 'C:/tmp/x'",
|
|
1985
|
+
"; './C:/tmp/x' “ok”",
|
|
1986
|
+
"# 2",
|
|
1987
|
+
"```",
|
|
1988
|
+
"An absent location is a refusal the iteration collects like any other value, and",
|
|
1989
|
+
"it stays distinguishable from an empty one: absent and empty are different facts,",
|
|
1990
|
+
"and only one of them is a failure",
|
|
1991
|
+
"```",
|
|
1992
|
+
"; './missing.txt' | []",
|
|
1993
|
+
"# [$!.resource-absent './missing.txt']",
|
|
1994
|
+
"; './empty.txt' “”",
|
|
1995
|
+
"# 0",
|
|
1996
|
+
"; './empty.txt' | []",
|
|
1997
|
+
"# []",
|
|
1998
|
+
"; './empty.txt' | “”",
|
|
1999
|
+
"# “”",
|
|
2000
|
+
"```",
|
|
2001
|
+
"The root binding is reachable by name, which is what makes the perimeter",
|
|
2002
|
+
"enumerable rather than ambient. It prints as the reference it denotes and never",
|
|
2003
|
+
"as the host location behind it",
|
|
2004
|
+
"```",
|
|
2005
|
+
"; $$.root",
|
|
2006
|
+
"# '.'",
|
|
2007
|
+
"",
|
|
2008
|
+
].join("\n"),
|
|
2009
|
+
],
|
|
2010
|
+
[
|
|
2011
|
+
"hc/testdoc.hc",
|
|
2012
|
+
[
|
|
2013
|
+
"#!/usr/bin/env hc",
|
|
2014
|
+
"“Hello, Homoiconicity!”",
|
|
2015
|
+
"`docString 1`",
|
|
2016
|
+
"```docString 2```",
|
|
2017
|
+
"`````docString 5 with ``` shorter backticks`````",
|
|
2018
|
+
"```",
|
|
2019
|
+
"docString 3",
|
|
2020
|
+
"one `backtick` span",
|
|
2021
|
+
"two ``backtick`` span",
|
|
2022
|
+
"```",
|
|
2023
|
+
"; `one-backtick document`",
|
|
2024
|
+
"# `one-backtick document`",
|
|
2025
|
+
"; ```three-backtick document with `one` and ``two`` spans```",
|
|
2026
|
+
"# ```three-backtick document with `one` and ``two`` spans```",
|
|
2027
|
+
"; `````five-backtick document with `one` ``two`` ```three``` and ````four```` spans`````",
|
|
2028
|
+
"# `````five-backtick document with `one` ``two`` ```three``` and ````four```` spans`````",
|
|
2029
|
+
"; ``",
|
|
2030
|
+
"# ``",
|
|
2031
|
+
"; ````",
|
|
2032
|
+
"# ````",
|
|
2033
|
+
"; ``````",
|
|
2034
|
+
"# ``````",
|
|
2035
|
+
"## A document publishes its characters without its fences",
|
|
2036
|
+
"; `one-backtick document`.body",
|
|
2037
|
+
"# “one-backtick document”",
|
|
2038
|
+
"; ```body with `one` and ``two`` spans```.body",
|
|
2039
|
+
"# “body with `one` and ``two`` spans”",
|
|
2040
|
+
"; 123",
|
|
2041
|
+
"# 123",
|
|
2042
|
+
"; 1234 # trailing comment",
|
|
2043
|
+
"# 1234",
|
|
2044
|
+
"; # inline comment before # 4321",
|
|
2045
|
+
"# 4321",
|
|
2046
|
+
"; 5678 # inline comment after #",
|
|
2047
|
+
"# 5678",
|
|
2048
|
+
"```",
|
|
2049
|
+
"docString 4",
|
|
2050
|
+
"```",
|
|
2051
|
+
"; 789",
|
|
2052
|
+
"# 789",
|
|
2053
|
+
"; 0xabc",
|
|
2054
|
+
"# 0xabc",
|
|
2055
|
+
"```",
|
|
2056
|
+
"Test closures",
|
|
2057
|
+
"```",
|
|
2058
|
+
"; {}",
|
|
2059
|
+
"# {}",
|
|
2060
|
+
"; {1}",
|
|
2061
|
+
"# { 1 }",
|
|
2062
|
+
"; {_}",
|
|
2063
|
+
"# { _ }",
|
|
2064
|
+
"; { _ }",
|
|
2065
|
+
"# { _ }",
|
|
2066
|
+
"; { _ + 1 }",
|
|
2067
|
+
"# { _ + 1 }",
|
|
2068
|
+
"; { _ + 1 } 2",
|
|
2069
|
+
"# 3",
|
|
2070
|
+
"```",
|
|
2071
|
+
"Test identifiers",
|
|
2072
|
+
"```",
|
|
2073
|
+
"; .a-b 3",
|
|
2074
|
+
"# .a-b 3",
|
|
2075
|
+
"; a-b",
|
|
2076
|
+
"# 3",
|
|
2077
|
+
"```",
|
|
2078
|
+
"Test array literal properties",
|
|
2079
|
+
"```",
|
|
2080
|
+
"; [.a 1; .b 2;].a",
|
|
2081
|
+
"# 1",
|
|
2082
|
+
"```",
|
|
2083
|
+
"Test types",
|
|
2084
|
+
"```",
|
|
2085
|
+
"## Empty schema accepts any value",
|
|
2086
|
+
"; .x <> 42",
|
|
2087
|
+
"# 42",
|
|
2088
|
+
"## Number enumerations",
|
|
2089
|
+
"; .option <1,2,3> 2",
|
|
2090
|
+
"# .option 2",
|
|
2091
|
+
"; @option 3",
|
|
2092
|
+
"# 3",
|
|
2093
|
+
"; @option 4",
|
|
2094
|
+
"# $!.type-error .option <1, 2, 3> 4",
|
|
2095
|
+
"## Single value schema (constant)",
|
|
2096
|
+
"; .const <42> 42",
|
|
2097
|
+
"# .const 42",
|
|
2098
|
+
"; @const 43",
|
|
2099
|
+
"# $!.type-error .const <42> 43",
|
|
2100
|
+
"## Multiple valid assignments",
|
|
2101
|
+
"; .x <1,2> 1",
|
|
2102
|
+
"# 1",
|
|
2103
|
+
"; @x 2",
|
|
2104
|
+
"# 2",
|
|
2105
|
+
"; @x 1",
|
|
2106
|
+
"# 1",
|
|
2107
|
+
"## Original tests",
|
|
2108
|
+
"; <> 1",
|
|
2109
|
+
"# <>",
|
|
2110
|
+
"; <> ()",
|
|
2111
|
+
"# <>",
|
|
2112
|
+
"; .one <1> 1",
|
|
2113
|
+
"# .one 1",
|
|
2114
|
+
"; @one 2",
|
|
2115
|
+
"# $!.type-error .one <1> 2",
|
|
2116
|
+
"## Boolean and first-class type operations",
|
|
2117
|
+
"; ().!",
|
|
2118
|
+
"# <>",
|
|
2119
|
+
"; <>.!",
|
|
2120
|
+
"# ()",
|
|
2121
|
+
"; 1 ~ <>",
|
|
2122
|
+
"# <>",
|
|
2123
|
+
"; 2 ~ ()",
|
|
2124
|
+
"# ()",
|
|
2125
|
+
"; “Q” ~ ~~“”",
|
|
2126
|
+
"# <>",
|
|
2127
|
+
"; “Q” ~ ~~1",
|
|
2128
|
+
"# ()",
|
|
2129
|
+
"## Closure signatures apply defaults, require bare fields, and allow extras",
|
|
2130
|
+
"; .join-name (.first “Jane”, .last) ^ {last “, ” first};",
|
|
2131
|
+
"; join-name (.first “John”, .last “Doe”)",
|
|
2132
|
+
"# “Doe, John”",
|
|
2133
|
+
"; join-name (.middle “Q”, .last “Doe”)",
|
|
2134
|
+
"# “Doe, Jane”",
|
|
2135
|
+
"; join-name (.middle “Q”)",
|
|
2136
|
+
"# $!invalid-argument-list (.middle “Q”, $!missing-required-argument .last;)",
|
|
2137
|
+
"```",
|
|
2138
|
+
"Conditionals",
|
|
2139
|
+
"```",
|
|
2140
|
+
"## Binary truth table for ordinary frames and raw nil: `:` answers a frame itself",
|
|
2141
|
+
"; 1 ? {2 + 2}",
|
|
2142
|
+
"# 4",
|
|
2143
|
+
"; 1 : {2 + 2}",
|
|
2144
|
+
"# 1",
|
|
2145
|
+
"; () ? {2 + 2}",
|
|
2146
|
+
"# ()",
|
|
2147
|
+
"; () : {2 + 2}",
|
|
2148
|
+
"# 4",
|
|
2149
|
+
"## The selected callable may itself return nil",
|
|
2150
|
+
"; 1 ? {()}",
|
|
2151
|
+
"# ()",
|
|
2152
|
+
"; () : {()}",
|
|
2153
|
+
"# ()",
|
|
2154
|
+
"## Dotted comparisons produce Frame.all or Frame.nil predicates",
|
|
2155
|
+
"; 1.> 5 ? {100}",
|
|
2156
|
+
"# ()",
|
|
2157
|
+
"; 1.> 5 : {10}",
|
|
2158
|
+
"# 10",
|
|
2159
|
+
"; 5.> 1 ? {100}",
|
|
2160
|
+
"# 100",
|
|
2161
|
+
"; 5.> 1 : {10}",
|
|
2162
|
+
"# <>",
|
|
2163
|
+
"## Chained conditionals answer the taken branch",
|
|
2164
|
+
"; 1.> 5 ? (2 * 50) : 10",
|
|
2165
|
+
"# 10",
|
|
2166
|
+
"; 5.> 1 ? (2 * 50) : 10",
|
|
2167
|
+
"# 100",
|
|
2168
|
+
"## A taken branch that answers nil falls through to the else branch",
|
|
2169
|
+
"; 5.> 1 ? {()} : {10}",
|
|
2170
|
+
"# 10",
|
|
2171
|
+
"```",
|
|
2172
|
+
"Figures: construct with optional children, observe with Figure answers",
|
|
2173
|
+
"```",
|
|
2174
|
+
"; .A []; .B [A]; .E [A, B]; .B2 [A];",
|
|
2175
|
+
"## Reuse and resemblance are different rungs of the equality ladder",
|
|
2176
|
+
"; [B = B2, B == B2, B === B2]",
|
|
2177
|
+
"# [<>, <>, ()]",
|
|
2178
|
+
"; (E .0) === A",
|
|
2179
|
+
"# <>",
|
|
2180
|
+
"## A plain conditional answers a Figure from either branch",
|
|
2181
|
+
"; .same {((_ .0) === (_ .1)) ? {B} : {A}};",
|
|
2182
|
+
"; same [B, B]",
|
|
2183
|
+
"# [[]]",
|
|
2184
|
+
"; same [B, B2]",
|
|
2185
|
+
"# []",
|
|
2186
|
+
"## Box a branch that answers nil, so it does not fall through",
|
|
2187
|
+
"; .rest {((_ && {(((_ .0) = .0) ? {[()]} : {[[__ .1]]}) .0}) | []) & {_ .0}};",
|
|
2188
|
+
"; rest E",
|
|
2189
|
+
"# [[[]]]",
|
|
2190
|
+
"## Observing a Figure through a plain name does not write onto it",
|
|
2191
|
+
"; E & {.o _; o};",
|
|
2192
|
+
"; E",
|
|
2193
|
+
"# [[], [[]]]",
|
|
2194
|
+
"```",
|
|
2195
|
+
"Quote delimiters",
|
|
2196
|
+
"```",
|
|
2197
|
+
"## Curly quotes nest without an escape character",
|
|
2198
|
+
"; “a “b” c”",
|
|
2199
|
+
"# “a “b” c”",
|
|
2200
|
+
"## The ASCII quote is an input spelling of the same value",
|
|
2201
|
+
'; "ascii"',
|
|
2202
|
+
"# “ascii”",
|
|
2203
|
+
'; ""',
|
|
2204
|
+
"# “”",
|
|
2205
|
+
"## An odd ASCII run selects nesting depth, so shorter runs are content",
|
|
2206
|
+
'; """x "" y"""',
|
|
2207
|
+
'# “x "" y”',
|
|
2208
|
+
"## Single quotes name a resource without authorizing it",
|
|
2209
|
+
"; 'jsr:@swanfactory/hclang'",
|
|
2210
|
+
"# 'jsr:@swanfactory/hclang'",
|
|
2211
|
+
"; 'jsr:@swanfactory/hclang'.scheme",
|
|
2212
|
+
"# “jsr”",
|
|
2213
|
+
"; 'docs/hc.md'.path",
|
|
2214
|
+
"# “docs/hc.md”",
|
|
2215
|
+
"```",
|
|
2216
|
+
"String schemas",
|
|
2217
|
+
"```",
|
|
2218
|
+
'; .color <"red","green","blue"> "red"',
|
|
2219
|
+
"# .color “red”",
|
|
2220
|
+
'; @color "blue"',
|
|
2221
|
+
"# “blue”",
|
|
2222
|
+
'; @color "purple"',
|
|
2223
|
+
"# $!.type-error .color <“red”, “green”, “blue”> “purple”",
|
|
2224
|
+
'; .status <"ok"> "ok"',
|
|
2225
|
+
"# .status “ok”",
|
|
2226
|
+
"```",
|
|
2227
|
+
"HLIR advanced types (aspirational)",
|
|
2228
|
+
"```",
|
|
2229
|
+
"; .x <i32> 42 # Primitive types",
|
|
2230
|
+
"# $!.unimplemented .x 42",
|
|
2231
|
+
"; .mat <tensor<2x3xf32>> [[1,2,3]] # Tensor types",
|
|
2232
|
+
"# $!.unimplemented .mat...",
|
|
2233
|
+
"; .f <(.x <i32>) -> <i32>> {x + 1} # Function signatures",
|
|
2234
|
+
"# $!.unimplemented .f...",
|
|
2235
|
+
"",
|
|
2236
|
+
].join("\n"),
|
|
2237
|
+
],
|
|
2238
|
+
[
|
|
2239
|
+
"hc/time.hc",
|
|
2240
|
+
[
|
|
2241
|
+
"#!/usr/bin/env hc",
|
|
2242
|
+
"```",
|
|
2243
|
+
"Datetime and duration (#369), and the clock as a grant (#370)",
|
|
2244
|
+
"",
|
|
2245
|
+
"These examples are the executable acceptance corpus for the `%…%` family. A time",
|
|
2246
|
+
"literal is inert data: like `'…'` it denotes without authorizing, and parsing one",
|
|
2247
|
+
"performs no observation. Reading the current instant is a separate thing, and it",
|
|
2248
|
+
"is a harness grant.",
|
|
2249
|
+
"",
|
|
2250
|
+
"An instant is offset-bearing, and it renders canonically in UTC, so output",
|
|
2251
|
+
"re-reads as the same value rather than as the spelling that produced it",
|
|
2252
|
+
"```",
|
|
2253
|
+
"; %2026-08-21T00:00:00Z%",
|
|
2254
|
+
"# %2026-08-21T00:00:00Z%",
|
|
2255
|
+
"; %2026-08-21T08:30:00-07:00%",
|
|
2256
|
+
"# %2026-08-21T15:30:00Z%",
|
|
2257
|
+
"; %1970-01-01T00:00:00.5Z%",
|
|
2258
|
+
"# %1970-01-01T00:00:00.5Z%",
|
|
2259
|
+
"```",
|
|
2260
|
+
"A date alone is the start of that UTC day. A day boundary has to be pinned",
|
|
2261
|
+
"somewhere, and UTC is the only choice that is not ambient",
|
|
2262
|
+
"```",
|
|
2263
|
+
"; %2026-08-21%",
|
|
2264
|
+
"# %2026-08-21T00:00:00Z%",
|
|
2265
|
+
"; %2024-02-29%",
|
|
2266
|
+
"# %2024-02-29T00:00:00Z%",
|
|
2267
|
+
"```",
|
|
2268
|
+
"A civil time with no offset is refused rather than guessed. It cannot become an",
|
|
2269
|
+
"instant without tzdata, which is externally mutable data revised by political",
|
|
2270
|
+
"decision, so named-zone conversion is a handler's business and never a literal's",
|
|
2271
|
+
"```",
|
|
2272
|
+
"; %2026-08-21T08:30:00%",
|
|
2273
|
+
"# $!.time-offset-required %2026-08-21T08:30:00%",
|
|
2274
|
+
"```",
|
|
2275
|
+
"A date the calendar does not have is refused, and so is anything else the",
|
|
2276
|
+
"spelling cannot mean",
|
|
2277
|
+
"```",
|
|
2278
|
+
"; %2026-02-29%",
|
|
2279
|
+
"# $!.time-malformed %2026-02-29%",
|
|
2280
|
+
"; %2026-13-01%",
|
|
2281
|
+
"# $!.time-malformed %2026-13-01%",
|
|
2282
|
+
"; %nonsense%",
|
|
2283
|
+
"# $!.time-malformed %nonsense%",
|
|
2284
|
+
"```",
|
|
2285
|
+
"A duration is a peer type, fixed-length, and it also renders canonically",
|
|
2286
|
+
"```",
|
|
2287
|
+
"; %PT1H%",
|
|
2288
|
+
"# %PT1H%",
|
|
2289
|
+
"; %PT90M%",
|
|
2290
|
+
"# %PT1H30M%",
|
|
2291
|
+
"; %P1W%",
|
|
2292
|
+
"# %P7D%",
|
|
2293
|
+
"; %PT0S%",
|
|
2294
|
+
"# %PT0S%",
|
|
2295
|
+
"```",
|
|
2296
|
+
"A calendar quantity is refused, because a year and a month are not",
|
|
2297
|
+
"displacements: admitting them would put calendar rules in the trusted base",
|
|
2298
|
+
"```",
|
|
2299
|
+
"; %P1Y%",
|
|
2300
|
+
"# $!.time-duration-calendar %P1Y%",
|
|
2301
|
+
"; %P1M%",
|
|
2302
|
+
"# $!.time-duration-calendar %P1M%",
|
|
2303
|
+
"; %PT1M%",
|
|
2304
|
+
"# %PT1M%",
|
|
2305
|
+
"```",
|
|
2306
|
+
"The algebra is enforced, and enforced from one dimensional table rather than from",
|
|
2307
|
+
"rules spelled per operator. An instant is a point, a duration is an interval, and",
|
|
2308
|
+
"the difference of two points is the interval between them",
|
|
2309
|
+
"```",
|
|
2310
|
+
"; %2026-08-22T00:00:00Z% - %2026-08-21T00:00:00Z%",
|
|
2311
|
+
"# %P1D%",
|
|
2312
|
+
"; %2026-08-21T00:00:00Z% + %P1D%",
|
|
2313
|
+
"# %2026-08-22T00:00:00Z%",
|
|
2314
|
+
"; %P1D% + %2026-08-21T00:00:00Z%",
|
|
2315
|
+
"# %2026-08-22T00:00:00Z%",
|
|
2316
|
+
"; %PT1H% * 3",
|
|
2317
|
+
"# %PT3H%",
|
|
2318
|
+
"; 2 * %PT30M%",
|
|
2319
|
+
"# %PT1H%",
|
|
2320
|
+
"```",
|
|
2321
|
+
"The fourth row is a type error, and it is a value like any other refusal",
|
|
2322
|
+
"```",
|
|
2323
|
+
"; %2026-08-21T00:00:00Z% + %2026-08-21T00:00:00Z%",
|
|
2324
|
+
"# $!.numeric-domain + FrameDateTime FrameDateTime",
|
|
2325
|
+
"; %2026-08-21% * 2",
|
|
2326
|
+
"# $!.numeric-domain * FrameDateTime FrameCount",
|
|
2327
|
+
"; %PT1H% + 1",
|
|
2328
|
+
"# $!.numeric-domain + FrameDuration FrameCount",
|
|
2329
|
+
"; 1 + %PT1H%",
|
|
2330
|
+
"# $!.numeric-domain + FrameCount FrameDuration",
|
|
2331
|
+
"```",
|
|
2332
|
+
"Division follows the same table: an interval over a scalar is an interval, and an",
|
|
2333
|
+
"interval over an interval is the plain number relating them",
|
|
2334
|
+
"```",
|
|
2335
|
+
"; %PT1H% / 2",
|
|
2336
|
+
"# %PT30M%",
|
|
2337
|
+
"; %P1D% / %PT1H%",
|
|
2338
|
+
"# 24",
|
|
2339
|
+
"; %PT1H% / %P1D%",
|
|
2340
|
+
"# 1/24",
|
|
2341
|
+
"```",
|
|
2342
|
+
"Arithmetic is exact, so a scaling that would not land on a whole nanosecond is",
|
|
2343
|
+
"refused rather than rounded into place",
|
|
2344
|
+
"```",
|
|
2345
|
+
"; %PT1H% * 1.5",
|
|
2346
|
+
"# %PT1H30M%",
|
|
2347
|
+
"; %PT1S% / 3",
|
|
2348
|
+
"# $!.time-inexact / FrameDuration FrameCount",
|
|
2349
|
+
"; (%PT1S% * 1000000000) / 1000000000",
|
|
2350
|
+
"# %PT1S%",
|
|
2351
|
+
"```",
|
|
2352
|
+
"Peers of one kind order, and the two kinds do not order against each other",
|
|
2353
|
+
"```",
|
|
2354
|
+
"; %PT1H%.< %PT2H%",
|
|
2355
|
+
"# <>",
|
|
2356
|
+
"; %2026-08-21%.> %2026-08-20%",
|
|
2357
|
+
"# <>",
|
|
2358
|
+
"; %2026-08-21T15:30:00Z% = %2026-08-21T08:30:00-07:00%",
|
|
2359
|
+
"# <>",
|
|
2360
|
+
"; %PT1H%.< %2026-08-21%",
|
|
2361
|
+
"# $!.numeric-domain < FrameDuration FrameDateTime",
|
|
2362
|
+
"```",
|
|
2363
|
+
'`%%` is Modulo and keeps the doubled spelling. a03 settled `"` against `"""` with',
|
|
2364
|
+
"run-length parity, but the cases are not analogous: the doubled quote was an",
|
|
2365
|
+
"unused spelling, while this one is an operator with behavior. An empty time",
|
|
2366
|
+
"literal would name nothing, so the family hands `%%` back rather than taking it",
|
|
2367
|
+
"```",
|
|
2368
|
+
"; 9 %% 4",
|
|
2369
|
+
"# 1",
|
|
2370
|
+
"; 3.%%2",
|
|
2371
|
+
"# 1",
|
|
2372
|
+
"```",
|
|
2373
|
+
"`now` is an observation, so it is not ambient and there is no bare name for it.",
|
|
2374
|
+
"The clock is a handler entry, and this harness installed the real one: what is",
|
|
2375
|
+
"deterministic about a real clock is that its reading is an instant already past",
|
|
2376
|
+
"```",
|
|
2377
|
+
"; $$.now",
|
|
2378
|
+
"# $!.name-missing $$.now",
|
|
2379
|
+
"; ('clock:now' | []) .0 .> %2000-01-01T00:00:00Z%",
|
|
2380
|
+
"# <>",
|
|
2381
|
+
"; (('clock:now' | []) .0 - %2000-01-01T00:00:00Z%) .> %P1D%",
|
|
2382
|
+
"# <>",
|
|
2383
|
+
"```",
|
|
2384
|
+
"The same source is byte-identical under a frozen or scripted clock, where the",
|
|
2385
|
+
"reading is pinned; only the installed entry decides what it answers. A program",
|
|
2386
|
+
"that is refused gets no reading either way, and the refusal is an ordinary value",
|
|
2387
|
+
"rather than something that raises",
|
|
2388
|
+
"```",
|
|
2389
|
+
"; 'clock:now' “2020-01-01”",
|
|
2390
|
+
"# $!.clock-read-only 'clock:now'",
|
|
2391
|
+
"; 'clock:yesterday' | []",
|
|
2392
|
+
"# [$!.clock-unreadable 'clock:yesterday']",
|
|
2393
|
+
"```",
|
|
2394
|
+
"Canonical rendering is the contract, so arithmetic that would leave the range a",
|
|
2395
|
+
"literal accepts refuses instead of answering a spelling the reader would reject",
|
|
2396
|
+
"```",
|
|
2397
|
+
"; %999999-12-30T00:00:00Z% + %P1D%",
|
|
2398
|
+
"# %+999999-12-31T00:00:00Z%",
|
|
2399
|
+
"; %999999-12-31T00:00:00Z% + %P1D%",
|
|
2400
|
+
"# $!.time-range + FrameDateTime FrameDuration",
|
|
2401
|
+
"```",
|
|
2402
|
+
"Nothing here is whitespace-sensitive. A time literal opens beside an operator",
|
|
2403
|
+
"exactly as it does after a space, because `%` is the family's delimiter and not an",
|
|
2404
|
+
"operator's continuation",
|
|
2405
|
+
"```",
|
|
2406
|
+
"; 2*%PT30M%",
|
|
2407
|
+
"# %PT1H%",
|
|
2408
|
+
"; %PT1H%-%PT30M%",
|
|
2409
|
+
"# %PT30M%",
|
|
2410
|
+
"; -%PT1H%",
|
|
2411
|
+
"# %-PT1H%",
|
|
2412
|
+
"",
|
|
2413
|
+
].join("\n"),
|
|
2414
|
+
],
|
|
2415
|
+
[
|
|
2416
|
+
"hc/units.hc",
|
|
2417
|
+
[
|
|
2418
|
+
"#!/usr/bin/env hc",
|
|
2419
|
+
"```",
|
|
2420
|
+
"Units of measure (#362)",
|
|
2421
|
+
"",
|
|
2422
|
+
"These examples are the executable acceptance corpus for the units MVP. An",
|
|
2423
|
+
"alphabetic property on an exact decimal builds an inert typed number: it renders",
|
|
2424
|
+
"as written, compares structurally, and refuses every arithmetic operation.",
|
|
2425
|
+
"",
|
|
2426
|
+
"Syntax",
|
|
2427
|
+
"```",
|
|
2428
|
+
"; 9.8.m",
|
|
2429
|
+
"# 9.8.m",
|
|
2430
|
+
"; 0.10.USD",
|
|
2431
|
+
"# 0.10.USD",
|
|
2432
|
+
"; 9.8.metres",
|
|
2433
|
+
"# 9.8.metres",
|
|
2434
|
+
"; 9.8.M",
|
|
2435
|
+
"# 9.8.M",
|
|
2436
|
+
"```",
|
|
2437
|
+
"A unit segment may carry an integer exponent, and further segments compose",
|
|
2438
|
+
"```",
|
|
2439
|
+
"; 9.8.m2",
|
|
2440
|
+
"# 9.8.m2",
|
|
2441
|
+
"; 9.8.m.s-1",
|
|
2442
|
+
"# 9.8.m.s-1",
|
|
2443
|
+
"; 9.8.kg.m.s-2",
|
|
2444
|
+
"# 9.8.kg.m.s-2",
|
|
2445
|
+
"; 9.8.m.s",
|
|
2446
|
+
"# 9.8.m.s",
|
|
2447
|
+
"```",
|
|
2448
|
+
"The equality ladder: a unit is part of the value, and `==` also compares the",
|
|
2449
|
+
"magnitude's rung",
|
|
2450
|
+
"```",
|
|
2451
|
+
"; 9.8.m = 9.8.m",
|
|
2452
|
+
"# <>",
|
|
2453
|
+
"; 9.80.m = 9.8.m",
|
|
2454
|
+
"# <>",
|
|
2455
|
+
"; 9.8.m == 9.8.m",
|
|
2456
|
+
"# <>",
|
|
2457
|
+
"; 9.80.m == 9.8.m",
|
|
2458
|
+
"# <>",
|
|
2459
|
+
"; 3.m == 3.0.m",
|
|
2460
|
+
"# ()",
|
|
2461
|
+
"; 9.8.m = 9.8.kg",
|
|
2462
|
+
"# ()",
|
|
2463
|
+
"; 9.8.m = 9.8",
|
|
2464
|
+
"# ()",
|
|
2465
|
+
"```",
|
|
2466
|
+
"`===` asks for the same frame, and an atom owns no identity, so it is `==`:",
|
|
2467
|
+
"different units are never the same (#358)",
|
|
2468
|
+
"```",
|
|
2469
|
+
"; 9.8.m === 9.8.kg",
|
|
2470
|
+
"# ()",
|
|
2471
|
+
"```",
|
|
2472
|
+
"Equality is spelling, not dimension: no segment is reordered, no exponent folded",
|
|
2473
|
+
"```",
|
|
2474
|
+
"; 9.8.m.s-1 = 9.8.m.s-1",
|
|
2475
|
+
"# <>",
|
|
2476
|
+
"; 9.8.m.s-1 = 9.8.s-1.m",
|
|
2477
|
+
"# ()",
|
|
2478
|
+
"; 9.8.m2 = 9.8.m.m",
|
|
2479
|
+
"# ()",
|
|
2480
|
+
"```",
|
|
2481
|
+
"Composition refuses, including same-unit",
|
|
2482
|
+
"```",
|
|
2483
|
+
"; 9.8.m + 1.2.m",
|
|
2484
|
+
"# $!.numeric-domain + FrameTypedNumber FrameTypedNumber",
|
|
2485
|
+
"; 9.8.m - 1.2.m",
|
|
2486
|
+
"# $!.numeric-domain - FrameTypedNumber FrameTypedNumber",
|
|
2487
|
+
"; 9.8.m.s-1 + 1.0.m.s-1",
|
|
2488
|
+
"# $!.numeric-domain + FrameTypedNumber FrameTypedNumber",
|
|
2489
|
+
"; 9.8.m + 1",
|
|
2490
|
+
"# $!.numeric-domain + FrameTypedNumber FrameCount",
|
|
2491
|
+
"; 1 + 9.8.m",
|
|
2492
|
+
"# $!.numeric-domain + FrameCount FrameTypedNumber",
|
|
2493
|
+
"; 9.8.m 2",
|
|
2494
|
+
"# $!.numeric-domain * FrameTypedNumber FrameCount",
|
|
2495
|
+
"; 9.8.m / 2",
|
|
2496
|
+
"# $!.numeric-domain / FrameTypedNumber FrameCount",
|
|
2497
|
+
"; 9.8.m %% 2",
|
|
2498
|
+
"# $!.numeric-domain %% FrameTypedNumber FrameCount",
|
|
2499
|
+
"; 9.8.m ** 2",
|
|
2500
|
+
"# $!.numeric-domain ** FrameTypedNumber FrameCount",
|
|
2501
|
+
"; 9.8.m.< 10.2.m",
|
|
2502
|
+
"# $!.numeric-domain < FrameTypedNumber FrameTypedNumber",
|
|
2503
|
+
"; 9.8.m“Hi”",
|
|
2504
|
+
"# $!.repetition-domain FrameTypedNumber",
|
|
2505
|
+
"; -(9.8.m)",
|
|
2506
|
+
"# $!.numeric-domain unary- FrameTypedNumber",
|
|
2507
|
+
"```",
|
|
2508
|
+
"Boundaries that do not move",
|
|
2509
|
+
"```",
|
|
2510
|
+
"; 9.8.5",
|
|
2511
|
+
"# 9.8.5",
|
|
2512
|
+
"; 100.kg",
|
|
2513
|
+
"# $!.name-missing “$:FrameCount...",
|
|
2514
|
+
"; (1 / 3).m",
|
|
2515
|
+
"# $!.name-missing “$:FrameRational...",
|
|
2516
|
+
"; (1 / 2.0).m",
|
|
2517
|
+
"# $!.name-missing “$:FrameNumber...",
|
|
2518
|
+
"; 1.408.055.m",
|
|
2519
|
+
"# $!.name-missing “$:FrameSequence...",
|
|
2520
|
+
"; 9.8.m.5",
|
|
2521
|
+
"# $!.name-missing “$:FrameTypedNumber...",
|
|
2522
|
+
"; 9.8.m.2s",
|
|
2523
|
+
"# $!.name-missing “$:FrameTypedNumber...",
|
|
2524
|
+
"; 9.8.m.s_1",
|
|
2525
|
+
"# $!.name-missing “$:FrameTypedNumber...",
|
|
2526
|
+
"; -9.8.m",
|
|
2527
|
+
"# $!.numeric-domain property FrameDecimal",
|
|
2528
|
+
"",
|
|
2529
|
+
].join("\n"),
|
|
2530
|
+
],
|
|
2531
|
+
[
|
|
2532
|
+
"hc/white-paper-core.hc",
|
|
2533
|
+
[
|
|
2534
|
+
"; {} [“Life, ” “The Universe, ” “Everything.”]",
|
|
2535
|
+
"# (“Life, The Universe, Everything.”)",
|
|
2536
|
+
"; .x (6 * 7)",
|
|
2537
|
+
"# .x 42",
|
|
2538
|
+
"; x",
|
|
2539
|
+
"# 42",
|
|
2540
|
+
"; .y 7",
|
|
2541
|
+
"# .y 7",
|
|
2542
|
+
"; [.x 11; @y 3;].x",
|
|
2543
|
+
"# 11",
|
|
2544
|
+
"; x",
|
|
2545
|
+
"# 42",
|
|
2546
|
+
"; y",
|
|
2547
|
+
"# 3",
|
|
2548
|
+
"; .base_ [.key 42;]",
|
|
2549
|
+
"# .base_ [.key 42;]",
|
|
2550
|
+
"; base_ .key",
|
|
2551
|
+
"# 42",
|
|
2552
|
+
"; {.key 113} base_",
|
|
2553
|
+
"# 113",
|
|
2554
|
+
"; base_ .key",
|
|
2555
|
+
"# 113",
|
|
2556
|
+
"; .fixed [.key 42;];",
|
|
2557
|
+
"; {.key 113} fixed",
|
|
2558
|
+
"# .key 113",
|
|
2559
|
+
"; fixed .key",
|
|
2560
|
+
"# 42",
|
|
2561
|
+
"; [.a 1; .b 2;].c",
|
|
2562
|
+
"# $!.name-missing “...",
|
|
2563
|
+
"; .k 7",
|
|
2564
|
+
"# .k 7",
|
|
2565
|
+
"; [10] & { _^.k }",
|
|
2566
|
+
"# [7]",
|
|
2567
|
+
"; [10, 20, 30] && { _ .0 }",
|
|
2568
|
+
"# [.0, .1, .2]",
|
|
2569
|
+
"; [1, 2, 3] | 1",
|
|
2570
|
+
"# 6",
|
|
2571
|
+
"",
|
|
2572
|
+
].join("\n"),
|
|
2573
|
+
],
|
|
2574
|
+
[
|
|
2575
|
+
"hc/white-paper.hc",
|
|
2576
|
+
[
|
|
2577
|
+
"#!/usr/bin/env hc",
|
|
2578
|
+
"```",
|
|
2579
|
+
"Title : Homoiconic C",
|
|
2580
|
+
"Subtitle : Programming without a Language",
|
|
2581
|
+
"",
|
|
2582
|
+
"HideAuthor : Ernest N. Prabhakar",
|
|
2583
|
+
"HideAffiliation : The Swan Factory, Inc.",
|
|
2584
|
+
"HideEmail : ernest.prabhakar@gmail.com",
|
|
2585
|
+
"",
|
|
2586
|
+
"Bib style : plainnat",
|
|
2587
|
+
"Bibliography : hc-refs.bib",
|
|
2588
|
+
"Logo : True",
|
|
2589
|
+
"Package : amsmath",
|
|
2590
|
+
"Doc class : [preprint]{acmart}",
|
|
2591
|
+
"",
|
|
2592
|
+
"Colorizer : ruby",
|
|
2593
|
+
"~Pre,~Code : language=ruby",
|
|
2594
|
+
".pre-indented : language=ruby",
|
|
2595
|
+
"",
|
|
2596
|
+
"[TITLE]",
|
|
2597
|
+
"",
|
|
2598
|
+
"~ Abstract",
|
|
2599
|
+
"",
|
|
2600
|
+
"Modern programming is dominated by languages derived from C[@CLang] and",
|
|
2601
|
+
"the UNIX shell[@UNIXShell], characterized by complicated syntax and",
|
|
2602
|
+
"sophisticated parsers. Minimalist languages such as Forth[@Forth],",
|
|
2603
|
+
"Scheme[@Scheme] and Self[@Self] are no longer taken seriously[^lua-fn],",
|
|
2604
|
+
"presumably because they are felt to lack sufficiently readable _syntax_",
|
|
2605
|
+
"and powerful enough _semantics_.",
|
|
2606
|
+
"",
|
|
2607
|
+
"In this paper we introduce a novel data format called **Homoiconic C**",
|
|
2608
|
+
'("HC") that we claim expresses a safe superset of C-like computations,',
|
|
2609
|
+
"yet is even easier to read than existing scripting languages. The key is",
|
|
2610
|
+
"a novel data structure and computational model we call _Frames_, designed",
|
|
2611
|
+
"to replace and improve upon the s-expressions and metacircular evaluation",
|
|
2612
|
+
"model of Lisp[@Lisp]. Frames act as a universal monad[^monad], with the",
|
|
2613
|
+
"result that Homoiconic C is simply conventions for creating and",
|
|
2614
|
+
"evaluating Frames.",
|
|
2615
|
+
"",
|
|
2616
|
+
"In this paper we will describe the complete syntax of HC, including three",
|
|
2617
|
+
"primitives, aggregates, and predefined operators; as a",
|
|
2618
|
+
"modeless data format, there are no keywords, reserved words, or hardly any",
|
|
2619
|
+
"grammar. Next we discuss the robust data protection semantics inspired by",
|
|
2620
|
+
"BitC[@BitC], which allow us the efficiency of C's memory",
|
|
2621
|
+
"model without any of the downsides. Finally, we provide examples of how",
|
|
2622
|
+
"these primitives allow us to easily represent other data formats and",
|
|
2623
|
+
"Object-Oriented programming.",
|
|
2624
|
+
"",
|
|
2625
|
+
"We are currently developing the first implementation of HC as a",
|
|
2626
|
+
"TypeScript[@TypeScript] interpreter. It can be found on GitHub[@Cite]",
|
|
2627
|
+
"under the MIT Open Source license.",
|
|
2628
|
+
"",
|
|
2629
|
+
"~",
|
|
2630
|
+
"[^lua-fn]: The only minimalist language still in active use appears to be",
|
|
2631
|
+
" Lua[@Lua], though even that is relegated to niche applications.",
|
|
2632
|
+
"",
|
|
2633
|
+
"[^monad]: Not just the mathematical term for an object closed under all",
|
|
2634
|
+
" operations, but Liebniz's original idea of a single universal",
|
|
2635
|
+
" building-block[@Liebniz].",
|
|
2636
|
+
"",
|
|
2637
|
+
"",
|
|
2638
|
+
"# Introduction { #sec-intro }",
|
|
2639
|
+
"",
|
|
2640
|
+
"Homoiconic C is a data format for computation. It is designed to be a",
|
|
2641
|
+
"simple yet powerful alternative to both traditional programming languages",
|
|
2642
|
+
"and existing data formats.",
|
|
2643
|
+
"",
|
|
2644
|
+
"## A Brief History of Programming Languages",
|
|
2645
|
+
"",
|
|
2646
|
+
"Early high-level languages (e.g., FORTRAN[@Cite], COBOL[@Cite],",
|
|
2647
|
+
"BASIC[@Cite], ALGOL[@Cite]) were strongly influenced by mathematics and",
|
|
2648
|
+
"artificial intelligence[@Cite], leading to sophisticated precedence rules",
|
|
2649
|
+
"and complicated syntax. The primary alternative was Lisp[@Lisp;], defined",
|
|
2650
|
+
"-- at least in theory -- by a single data structure (the list) and a",
|
|
2651
|
+
"single rule (metacircular evaluation).",
|
|
2652
|
+
"",
|
|
2653
|
+
"Lisp was not as efficient as, say, Fortran, but it was much more elegant",
|
|
2654
|
+
"and powerful. The common assumption was that eventually computers would",
|
|
2655
|
+
"become powerful enough that Lisp's inefficiencies would no longer matter.",
|
|
2656
|
+
"Sadly, the failure of hardware-optimized Lisp machines[@Cite] marked the",
|
|
2657
|
+
"death of that dream.",
|
|
2658
|
+
"",
|
|
2659
|
+
"## Then Came C",
|
|
2660
|
+
"",
|
|
2661
|
+
"Into that void stepped the C programming language[@CLang]. C was derived",
|
|
2662
|
+
"from ALGOL, but borrowed (some would say butchered[@Cite]) several",
|
|
2663
|
+
"powerful ideas from Lisp, such as macros[@Cite] and function",
|
|
2664
|
+
"pointers[@Cite]. In addition, the C memory model[@Cite] mapped well onto",
|
|
2665
|
+
"modern processor architectures, enabling remarkably good performance. It",
|
|
2666
|
+
"also benefited from:",
|
|
2667
|
+
"",
|
|
2668
|
+
"* A relatively simple and easy to read syntax",
|
|
2669
|
+
"* Association with the UNIX operating system",
|
|
2670
|
+
"* Self-sustaining[@Cite], open source compilers",
|
|
2671
|
+
"",
|
|
2672
|
+
"This led to C (along with its direct descendants, C++[@Cite] and",
|
|
2673
|
+
"Objective-C[@Cite]) completely dominating the field for systems",
|
|
2674
|
+
"programming; a situation which continues today, almost fifty years later.",
|
|
2675
|
+
"This led to the C syntax (with some borrowing from its sister language,",
|
|
2676
|
+
"the UNIX shell) becoming the baseline for virtually every mass-market",
|
|
2677
|
+
"language in use today[@Cite].",
|
|
2678
|
+
"",
|
|
2679
|
+
"This success was not entirely a good thing. C's memory model and type",
|
|
2680
|
+
"system optimized for efficiency at the cost of safety, leading to",
|
|
2681
|
+
"innumerable programming errors and security holes that still plague us",
|
|
2682
|
+
"today [@Cite]. C's syntax and macros -- a breath of fresh air",
|
|
2683
|
+
"when they first came out -- feel clunky and dated in a world of scripting",
|
|
2684
|
+
"languages and functional programming, to the point where it is rarely",
|
|
2685
|
+
"taught to beginning programmers anymore.",
|
|
2686
|
+
"",
|
|
2687
|
+
"## Framing A New Hope { #sec-frames }",
|
|
2688
|
+
"",
|
|
2689
|
+
"In the last decade, we have seen renewed innovation in systems",
|
|
2690
|
+
"programming, leading to languages such as Rust[@Cite], Go[@Cite], and",
|
|
2691
|
+
"Swift [@Cite]. These are enough better and different than C that they",
|
|
2692
|
+
"have carved out their own niches (especially with the help of powerful",
|
|
2693
|
+
"patrons). However, they don't seem to have the factor-of-ten improvement",
|
|
2694
|
+
"necessary to displace or replace C, the way C did to assembly language.",
|
|
2695
|
+
"",
|
|
2696
|
+
"Homoiconic C aspires to reach that goal by marrying the best aspects of",
|
|
2697
|
+
"C's syntax and memory model with the values of rigor and simplicity that",
|
|
2698
|
+
"characterized Lisp. The central innovation is a novel data structure we",
|
|
2699
|
+
"call a **frame**. Frames are simultaneously:",
|
|
2700
|
+
"",
|
|
2701
|
+
"* Callable (like functions)",
|
|
2702
|
+
"* Enumerable (like arrays)",
|
|
2703
|
+
"* Associative (like structs)",
|
|
2704
|
+
"* Inherited (like classes)",
|
|
2705
|
+
"",
|
|
2706
|
+
"Our premise is that the multitude of structures found in programming",
|
|
2707
|
+
"languages boil down to just these four attributes. By encoding",
|
|
2708
|
+
"them in a single object, we hope to dramatically simplify both the structure",
|
|
2709
|
+
"of the language and the process of programming.",
|
|
2710
|
+
"",
|
|
2711
|
+
"HC also incorporates:",
|
|
2712
|
+
"",
|
|
2713
|
+
"* Homoiconicity, from Lisp : Frames are both code and data, making it",
|
|
2714
|
+
" trivial to manipulate code via higher-level abstractions.",
|
|
2715
|
+
"* Dataflow, from the UNIX Shell",
|
|
2716
|
+
" : Iteration and Input/Output are designed for simple pipeline-style composition.",
|
|
2717
|
+
"* Effect Typing, from BitC[@Cite] : By carefully annotating function",
|
|
2718
|
+
" boundaries for both _constancy_ and _immutability_, we can safely alias",
|
|
2719
|
+
" data structures to get C-like performance while preserving the security",
|
|
2720
|
+
" of managed code.",
|
|
2721
|
+
"* Lexical Scoping, from Scheme[@Cite] : Everything inherits its current",
|
|
2722
|
+
" scope (like closures). In addition, evaluation of closures causes the",
|
|
2723
|
+
" result to inherit their scope, allowing them to be used as object",
|
|
2724
|
+
" factories.",
|
|
2725
|
+
"",
|
|
2726
|
+
"",
|
|
2727
|
+
"## About This Document",
|
|
2728
|
+
"",
|
|
2729
|
+
"In the remainder of this document, we will cover:",
|
|
2730
|
+
"",
|
|
2731
|
+
"* The syntax, operators, and access control that define the language",
|
|
2732
|
+
"* Examples of using Homoiconic C to model object-oriented programming and HTML",
|
|
2733
|
+
"* The current status and possible future directions",
|
|
2734
|
+
"* Conclusions and comparisons to related work",
|
|
2735
|
+
"",
|
|
2736
|
+
"",
|
|
2737
|
+
"",
|
|
2738
|
+
"# Language Definition",
|
|
2739
|
+
"",
|
|
2740
|
+
"",
|
|
2741
|
+
"## Syntax",
|
|
2742
|
+
"",
|
|
2743
|
+
"The core principle of Homoiconic C syntax is _isomorphism_: every",
|
|
2744
|
+
"syntactic construct refers to exactly one semantic concept. Put another",
|
|
2745
|
+
"way, it is modeless: syntax characters do not mean different things in different",
|
|
2746
|
+
"places. This enables vastly simpler parsers and a much shallower learning",
|
|
2747
|
+
"curve.",
|
|
2748
|
+
"",
|
|
2749
|
+
"Like traditional data formats, HC is build around _literals_ and the",
|
|
2750
|
+
"_terminals_ that separate and organize them. HC simply extends that with",
|
|
2751
|
+
"_identifiers_, and a single grammatic construct, the _expression_. HC",
|
|
2752
|
+
"documents that only use literals and terminals are called _data",
|
|
2753
|
+
"programs_, or sometimes just _congrams_.",
|
|
2754
|
+
"",
|
|
2755
|
+
"### Expressions",
|
|
2756
|
+
"",
|
|
2757
|
+
"Expressions are simply zero or more frames evaluated within the current",
|
|
2758
|
+
"context, then applied left to right (left fold [@LeftFold]). We refer to",
|
|
2759
|
+
"this as the _elliptical evaluator_, in homage to Lisp's metacircular",
|
|
2760
|
+
"evaluator.",
|
|
2761
|
+
"",
|
|
2762
|
+
"```",
|
|
2763
|
+
" frame0 frame1 frame2 ...",
|
|
2764
|
+
"```",
|
|
2765
|
+
"Specifically:",
|
|
2766
|
+
"",
|
|
2767
|
+
"1. `frame0` is evaluated to `value0` (also a frame)",
|
|
2768
|
+
"2. `frame1` is evaluated to `value1`",
|
|
2769
|
+
"3. `value0` is called with the argument `value1`, producing `result1`",
|
|
2770
|
+
"4. `result1` is called with `value2` producing `result2`",
|
|
2771
|
+
"5. The final `result` is thus the value of the evaluated expression",
|
|
2772
|
+
"",
|
|
2773
|
+
"The HC read-eval-print loop (REPL) uses ';' for the input prompt and '#' for the",
|
|
2774
|
+
"output prompt:",
|
|
2775
|
+
"",
|
|
2776
|
+
"```",
|
|
2777
|
+
"; .literal",
|
|
2778
|
+
"# .literal",
|
|
2779
|
+
"```",
|
|
2780
|
+
"",
|
|
2781
|
+
"That's pretty much all there is. There are no special forms, keywords,",
|
|
2782
|
+
"precedence rules, or other grammatic constructs. While we realize those",
|
|
2783
|
+
"may provide some efficiency gains for experienced programmers, we do not",
|
|
2784
|
+
"believe they are worth of cost of complicating the implementation and",
|
|
2785
|
+
"increasing the learning curve for new programmers. In particularly,",
|
|
2786
|
+
"we assert they are not actually necessary for a fully-functional programming system.",
|
|
2787
|
+
"",
|
|
2788
|
+
"### Literals",
|
|
2789
|
+
"",
|
|
2790
|
+
"Like any good data format, HC has a rich set of literals, described in",
|
|
2791
|
+
"Table [#sec-table-literals].",
|
|
2792
|
+
"",
|
|
2793
|
+
'~ TableFigure { #sec-table-literals; caption: "Literals Syntax" }',
|
|
2794
|
+
"",
|
|
2795
|
+
"+----------|---------------+----------|---------------+--------------------+",
|
|
2796
|
+
"| Integer || Non-Integer || Quote |",
|
|
2797
|
+
"+----------|---------------+----------|---------------+--------------------+",
|
|
2798
|
+
"| 0b010 | _binary_ |1/3| _rational_| “_string_” |",
|
|
2799
|
+
"| 0o1777 | _octal_ |123.456| _float_ | # _comment_ # |",
|
|
2800
|
+
"| 1234 | _decimal_ |9.8.m| _quantity_ | \\\\_length_\\\\_blob_ |",
|
|
2801
|
+
"| 0xCAFE | _hexadecimal_ |1.408.055| _sequence_ | '_resource_' |",
|
|
2802
|
+
"| 0@Base64 | _Base64_ |+1.408.555.1212| _phone_ | |",
|
|
2803
|
+
"+----------|---------------+----------|---------------+--------------------+",
|
|
2804
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
2805
|
+
" tbody-tr-even-background-color:Floralwhite; }",
|
|
2806
|
+
"~",
|
|
2807
|
+
"",
|
|
2808
|
+
"The most significant departure from traditional syntax is the use of",
|
|
2809
|
+
"matching smart quotes, which enables nesting and all but eliminates the",
|
|
2810
|
+
"need for escape sequences. Balanced interior quotes are ordinary content,",
|
|
2811
|
+
"so a quotation inside a quotation needs no escape character:",
|
|
2812
|
+
"```",
|
|
2813
|
+
"; “nesting “quotes” inside quotes”",
|
|
2814
|
+
"# “nesting “quotes” inside quotes”",
|
|
2815
|
+
"```",
|
|
2816
|
+
"A delimiter earns its keep only when it changes what the delimited text",
|
|
2817
|
+
"_denotes_. The ASCII double quote therefore introduces no second string",
|
|
2818
|
+
"type: it is simply the input spelling of the curly pair, and its output is",
|
|
2819
|
+
"always canonical. Run length selects nesting depth rather than type, using",
|
|
2820
|
+
"the same odd/even rule as document fences, so an even run is the empty",
|
|
2821
|
+
"string and a longer odd run permits interior runs as content:",
|
|
2822
|
+
"```",
|
|
2823
|
+
'; "ASCII quotes canonicalize"',
|
|
2824
|
+
"# “ASCII quotes canonicalize”",
|
|
2825
|
+
'; ""',
|
|
2826
|
+
"# “”",
|
|
2827
|
+
'; """interior " and "" runs are content"""',
|
|
2828
|
+
'# “interior " and "" runs are content”',
|
|
2829
|
+
"```",
|
|
2830
|
+
"The single quote takes the one genuinely vacant slot: naming something",
|
|
2831
|
+
"that is _not_ in the program. A resource identifier is an inert,",
|
|
2832
|
+
"structured URI reference. It reaches no network, filesystem, or registry",
|
|
2833
|
+
"when it is lexed or evaluated, so source text can name a resource without",
|
|
2834
|
+
"being able to authorize it; resolution requires a resource frame supplied",
|
|
2835
|
+
"by the invocation context.",
|
|
2836
|
+
"```",
|
|
2837
|
+
"; 'https://theswanfactory.com/hc?v=1'",
|
|
2838
|
+
"# 'https://theswanfactory.com/hc?v=1'",
|
|
2839
|
+
"; 'jsr:@swanfactory/hclang'.scheme",
|
|
2840
|
+
"# “jsr”",
|
|
2841
|
+
"; 'https://theswanfactory.com/hc'.authority",
|
|
2842
|
+
"# “theswanfactory.com”",
|
|
2843
|
+
"```",
|
|
2844
|
+
"Because every external identity is lexically marked, a program's entire",
|
|
2845
|
+
"external surface can be enumerated without evaluating it.",
|
|
2846
|
+
"",
|
|
2847
|
+
"In addition, as part of HC's quest to be a universal data format, it",
|
|
2848
|
+
"natively supports:",
|
|
2849
|
+
"",
|
|
2850
|
+
"* Base64 numbers",
|
|
2851
|
+
"* arbitrary-length binary and hexadecimal bitstreams",
|
|
2852
|
+
"* net-string style _blobs_",
|
|
2853
|
+
"* a dedicated _time_ type and literal (to avoid overloading integers)",
|
|
2854
|
+
"",
|
|
2855
|
+
"By definition, literals evaluate to themselves:",
|
|
2856
|
+
"```",
|
|
2857
|
+
"; “Hello, Quine!”",
|
|
2858
|
+
"# “Hello, Quine!”",
|
|
2859
|
+
"```",
|
|
2860
|
+
"This is true even at the file level. A data program consistent entirely",
|
|
2861
|
+
"of terminals and literals simply evaluates to (and prints out) itself, or",
|
|
2862
|
+
'"[quines](https://en.wikipedia.org/wiki/Quine_%28computing%29)."',
|
|
2863
|
+
"",
|
|
2864
|
+
"Because literals are also frames, and thus both code and data, they can",
|
|
2865
|
+
"be called like functions. Strings, for example, stringify and concatenate",
|
|
2866
|
+
"their argument.",
|
|
2867
|
+
"```",
|
|
2868
|
+
"; “Hello, ” “Homoiconicity!”",
|
|
2869
|
+
"# “Hello, Homoiconicity!”",
|
|
2870
|
+
"; “The Answer” “: ” 42",
|
|
2871
|
+
"# “The Answer: 42”",
|
|
2872
|
+
"```",
|
|
2873
|
+
"",
|
|
2874
|
+
"Similarly, numbers replicate their argument that many times:",
|
|
2875
|
+
"```",
|
|
2876
|
+
"; 2 “Repeats”",
|
|
2877
|
+
"# “RepeatsRepeats”",
|
|
2878
|
+
"```",
|
|
2879
|
+
"",
|
|
2880
|
+
"### Terminals",
|
|
2881
|
+
"",
|
|
2882
|
+
"Terminals in Homoiconic C look much like those in other C-based",
|
|
2883
|
+
"languages -- see Table [#sec-table-terminals] -- with a few twists.",
|
|
2884
|
+
"",
|
|
2885
|
+
'~ TableFigure { #sec-table-terminals; caption: "Terminals Syntax" }',
|
|
2886
|
+
"+---------|-----------------------+------|-----------------+",
|
|
2887
|
+
"| Separators || Aggregates ||",
|
|
2888
|
+
"+---------|-----------------------+------|-----------------+",
|
|
2889
|
+
"| , | _end expression_ | ( | _begin group_ |",
|
|
2890
|
+
"| ; | _void expression_ | ) | _end group_ |",
|
|
2891
|
+
"| newline | _end line_ | \\[ | _begin array_ |",
|
|
2892
|
+
"| space | _split subexpression_ | ] | _end array_ |",
|
|
2893
|
+
"| || { | _begin closure_ |",
|
|
2894
|
+
"| || } | _end closure_ |",
|
|
2895
|
+
"+---------|-----------------------+------|-----------------+",
|
|
2896
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
2897
|
+
" tbody-tr-even-background-color:Floralwhite }",
|
|
2898
|
+
"~",
|
|
2899
|
+
"",
|
|
2900
|
+
"Formally speaking, each expression should terminate in an ',' or ';', depending",
|
|
2901
|
+
"on whether we want to return the resulting value:",
|
|
2902
|
+
"```",
|
|
2903
|
+
"; “My Statement”;",
|
|
2904
|
+
"; “Self Expression”,",
|
|
2905
|
+
"# “Self Expression”",
|
|
2906
|
+
"```",
|
|
2907
|
+
'This effectively allows us to distinguish "expressions" that return a',
|
|
2908
|
+
'value from "statements" that do not. However, trailing commas are',
|
|
2909
|
+
"optional, if neither separator is present will be inferred at the end of",
|
|
2910
|
+
"a line or aggregate.",
|
|
2911
|
+
"",
|
|
2912
|
+
"Space plays an important role in binding, since we do not allow implicit",
|
|
2913
|
+
"precedence. Spaces create a new subexpression, so frames that have no",
|
|
2914
|
+
"space between them bind more tightly than those that do.",
|
|
2915
|
+
"",
|
|
2916
|
+
"```",
|
|
2917
|
+
"; “Want ” 2 “Live” # evaluates left to right",
|
|
2918
|
+
"# “Want 2Live”",
|
|
2919
|
+
"; “Want ” (2“Live”) # TODO: evaluates `2“Live”` first w/o parentheses",
|
|
2920
|
+
"# “Want LiveLive”",
|
|
2921
|
+
"```",
|
|
2922
|
+
"This of course can also be done (with more visual clutter) via explicit grouping:",
|
|
2923
|
+
"```",
|
|
2924
|
+
"; “Want ” (2 “Live”) # evaluates grouped expressions first",
|
|
2925
|
+
"# “Want LiveLive”",
|
|
2926
|
+
"```",
|
|
2927
|
+
"",
|
|
2928
|
+
"Arrays work as you'd expect:",
|
|
2929
|
+
"```",
|
|
2930
|
+
"; [1, 1, 2, 3, 5] 8",
|
|
2931
|
+
"# [1, 1, 2, 3, 5, 8]",
|
|
2932
|
+
"```",
|
|
2933
|
+
"",
|
|
2934
|
+
"Closures are simply lazy expressions, which evaluate their contents when invoked.",
|
|
2935
|
+
"```",
|
|
2936
|
+
"; { “Life, ” “The Universe, ” “Everything.” } ()",
|
|
2937
|
+
"# “Life, The Universe, Everything.”",
|
|
2938
|
+
"```",
|
|
2939
|
+
"The result of the empty expression (`()`) is called `nil`, and represents the Boolean false.",
|
|
2940
|
+
"This will become important in Section [#sec-operators] when we discuss conditionals.",
|
|
2941
|
+
"",
|
|
2942
|
+
"Note that statements inside a closure represent values that are not",
|
|
2943
|
+
"returned, which becomes very powerful when we add identifiers.",
|
|
2944
|
+
"",
|
|
2945
|
+
'Importantly, the empty closure `{}` becomes the "codify" operator, which converts arrays',
|
|
2946
|
+
"into deferred expressions:",
|
|
2947
|
+
"",
|
|
2948
|
+
"```",
|
|
2949
|
+
"; {} [“Life, ” “The Universe, ” “Everything.”]",
|
|
2950
|
+
"# (“Life, The Universe, Everything.”)",
|
|
2951
|
+
"```",
|
|
2952
|
+
"",
|
|
2953
|
+
"### Identifiers",
|
|
2954
|
+
"",
|
|
2955
|
+
"Everything else is just an identifier. Identifiers can contain letters,",
|
|
2956
|
+
"numbers, or non-terminal symbols. They come in several varieties as",
|
|
2957
|
+
"described in Table [#sec-table-id].",
|
|
2958
|
+
"",
|
|
2959
|
+
'~ TableFigure { #sec-table-id; caption: "Identifiers" }',
|
|
2960
|
+
"+-----------+----------------+-------------+-------------------------+",
|
|
2961
|
+
"|Variety | Example | Starts With | Contains |",
|
|
2962
|
+
"+-----------+----------------+-------------+-------------------------+",
|
|
2963
|
+
"| Label | _variable_ | _letter_ | _letter_, _number_, `-` |",
|
|
2964
|
+
"| Operator | `+` | _symbol_ | _symbol_ |",
|
|
2965
|
+
"| Alias | `@variable` | `@` | _identifier_ |",
|
|
2966
|
+
"| Scope | `$` / `$$` | `$` | `$`, then `.property` |",
|
|
2967
|
+
"| Argument | \\_^ | \\_ | \\_,\\^ |",
|
|
2968
|
+
"| Parameter | `.` / `..` | `.` | `.` |",
|
|
2969
|
+
"+-----------+----------------+-------------+-------------------------+",
|
|
2970
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
2971
|
+
" tr-even-background-color:Floralwhite }",
|
|
2972
|
+
"",
|
|
2973
|
+
"~",
|
|
2974
|
+
"",
|
|
2975
|
+
"Syntactically these are equivalent, with one small piece of syntactic",
|
|
2976
|
+
"sugar for operators; the dot is optional when used in a binary relation:",
|
|
2977
|
+
"",
|
|
2978
|
+
"```",
|
|
2979
|
+
"; 2 .+ 2",
|
|
2980
|
+
"# 4",
|
|
2981
|
+
"",
|
|
2982
|
+
"; 2 + 2",
|
|
2983
|
+
"# 4",
|
|
2984
|
+
"```",
|
|
2985
|
+
"",
|
|
2986
|
+
"#### Assignment",
|
|
2987
|
+
"",
|
|
2988
|
+
"Identifiers can be referred to via three different modes:",
|
|
2989
|
+
"",
|
|
2990
|
+
"- `value`",
|
|
2991
|
+
"- `.name`",
|
|
2992
|
+
"- `@reference`",
|
|
2993
|
+
"",
|
|
2994
|
+
"Assignment is just a simple expression setting a property with that name",
|
|
2995
|
+
"in the current context. Parentheses make the value expression explicit:",
|
|
2996
|
+
"```",
|
|
2997
|
+
"; .x (6 * 7);",
|
|
2998
|
+
"```",
|
|
2999
|
+
"This avoids the subtle and confusing distinction between differing",
|
|
3000
|
+
'"left-hand-side" and "right-hand-side" interpretations of an identical symbol _x_.',
|
|
3001
|
+
"That enables `=` to always mean a test for equality, rather than also being used",
|
|
3002
|
+
"for assignment.",
|
|
3003
|
+
"",
|
|
3004
|
+
"We can use the value `x` to access that property in the same or any child context:",
|
|
3005
|
+
"",
|
|
3006
|
+
"```",
|
|
3007
|
+
"; x",
|
|
3008
|
+
"# 42",
|
|
3009
|
+
"; [x]",
|
|
3010
|
+
"# [42]",
|
|
3011
|
+
"```",
|
|
3012
|
+
"",
|
|
3013
|
+
"To set the property in the context it was defined, rather than the local context,",
|
|
3014
|
+
"use a _reference_ instead of a name. Here the array creates a child data context:",
|
|
3015
|
+
"```",
|
|
3016
|
+
"; .y 7;",
|
|
3017
|
+
"; [.x 11; @y 3;];",
|
|
3018
|
+
"; x",
|
|
3019
|
+
"# 42",
|
|
3020
|
+
"; y",
|
|
3021
|
+
"# 3",
|
|
3022
|
+
"```",
|
|
3023
|
+
"",
|
|
3024
|
+
"Names also provide an elegant way of manipulating data structures, still",
|
|
3025
|
+
"in the context of simple expressions. Arrays carry properties; a closure can",
|
|
3026
|
+
"apply a setter to an array passed as its argument, when the name grants it.",
|
|
3027
|
+
"A trailing underscore declares a mutable name, and only a mutable name lets a",
|
|
3028
|
+
"callee write through it:",
|
|
3029
|
+
"",
|
|
3030
|
+
"```",
|
|
3031
|
+
"; .base_ [.key 42;];",
|
|
3032
|
+
"; base_ .key # gets property",
|
|
3033
|
+
"# 42",
|
|
3034
|
+
"; {.key 113} base_; # sets property",
|
|
3035
|
+
"; base_ .key",
|
|
3036
|
+
"# 113",
|
|
3037
|
+
"; .fixed [.key 42;];",
|
|
3038
|
+
"; {.key 113} fixed; # binds locally, fixed is untouched",
|
|
3039
|
+
"; fixed .key",
|
|
3040
|
+
"# 42",
|
|
3041
|
+
"```",
|
|
3042
|
+
"The space between _base_ and _key is not necessary, but we use it to",
|
|
3043
|
+
"emphasize the fact that this is just an ordinary expression, not a",
|
|
3044
|
+
"special syntax.",
|
|
3045
|
+
"",
|
|
3046
|
+
"#### Scope Anchors",
|
|
3047
|
+
"",
|
|
3048
|
+
"Two anchors make non-local namespaces explicit without counting lexical levels:",
|
|
3049
|
+
"",
|
|
3050
|
+
"- `$` is the top-level namespace of the current file or module.",
|
|
3051
|
+
"- `$$` is the namespace supplied by the host.",
|
|
3052
|
+
"",
|
|
3053
|
+
"Ordinary property syntax performs reads, as in `$.setting` and `$$.HOME`. A bare",
|
|
3054
|
+
"name never searches `$$`, so the process environment cannot silently determine",
|
|
3055
|
+
"whether a program binds an identifier. Host namespace bindings cannot be",
|
|
3056
|
+
"replaced by HC source, though a mutable value deliberately supplied by the host",
|
|
3057
|
+
"retains its ordinary effects. Top-level declarations still use `.name`, and",
|
|
3058
|
+
"`@name` reassigns a binding in the context where HC defined it.",
|
|
3059
|
+
"",
|
|
3060
|
+
"#### Controls",
|
|
3061
|
+
"",
|
|
3062
|
+
"As part of its quest to avoid arbitrary keywords, HC introduces the concept of",
|
|
3063
|
+
"_controls_, mirroring the hardware distinction between the control plane and the data plane.",
|
|
3064
|
+
"Controls are special closures which modify the behavior of the runtime, rather than",
|
|
3065
|
+
"simply returning values.",
|
|
3066
|
+
"",
|
|
3067
|
+
"##### Flow Control",
|
|
3068
|
+
"",
|
|
3069
|
+
"HC currently has no sigil for imperative exit or multi-level return. Earlier",
|
|
3070
|
+
"drafts reserved `$$`, `$<`, and `$<<` for those operations; those spellings are",
|
|
3071
|
+
"retired. `$$` is now the explicit host-namespace anchor, while `$<` and `$<<`",
|
|
3072
|
+
"are rejected rather than silently consuming an expression.",
|
|
3073
|
+
"",
|
|
3074
|
+
"",
|
|
3075
|
+
"##### Exceptions",
|
|
3076
|
+
"",
|
|
3077
|
+
"Controls are also used to signal exceptions and errors. Exception controls",
|
|
3078
|
+
"begin with `$!` and return an interrupt value that propagates back up the call",
|
|
3079
|
+
"chain until it encounters an appropriate handler or aborts the program. The REPL,",
|
|
3080
|
+
"however, simply prints out the exceptional value:",
|
|
3081
|
+
"",
|
|
3082
|
+
"```",
|
|
3083
|
+
"; .scope [.a 1; .b 2;];",
|
|
3084
|
+
"; scope.c",
|
|
3085
|
+
"# $!.name-missing “...",
|
|
3086
|
+
"```",
|
|
3087
|
+
"Note that in the interest of clarify, we voilate our usual rule and use",
|
|
3088
|
+
"English names for exceptions. We do still intend to make these fully",
|
|
3089
|
+
"localizable, so at least beginning programmers can experience an environment",
|
|
3090
|
+
"that doesn't require them to also learn a foreign language.",
|
|
3091
|
+
"",
|
|
3092
|
+
"#### Arguments",
|
|
3093
|
+
"",
|
|
3094
|
+
"Use `_` as the anonymous argument, representing everything this frame",
|
|
3095
|
+
"was called with:",
|
|
3096
|
+
"```",
|
|
3097
|
+
"; .triplicate {3 _};",
|
|
3098
|
+
"; triplicate “Baby”",
|
|
3099
|
+
"# “BabyBabyBaby”",
|
|
3100
|
+
"```",
|
|
3101
|
+
"This is useful not just for closures, but for representing the command-line",
|
|
3102
|
+
"arguments for the entire script.",
|
|
3103
|
+
"",
|
|
3104
|
+
"When you apply something to a closure, it is effectively inserting that",
|
|
3105
|
+
"argument into the inheritance hierarchy. Thus we can access properties",
|
|
3106
|
+
"of the argument directly, rather than explicitly calling `_`.",
|
|
3107
|
+
"```",
|
|
3108
|
+
"; .mag {(x * x) + (y * y )};",
|
|
3109
|
+
"; mag (.x 1; .y 2;)",
|
|
3110
|
+
"# 5",
|
|
3111
|
+
"```",
|
|
3112
|
+
"You can reach past the argument to the enclosing lexical scope (one level above)",
|
|
3113
|
+
"using the `_^` identifier. It is not a `super` reference: it names the scope the",
|
|
3114
|
+
"closure was written in, not a declared parent, and each caret is one more",
|
|
3115
|
+
"lexical scope out regardless of how the closure was called.",
|
|
3116
|
+
"```",
|
|
3117
|
+
"; .print-arg { var };",
|
|
3118
|
+
"; .print-parent { _^.var };",
|
|
3119
|
+
"; .var “parent”;",
|
|
3120
|
+
"",
|
|
3121
|
+
"; print-arg(.var “arg”)",
|
|
3122
|
+
"# “arg”",
|
|
3123
|
+
"; print-parent(.var “arg”)",
|
|
3124
|
+
"# “parent”",
|
|
3125
|
+
"```",
|
|
3126
|
+
"Since objects capture the scope where they are created, this even allows",
|
|
3127
|
+
"closures to be called with implicit arguments to access the enclosing",
|
|
3128
|
+
"scope:",
|
|
3129
|
+
"```",
|
|
3130
|
+
"; .x 3;",
|
|
3131
|
+
"; .y 4;",
|
|
3132
|
+
"; mag []",
|
|
3133
|
+
"# 25",
|
|
3134
|
+
"```",
|
|
3135
|
+
"Implicit arguments are a code smell, and will generate a warning.",
|
|
3136
|
+
"However, they can be very useful when debugging or refactoring. That may seem",
|
|
3137
|
+
"dangerous, but the data protection rules (below) largely limit what the called",
|
|
3138
|
+
"function can do to the calling scope.",
|
|
3139
|
+
"",
|
|
3140
|
+
"#### Call Parameters",
|
|
3141
|
+
"",
|
|
3142
|
+
"Iterator blocks receive a second value alongside their ordinary `_` argument:",
|
|
3143
|
+
"`|` supplies the element index, `&&` the property key, and `&` the running",
|
|
3144
|
+
"accumulator. `.` reads that current call parameter. Repeat the dot to reach the",
|
|
3145
|
+
"same role in exact enclosing calls: `..` is one call outward, `...` two. If the",
|
|
3146
|
+
"requested call supplied no parameter, the read reports `$!.name-missing`; dot",
|
|
3147
|
+
"has no separate `Self` meaning.",
|
|
3148
|
+
"",
|
|
3149
|
+
"## Operators",
|
|
3150
|
+
"",
|
|
3151
|
+
"Homoiconic C predefines a small number of top-level operators used by all",
|
|
3152
|
+
"frames. These provide functionality other languages often hard-code into",
|
|
3153
|
+
"their syntax. Note that specific datatypes may define their own operators",
|
|
3154
|
+
"(e.g., `+` for numbers) not covered in this section.",
|
|
3155
|
+
"",
|
|
3156
|
+
"### Type Operations",
|
|
3157
|
+
"Like all modern statically typed languages, HC relies heavily on type",
|
|
3158
|
+
"inference. By using dataflow, we also eliminate the need to define",
|
|
3159
|
+
"variables for loops or temporary variables. In addition, a frame that is",
|
|
3160
|
+
"callable with any other frame has the generic type, and thus does not need to be",
|
|
3161
|
+
"declared.",
|
|
3162
|
+
"",
|
|
3163
|
+
"However, there are times we do need to explicitly annotate what kind of",
|
|
3164
|
+
"frames we are expecting, especially at function boundaries. For those",
|
|
3165
|
+
"cases we use the type operators in Table [#sec-table-type].",
|
|
3166
|
+
"",
|
|
3167
|
+
'~ TableFigure { #sec-table-type; caption: "Type Operators" }',
|
|
3168
|
+
"",
|
|
3169
|
+
"+---|--------------+------|--------------+",
|
|
3170
|
+
"| Type || Bind | |",
|
|
3171
|
+
"+---|--------------+------|--------------+",
|
|
3172
|
+
"| < | _begin type_ | \\~\\~ | _get type_ |",
|
|
3173
|
+
"| > | _end type_ | ^ | _bind type_ |",
|
|
3174
|
+
"| ~ |_has type_ | ^^ |_bind return_ |",
|
|
3175
|
+
"+---|--------------+------|--------------+",
|
|
3176
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
3177
|
+
" tr-even-background-color:Floralwhite }",
|
|
3178
|
+
"~",
|
|
3179
|
+
"",
|
|
3180
|
+
"Note that in HC, type is declared using a pair of operators, not a syntactic",
|
|
3181
|
+
"construct. This works because types are just expressions, and thus do not",
|
|
3182
|
+
"need to change the evaluation rules.",
|
|
3183
|
+
"",
|
|
3184
|
+
"",
|
|
3185
|
+
"#### The All Type",
|
|
3186
|
+
"",
|
|
3187
|
+
"The empty type `<>` is known as _all_. As the opposite of the empty expression `()` _nil_,",
|
|
3188
|
+
"it acts as the boolean `true` value.",
|
|
3189
|
+
"```",
|
|
3190
|
+
"; <>",
|
|
3191
|
+
"# <>",
|
|
3192
|
+
"; ().!",
|
|
3193
|
+
"# <>",
|
|
3194
|
+
"; <>",
|
|
3195
|
+
"# <>",
|
|
3196
|
+
"; <>.!",
|
|
3197
|
+
"# ()",
|
|
3198
|
+
"; ()",
|
|
3199
|
+
"# ()",
|
|
3200
|
+
"```",
|
|
3201
|
+
"#### Type Membership",
|
|
3202
|
+
"",
|
|
3203
|
+
"The _has-type_ operator `~` tests whether an object belongs to particular",
|
|
3204
|
+
"type, returning true (all) or false (nil). Every object is a member of",
|
|
3205
|
+
"_all_, while nothing is a member of _nil_:",
|
|
3206
|
+
"```",
|
|
3207
|
+
"; 1 ~ <>",
|
|
3208
|
+
"# <>",
|
|
3209
|
+
"; 2 ~ ()",
|
|
3210
|
+
"# ()",
|
|
3211
|
+
"; ()",
|
|
3212
|
+
"# ()",
|
|
3213
|
+
"```",
|
|
3214
|
+
"#### Type Signatures",
|
|
3215
|
+
"",
|
|
3216
|
+
"We use `^` to specify the type signature of a closure, which may include",
|
|
3217
|
+
"optional defaults:",
|
|
3218
|
+
"```",
|
|
3219
|
+
"; .join-name (.first “Jane”, .last) ^ {last “, ” first};",
|
|
3220
|
+
"; join-name (.first “John”, .last “Doe”)",
|
|
3221
|
+
"# “Doe, John”",
|
|
3222
|
+
"```",
|
|
3223
|
+
"Types are generous, in that you are allowed to specify additional properties,",
|
|
3224
|
+
"but it is an error to omit properties that do not have a default:",
|
|
3225
|
+
"```",
|
|
3226
|
+
"; join-name (.middle “Q”, .last “Doe”)",
|
|
3227
|
+
"# “Doe, Jane”",
|
|
3228
|
+
"; join-name (.middle “Q”)",
|
|
3229
|
+
"# $!invalid-argument-list (.middle “Q”, $!missing-required-argument .last;)",
|
|
3230
|
+
"```",
|
|
3231
|
+
"The return type is usually inferred, but can be specified explicitly using a trailing `^^`.",
|
|
3232
|
+
"",
|
|
3233
|
+
"",
|
|
3234
|
+
"#### Type Values",
|
|
3235
|
+
"",
|
|
3236
|
+
"The simplest way to construct a type is to use the `~~` operator to extract the type",
|
|
3237
|
+
"of a known object:",
|
|
3238
|
+
"```",
|
|
3239
|
+
"; “Q” ~ ~~“”",
|
|
3240
|
+
"# <>",
|
|
3241
|
+
"; “Q” ~ ~~1",
|
|
3242
|
+
"# ()",
|
|
3243
|
+
"```",
|
|
3244
|
+
"### Content",
|
|
3245
|
+
"",
|
|
3246
|
+
"Homoiconic C defines three content operators, each of which come in three",
|
|
3247
|
+
"flavors as shown in Table [#sec-table-content].",
|
|
3248
|
+
"",
|
|
3249
|
+
'~ TableFigure { #sec-table-content; caption: "Content Operators" }',
|
|
3250
|
+
"+----------+-----+------+----------+",
|
|
3251
|
+
"| Content ||||",
|
|
3252
|
+
"|Role | All | Data | Metadata |",
|
|
3253
|
+
"+----------+-----+------+----------+",
|
|
3254
|
+
"| Equality | \\= | \\=\\= | \\=\\=\\= |",
|
|
3255
|
+
"| Map | \\| | \\|\\| | \\|\\|\\| |",
|
|
3256
|
+
"| Fold | & | && | &&& |",
|
|
3257
|
+
"+----------+-----+------+----------+",
|
|
3258
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
3259
|
+
" tr-even-background-color:Floralwhite }",
|
|
3260
|
+
"~",
|
|
3261
|
+
"These flavors determine whether we consider the whole object, or just the data",
|
|
3262
|
+
"or metadata separately.",
|
|
3263
|
+
"",
|
|
3264
|
+
"#### Equality",
|
|
3265
|
+
"Equality is a ladder, each rung strictly stronger than the last. `=` asks for",
|
|
3266
|
+
"the same value, `==` for the same value and type, and `===` for the same frame:",
|
|
3267
|
+
"```",
|
|
3268
|
+
"; .a [113, .p 887];",
|
|
3269
|
+
"; .b [113, .p 661];",
|
|
3270
|
+
"; .c [443, .p 887];",
|
|
3271
|
+
"; a = a",
|
|
3272
|
+
"# <>",
|
|
3273
|
+
"; a = b",
|
|
3274
|
+
"# ()",
|
|
3275
|
+
"; a = [113, .p 887]",
|
|
3276
|
+
"# <>",
|
|
3277
|
+
"; [3] = [3.0]",
|
|
3278
|
+
"# <>",
|
|
3279
|
+
"; [3] == [3.0]",
|
|
3280
|
+
"# ()",
|
|
3281
|
+
"; a == [113, .p 887]",
|
|
3282
|
+
"# <>",
|
|
3283
|
+
"; a === [113, .p 887]",
|
|
3284
|
+
"# ()",
|
|
3285
|
+
"; a === a",
|
|
3286
|
+
"# <>",
|
|
3287
|
+
"```",
|
|
3288
|
+
"#### Iterators",
|
|
3289
|
+
"",
|
|
3290
|
+
"We use `&` for map. Each element is applied to the value on the right, and the",
|
|
3291
|
+
"answers are kept apart.",
|
|
3292
|
+
"```",
|
|
3293
|
+
"; [1, 2, 3] & { _ + 1 }",
|
|
3294
|
+
"# [2, 3, 4]",
|
|
3295
|
+
"```",
|
|
3296
|
+
"We use `|` for reduce, in homage to the UNIX pipeline: each element is applied to",
|
|
3297
|
+
"the value the last one answered, so what you start from is the combining rule.",
|
|
3298
|
+
"```",
|
|
3299
|
+
"; [1, 2, 3] | “”",
|
|
3300
|
+
"# “123”",
|
|
3301
|
+
"; [1, 2, 3] | 1",
|
|
3302
|
+
"# 6",
|
|
3303
|
+
"```",
|
|
3304
|
+
"Doubling either operator widens the stream to `[key, value]` tuples, so a step",
|
|
3305
|
+
"knows which address it is looking at.",
|
|
3306
|
+
"```",
|
|
3307
|
+
"; [10, 20] && { _ }",
|
|
3308
|
+
"# [[.0, 10], [.1, 20]]",
|
|
3309
|
+
"```",
|
|
3310
|
+
"The operators also work with resources, which push characters rather than lines",
|
|
3311
|
+
"or records, so what a read answers is decided by what it is reduced into rather",
|
|
3312
|
+
"than by the source. `hc/resources.hc` is the executable corpus for that,",
|
|
3313
|
+
"since it needs a root binding this document is not granted.",
|
|
3314
|
+
"",
|
|
3315
|
+
"### Conditionals",
|
|
3316
|
+
"",
|
|
3317
|
+
"Homoiconic C's sole conditionals are a pair of binary operators analogous to C's ternary operator,",
|
|
3318
|
+
"albeit with slightly different semantics. These are described in Table [#sec-table-cond].",
|
|
3319
|
+
"",
|
|
3320
|
+
'~ TableFigure { #sec-table-cond; caption: "Conditional Operators" }',
|
|
3321
|
+
"",
|
|
3322
|
+
"+-------+--------+-------+--------+",
|
|
3323
|
+
"| Operator | Name| On Frame | On Nil |",
|
|
3324
|
+
"+-------+--------+-------+--------+",
|
|
3325
|
+
"| ? | _if_ | Call with `()` | Return `()` |",
|
|
3326
|
+
"| : | _else_ |Return the frame | Call with `()` |",
|
|
3327
|
+
"+-------+--------+-------+--------+",
|
|
3328
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
3329
|
+
" tr-even-background-color:Floralwhite }",
|
|
3330
|
+
"~",
|
|
3331
|
+
"",
|
|
3332
|
+
"Note that these are not special forms, but simply defined with one behavior on nil",
|
|
3333
|
+
'and the opposite on regular frames. `:` reads as "or else": a frame answers itself.',
|
|
3334
|
+
"```",
|
|
3335
|
+
"; 1 ? {2 + 2}",
|
|
3336
|
+
"# 4",
|
|
3337
|
+
"; 1 : {2 + 2}",
|
|
3338
|
+
"# 1",
|
|
3339
|
+
"",
|
|
3340
|
+
"; () ? {2 + 2}",
|
|
3341
|
+
"# ()",
|
|
3342
|
+
"; () : {2 + 2}",
|
|
3343
|
+
"# 4",
|
|
3344
|
+
"```",
|
|
3345
|
+
"Chaining applies those binary rules using HC's ordinary left-to-right",
|
|
3346
|
+
"evaluation. The result returned by `?` becomes the left operand of `:`, so",
|
|
3347
|
+
"`c ? t : e` answers `t` or `e`. A taken branch that answers nil falls through",
|
|
3348
|
+
"to `e`, the price of composing two binary operators:",
|
|
3349
|
+
"```",
|
|
3350
|
+
"; 1.> 5 ? (2 * 50) : 10",
|
|
3351
|
+
"# 10",
|
|
3352
|
+
"; 5.> 1 ? (2 * 50) : 10",
|
|
3353
|
+
"# 100",
|
|
3354
|
+
"`````",
|
|
3355
|
+
"Note that applying nil to anything other than a closure has no effect, so",
|
|
3356
|
+
"conditionals work just as well with simple expressions as they do with",
|
|
3357
|
+
"lazy blocks.",
|
|
3358
|
+
"",
|
|
3359
|
+
"### Importing Modules",
|
|
3360
|
+
"",
|
|
3361
|
+
"> [!NOTE]",
|
|
3362
|
+
"> `<-` imports a resource: `Figures <- './hc/figures.hc'` evaluates that",
|
|
3363
|
+
"> file in a fresh namespace and binds the namespace to `Figures`, and",
|
|
3364
|
+
"> `. <- '…'` imports into the current namespace. Every file in the",
|
|
3365
|
+
"> package's `hc/` folder is bundled and can be imported this way, its",
|
|
3366
|
+
"> examples skipped. Matching a bare name such as `.module` against a",
|
|
3367
|
+
"> registry, as sketched below, is not implemented.",
|
|
3368
|
+
"",
|
|
3369
|
+
"Importing external modules into a program has come a long way from C's",
|
|
3370
|
+
"text-based `#include` statement. Modern imports are typically expected",
|
|
3371
|
+
"to perform three roles:",
|
|
3372
|
+
"",
|
|
3373
|
+
"1. Match a module name with a local package on disk, often downloaded via",
|
|
3374
|
+
" a package manager",
|
|
3375
|
+
"2. Read information from that module",
|
|
3376
|
+
"3. Import names from that module into the current namespace",
|
|
3377
|
+
"",
|
|
3378
|
+
"This functionality must be available as a primitive, since it is necessary",
|
|
3379
|
+
"for adding other functionality.",
|
|
3380
|
+
"",
|
|
3381
|
+
"We use the `<-` import operator to match a name against both the online",
|
|
3382
|
+
"registry (TBD) and the local path, and load it into a property with the",
|
|
3383
|
+
"same name. Registry settings can be configured via the `.hconfig` file.",
|
|
3384
|
+
"",
|
|
3385
|
+
"```hc",
|
|
3386
|
+
"; <- .module;",
|
|
3387
|
+
"; module",
|
|
3388
|
+
"# (.prop 1, .another-prop 2)",
|
|
3389
|
+
"```",
|
|
3390
|
+
"",
|
|
3391
|
+
"We can also bind it to a different name:",
|
|
3392
|
+
"",
|
|
3393
|
+
"```hc",
|
|
3394
|
+
"; .alias <- .module;",
|
|
3395
|
+
"; alias.prop",
|
|
3396
|
+
"# 1",
|
|
3397
|
+
"```",
|
|
3398
|
+
"",
|
|
3399
|
+
"or directly into the current namespace `.`.",
|
|
3400
|
+
"",
|
|
3401
|
+
"```hc",
|
|
3402
|
+
"; . <- .module;",
|
|
3403
|
+
"; prop",
|
|
3404
|
+
"# 1",
|
|
3405
|
+
"```",
|
|
3406
|
+
"",
|
|
3407
|
+
"A module can also be named by a resource identifier, since `'…'` denotes",
|
|
3408
|
+
"anything outside the program without granting any authority over it:",
|
|
3409
|
+
"",
|
|
3410
|
+
"```hc",
|
|
3411
|
+
"; .hclang <- 'jsr:@swanfactory/hclang';",
|
|
3412
|
+
"; hclang.execute “1 + 1”",
|
|
3413
|
+
"# “2”",
|
|
3414
|
+
"```",
|
|
3415
|
+
"",
|
|
3416
|
+
'While not recommended in general, direct import allows apparently "built-in"',
|
|
3417
|
+
"functionality to provided via a prologue, rather than hard-coded into the",
|
|
3418
|
+
"language. This reflects HC's philosophy to provide the same functionality",
|
|
3419
|
+
"we have as language designers to end users wherever possible.",
|
|
3420
|
+
"",
|
|
3421
|
+
"## Access Control { #sec-access }",
|
|
3422
|
+
"",
|
|
3423
|
+
"Arguably the primary source of bugs, clutter, and complexity in",
|
|
3424
|
+
'programming languages is knowing "who can perform which actions on what data,"',
|
|
3425
|
+
'which we refer to somewhat loosely as "access control." We consider this',
|
|
3426
|
+
'problem so important we spend the bulk of our "syntactic budget" on',
|
|
3427
|
+
"giving programmers an easy way to specify and detect access modes. This",
|
|
3428
|
+
"is done by encoding those rules in the identifiers themselves, as seen in",
|
|
3429
|
+
"Table {#sec-table-access}.",
|
|
3430
|
+
"",
|
|
3431
|
+
'~ TableFigure { #sec-table-access; caption: "Access Modifiers" }',
|
|
3432
|
+
"",
|
|
3433
|
+
"+-----------+------------+-------------+",
|
|
3434
|
+
"|Privacy | Constancy || Effect |",
|
|
3435
|
+
"+-----------+------------+-------------+",
|
|
3436
|
+
"| _public_ | _variable_ | _immutable_ |",
|
|
3437
|
+
"| \\__protected_ | _Constant_ | _mutable_\\_ |",
|
|
3438
|
+
"| \\_\\__private_ | | _mutating_: |",
|
|
3439
|
+
"+-----------+------------+-------------+",
|
|
3440
|
+
"{ tbody-tr-odd-background-color:Gainsboro; \\",
|
|
3441
|
+
" tr-even-background-color:Floralwhite }",
|
|
3442
|
+
"~",
|
|
3443
|
+
"",
|
|
3444
|
+
"Importantly, these are modifiers not different identifiers. So, for example, the",
|
|
3445
|
+
"constant `COOL` in one scope overrides its case duplicate `cool` from a",
|
|
3446
|
+
"parent scope. For natural languages without separate upper and lower",
|
|
3447
|
+
"case, we use an initial letter `K` to denote the constant version.",
|
|
3448
|
+
"",
|
|
3449
|
+
"### Encapsulation",
|
|
3450
|
+
"",
|
|
3451
|
+
"The simplest form of access control is _encapsulation_, restricting the ability of",
|
|
3452
|
+
"external objects to even see certain properties. Here we follow the informal",
|
|
3453
|
+
"conventions often used in C programs:",
|
|
3454
|
+
"",
|
|
3455
|
+
"* `public`",
|
|
3456
|
+
" : visible to everyone",
|
|
3457
|
+
"* `_protected`",
|
|
3458
|
+
" : not visible to parents or peers, but still visible to children",
|
|
3459
|
+
"* `__private`",
|
|
3460
|
+
" : not visible to anyone, even children",
|
|
3461
|
+
"",
|
|
3462
|
+
"A method runs against its own object, so it reaches all three of its own",
|
|
3463
|
+
"properties. A child reaches the public and protected ones, while an outside",
|
|
3464
|
+
"peer reaches only the public one:",
|
|
3465
|
+
"`````",
|
|
3466
|
+
"; .see-me [.my-public-value 42; ._my-protected-value 21; .__my-private-value 7; .own-method {[my-public-value, my-protected-value, my-private-value]}];",
|
|
3467
|
+
"; see-me.own-method()",
|
|
3468
|
+
"# [42, 21, 7]",
|
|
3469
|
+
"; .my-child [.^ see-me; .read {[my-public-value, my-protected-value, my-private-value]}];",
|
|
3470
|
+
"; my-child.read()",
|
|
3471
|
+
"# [42, 21, $!.is-private .my-private-value]",
|
|
3472
|
+
"; see-me.my-public-value",
|
|
3473
|
+
"# 42",
|
|
3474
|
+
"; see-me.my-protected-value",
|
|
3475
|
+
"# $!.is-protected .my-protected-value",
|
|
3476
|
+
"; see-me.my-private-value",
|
|
3477
|
+
"# $!.is-private .my-private-value",
|
|
3478
|
+
"```",
|
|
3479
|
+
"### Effect",
|
|
3480
|
+
"",
|
|
3481
|
+
"Rather than specifying _call-by-value_ or _call-by-reference_, HC is",
|
|
3482
|
+
"designed around the BitC[@BitC] model of effect typing. Shapiro *et al*",
|
|
3483
|
+
"proved it is possible to have a sound *and* complete systems language if",
|
|
3484
|
+
"we explicitly annotate identifiers for both **constancy** and",
|
|
3485
|
+
"**mutability** (which together we call _effect_ ) at each context",
|
|
3486
|
+
"boundary. This gives the compiler enough information to know how and when",
|
|
3487
|
+
"to safely copy or share data structures. Put another way, effect typing",
|
|
3488
|
+
"makes it as easy to allow side effects for performance as it is to",
|
|
3489
|
+
"restrict side effects for safety.",
|
|
3490
|
+
"",
|
|
3491
|
+
" Unfortunately, BitC could not accommodate such annotations within their",
|
|
3492
|
+
" Lisp-like syntax[@Cite]. Inspired by their work, we have designed the",
|
|
3493
|
+
" syntax of our identifiers to explicitly support effect typing:",
|
|
3494
|
+
"",
|
|
3495
|
+
"* `variable`",
|
|
3496
|
+
" : Does not begin with an uppercase letter. Can be reassigned.",
|
|
3497
|
+
"* `CONSTANT`",
|
|
3498
|
+
" : Begins with uppercase letter. Can **not** be reassigned.",
|
|
3499
|
+
"* `immutable`",
|
|
3500
|
+
" : Has no suffix. Can not be modified in place.",
|
|
3501
|
+
"* `mutable_`",
|
|
3502
|
+
" : Trailing underscore. Can be modified in place.",
|
|
3503
|
+
"* `mutating_method_`",
|
|
3504
|
+
" : Trailing underscore. Can modify its parent context. Returns parent.",
|
|
3505
|
+
"",
|
|
3506
|
+
"",
|
|
3507
|
+
"Please note that these particular conventions are preliminary, and may",
|
|
3508
|
+
"change in future versions based on empirical tests of readability and",
|
|
3509
|
+
"intuitiveness. Since HC is just a data format, we plan to explicitly",
|
|
3510
|
+
"version documents and enable automatic migration between incompatible versions.",
|
|
3511
|
+
"",
|
|
3512
|
+
"#### Constancy",
|
|
3513
|
+
"",
|
|
3514
|
+
"BitC's first key insight is that _constancy_ (whether an identifier can be",
|
|
3515
|
+
"assigned a new value) is distinct from _mutability_ (whether the",
|
|
3516
|
+
"referenced value can be modified in place). In other words, constancy is",
|
|
3517
|
+
"a property of the _source_ object, whereas mutability is a property of the",
|
|
3518
|
+
"_destination_ object.",
|
|
3519
|
+
"```",
|
|
3520
|
+
"; .variable 42;",
|
|
3521
|
+
"; .Constant 21;",
|
|
3522
|
+
"; .variable 113",
|
|
3523
|
+
"# 113",
|
|
3524
|
+
"; .Constant 7",
|
|
3525
|
+
"# $error{$is-constant .Constant}",
|
|
3526
|
+
"```",
|
|
3527
|
+
"#### Mutability",
|
|
3528
|
+
"",
|
|
3529
|
+
"The second key insight from BitC is that effect is a property of",
|
|
3530
|
+
"_names_ rather than of _values_. Object literals have no effect",
|
|
3531
|
+
"restrictions on their own; this is contrast to, e.g., Apple's Cocoa",
|
|
3532
|
+
"frameworks[@Cite], where mutability is an inherent part of the object's",
|
|
3533
|
+
"constructed type. Instead, every object is in principle mutable, but as",
|
|
3534
|
+
"long as it is only referenced from immutable handles the compiler can",
|
|
3535
|
+
"safely share a single instance between them, avoiding unnecessary copies.",
|
|
3536
|
+
"",
|
|
3537
|
+
"Conversely, objects that are referenced and passed via mutable handles",
|
|
3538
|
+
'are explicitly "aliases" of each other, so the compiler knows that it',
|
|
3539
|
+
"needs to synchronize changes between local copies, ensure serialization",
|
|
3540
|
+
"between different threads, etc.",
|
|
3541
|
+
"",
|
|
3542
|
+
"In order to ensure both immutable and mutable handles support the same",
|
|
3543
|
+
"methods, HC explicitly tracks which methods mutate their parent scope via",
|
|
3544
|
+
"the same trailing underscore (`_`) that marks a mutable name. One marker",
|
|
3545
|
+
"serves the whole effect axis, so the colon keeps its single meaning as the",
|
|
3546
|
+
"if-else operator. When a mutating method is called on an immutable",
|
|
3547
|
+
"object, it simply performs a _copy-on-write_, returning a new object. To",
|
|
3548
|
+
"enable this, mutating methods can not explicitly return a value, but",
|
|
3549
|
+
'implicitly return their parent (e.g., "this"; see Section {#sec-oops} for',
|
|
3550
|
+
"more details).",
|
|
3551
|
+
"```",
|
|
3552
|
+
"; .fixed [.hic “Object”; .property 42; .accessor {property}; .mutator_ {@property _;}];",
|
|
3553
|
+
"; fixed.accessor()",
|
|
3554
|
+
"# 42",
|
|
3555
|
+
"; .varying_ (fixed.mutator_ 113);",
|
|
3556
|
+
"; varying_.accessor()",
|
|
3557
|
+
"# 113",
|
|
3558
|
+
"; fixed.accessor()",
|
|
3559
|
+
"# 42",
|
|
3560
|
+
"```",
|
|
3561
|
+
"# Applications {#sec-applications}",
|
|
3562
|
+
"",
|
|
3563
|
+
"While the above language may seem simple to the point of simplistic, it has a",
|
|
3564
|
+
"surprising amount of power. Here are a few examples of what it can do.",
|
|
3565
|
+
"",
|
|
3566
|
+
"## Congrams {#sec-congrams}",
|
|
3567
|
+
"",
|
|
3568
|
+
"As mentioned above, HC programs that consist only of literals other than closures",
|
|
3569
|
+
"are called _congrams_, which are just pure data. This provides a",
|
|
3570
|
+
"once-in-a-lifetime opportunity to bring rigor and consistency to a variety of organic",
|
|
3571
|
+
"data formats developed over the Internet's brief history.",
|
|
3572
|
+
"",
|
|
3573
|
+
"### HCSV",
|
|
3574
|
+
"",
|
|
3575
|
+
"Homoiconic C may finally provide a well-defined alternative to the",
|
|
3576
|
+
"ubiquitous CSV[@Cite] file. A properly-structured `.hcsv` file is just as compact",
|
|
3577
|
+
"as CSV, with two important differences:",
|
|
3578
|
+
"* The header row, if any, consists of a list of names",
|
|
3579
|
+
"* Strings must be (smart) quoted",
|
|
3580
|
+
"```",
|
|
3581
|
+
"; .first-name, .last-name, .phone-number",
|
|
3582
|
+
"# (.first-name, .last-name, .phone-number)",
|
|
3583
|
+
"; “John”, “Doe”, +1.408.555.1212",
|
|
3584
|
+
"# (“John”, “Doe”, +1.408.555.1212)",
|
|
3585
|
+
"; “Jane”, “Smith”, +1.650.555.1212",
|
|
3586
|
+
"# (“Jane”, “Smith”, +1.650.555.1212)",
|
|
3587
|
+
"```",
|
|
3588
|
+
"### HCSON",
|
|
3589
|
+
"",
|
|
3590
|
+
"HC can also emulate the popular JSON[@Cite] format, or more precisely its",
|
|
3591
|
+
"CoffeeScript cousin CSON[@Cite].",
|
|
3592
|
+
"```",
|
|
3593
|
+
"; .first-name “John”, .last-name “Doe”, .phone-number +1.408.555.1212",
|
|
3594
|
+
"# (.first-name “John”, .last-name “Doe”, .phone-number +1.408.555.1212)",
|
|
3595
|
+
"; .first-name “Jane”, .last-name “Smith”, .phone-number +1.650.555.1212",
|
|
3596
|
+
"# (“Jane”, “Smith”, +1.650.555.1212)",
|
|
3597
|
+
"```",
|
|
3598
|
+
"## Object-Orientation",
|
|
3599
|
+
"",
|
|
3600
|
+
"Perhaps surprisingly, it is possible to implement a complete object-oriented",
|
|
3601
|
+
"programming system using only the above primitives. All we need",
|
|
3602
|
+
"are our access control rules plus the parent declaration `.^`.",
|
|
3603
|
+
"",
|
|
3604
|
+
"### Singletons",
|
|
3605
|
+
"",
|
|
3606
|
+
"Let's start with a simple singleton object containing private data:",
|
|
3607
|
+
"```",
|
|
3608
|
+
"; .my-object_ [._property 13; .getProperty {_property}; .setProperty_ {@property _;}];",
|
|
3609
|
+
"; my-object_.getProperty()",
|
|
3610
|
+
"# 13",
|
|
3611
|
+
"; my-object_.setProperty_ 42;",
|
|
3612
|
+
"; my-object_.getProperty()",
|
|
3613
|
+
"# 42",
|
|
3614
|
+
"```",
|
|
3615
|
+
"### Classes",
|
|
3616
|
+
"",
|
|
3617
|
+
"To turn that into a class, we simply make it a closure which returns",
|
|
3618
|
+
"a frame analogous to that singleton:",
|
|
3619
|
+
"```",
|
|
3620
|
+
"; .my-class {[._property _; .getProperty {_property}; .setProperty_ {@property _;}]};",
|
|
3621
|
+
"; .my-instance (my-class 3);",
|
|
3622
|
+
"; my-instance.getProperty()",
|
|
3623
|
+
"# 3",
|
|
3624
|
+
"```",
|
|
3625
|
+
"### Inheritance",
|
|
3626
|
+
"",
|
|
3627
|
+
"Even inheritance is already accounted for, simply by explicitly specifying",
|
|
3628
|
+
"its parent scope:",
|
|
3629
|
+
"```",
|
|
3630
|
+
"; .my-base-class [.public-value 42; ._protected-value 21; .__private-value 7];",
|
|
3631
|
+
"; .my-subclass {[.^ my-base-class; .values {[public-value, protected-value, private-value]}]};",
|
|
3632
|
+
"; .my-subinstance (my-subclass());",
|
|
3633
|
+
"; my-subinstance.values()",
|
|
3634
|
+
"# [42, 21, $!.is-private .private-value]",
|
|
3635
|
+
"; my-subinstance.public-value",
|
|
3636
|
+
"# 42",
|
|
3637
|
+
"; my-subinstance.protected-value",
|
|
3638
|
+
"# $!.is-protected .protected-value",
|
|
3639
|
+
"```",
|
|
3640
|
+
"There is no built-in support for multiple inheritance. However, because",
|
|
3641
|
+
"inheritance is just another expression, you are welcome to define your own:",
|
|
3642
|
+
"```",
|
|
3643
|
+
"; .my-inheritance { [.a _.0.a; .b _.1.b] };",
|
|
3644
|
+
"; .my-base [.a 1];",
|
|
3645
|
+
"; .another-base [.b 2];",
|
|
3646
|
+
"; .multiclass (my-inheritance [my-base, another-base]);",
|
|
3647
|
+
"; multiclass.a",
|
|
3648
|
+
"# 1",
|
|
3649
|
+
"; multiclass.b",
|
|
3650
|
+
"# 2",
|
|
3651
|
+
"`````",
|
|
3652
|
+
"# Implementation",
|
|
3653
|
+
"",
|
|
3654
|
+
" Homoiconic C is available as the `hc` interpreter via the `hclang`",
|
|
3655
|
+
" node.js module, written in TypeScript.",
|
|
3656
|
+
"",
|
|
3657
|
+
"```console",
|
|
3658
|
+
"$ npm install -g hclang",
|
|
3659
|
+
'$ hc -e "“Hello, ” “Homoiconic C!”"',
|
|
3660
|
+
"```",
|
|
3661
|
+
"",
|
|
3662
|
+
"It is under active development, and available on GitHub[@Cite] under",
|
|
3663
|
+
"the MIT Open Source license.",
|
|
3664
|
+
"",
|
|
3665
|
+
"## Architecture",
|
|
3666
|
+
"",
|
|
3667
|
+
"The core runtime objects live in the `lib/frames` directory, where they",
|
|
3668
|
+
"are implemented as TypeScript classes. Generally speaking there is",
|
|
3669
|
+
"one class for each primitive and aggregate frame, plus abstract classes for",
|
|
3670
|
+
"the generic Frame, FrameAtom, and FrameList.",
|
|
3671
|
+
"",
|
|
3672
|
+
"The interpreter lives in the `lib/execute` directory, and is also",
|
|
3673
|
+
"implemented using frames. Every frame knows how it is represented, and",
|
|
3674
|
+
"the lexer uses that information to dynamically generate a lookup table",
|
|
3675
|
+
"from a list of frame classes. Strings iterate as a list of symbols, so",
|
|
3676
|
+
"the lexer generates tokens from the input string by evaluating",
|
|
3677
|
+
"evaluating a specialized program. Similarly, terminals act as controls",
|
|
3678
|
+
"grouping tokens into expressions and aggregates.",
|
|
3679
|
+
"",
|
|
3680
|
+
"Finally, operator bindings and currying are defined in `lib/ops`, and a",
|
|
3681
|
+
"preliminary wrapping of HTML called MAML lives in the `lib/maml` directory.",
|
|
3682
|
+
"",
|
|
3683
|
+
"## Status",
|
|
3684
|
+
"",
|
|
3685
|
+
"As of April 2017, the implementation is about 30% complete. We have",
|
|
3686
|
+
"implemented the core runtime frames and the parsing pipeline, and are",
|
|
3687
|
+
"able to evaluate simple expressions as arguments to the command-line.",
|
|
3688
|
+
"Supporting the remaining primitives and aggregates, as well as",
|
|
3689
|
+
"implementing a full REPL, should be fairly straightforward.",
|
|
3690
|
+
"",
|
|
3691
|
+
"To date we have only implemented a single operator, iteration over",
|
|
3692
|
+
"properties. This is enough to serve as a proof-of-concept, though it will",
|
|
3693
|
+
"undoubtedly need to be refactored to support the full range of operators.",
|
|
3694
|
+
"",
|
|
3695
|
+
"We have not yet begun to implement access control, though we have a high",
|
|
3696
|
+
"degree of confidence in the design based on previous prototypes. The design",
|
|
3697
|
+
"of the overall type system is somewhat less mature, especially where it overlaps",
|
|
3698
|
+
"with inheritance. This is also the case for the module system, which is still",
|
|
3699
|
+
"in the conceptual stage.",
|
|
3700
|
+
"",
|
|
3701
|
+
"## Next Steps",
|
|
3702
|
+
"",
|
|
3703
|
+
"### Documentation-Driven Development",
|
|
3704
|
+
"",
|
|
3705
|
+
"The first priority is obviously completing the interpreter. The main tool",
|
|
3706
|
+
"we plan to use to get there is enabling **executable documentation**.",
|
|
3707
|
+
"",
|
|
3708
|
+
"This document, for example, is written in a dialect of Markdown called",
|
|
3709
|
+
"Madoko[@Cite] which uses triple back-quotes (`` ``` ``) to delimit code",
|
|
3710
|
+
"fragments. We could invert that by having Homoiconic C use those quotes",
|
|
3711
|
+
"as the delimiters for doc-strings, so it can directly (and sequentially)",
|
|
3712
|
+
"evaluate the code fragments. Next, we add an input stage that tracks the",
|
|
3713
|
+
"raw source, and an output stage treats the semicolon-hashtag pairs as",
|
|
3714
|
+
"acceptance tests.",
|
|
3715
|
+
"",
|
|
3716
|
+
"Once that is in place, we can literally run our documentation simply by prefixing",
|
|
3717
|
+
"this file with:",
|
|
3718
|
+
"",
|
|
3719
|
+
"````hc",
|
|
3720
|
+
"#!/usr/bin/env hc -doctest",
|
|
3721
|
+
"```",
|
|
3722
|
+
"````",
|
|
3723
|
+
"",
|
|
3724
|
+
"The process would thus involve rewriting the documentation and",
|
|
3725
|
+
"the source code together until they are both complete and consistent.",
|
|
3726
|
+
"",
|
|
3727
|
+
"### Compilation",
|
|
3728
|
+
"",
|
|
3729
|
+
"Once the interpreter is finished, we plan to work on a self-hosting",
|
|
3730
|
+
"transpiler. Written in Homoiconic C, it would convert `.hc` files",
|
|
3731
|
+
"directly into executable JavaScript. This may be rather heavyweight,",
|
|
3732
|
+
"however, since all the JavaScript objects would be Frame",
|
|
3733
|
+
"instances.",
|
|
3734
|
+
"",
|
|
3735
|
+
"The second step would be compiling directly to `asm.js`[@Cite]/",
|
|
3736
|
+
"WebBinary[@Cite]. In particular, the goal would be to first wrap asm.js",
|
|
3737
|
+
'as a "congram" so that it can be easily manipulated directly from Homoiconic C.',
|
|
3738
|
+
"",
|
|
3739
|
+
"That experience would serve as a useful stepping stone towards a true",
|
|
3740
|
+
"native code compiler. Rather than simply using LLVM[@Cite], we would",
|
|
3741
|
+
"prefer to use that opportunity to reexamine the very nature of",
|
|
3742
|
+
"intermediate representations and assembly language. The theory underlying",
|
|
3743
|
+
'Homoiconic C suggests that "switching circuits" may do a better job of',
|
|
3744
|
+
"abstracting the underlying electronics than traditional von Neumann",
|
|
3745
|
+
"architectures[@Cite]. While admittedly a long shot, if successful it",
|
|
3746
|
+
"could enable dramatic breakthroughs in performance, power consumption,",
|
|
3747
|
+
"and hardware evolution.",
|
|
3748
|
+
"",
|
|
3749
|
+
"# Related Work",
|
|
3750
|
+
"",
|
|
3751
|
+
"## BitC",
|
|
3752
|
+
"",
|
|
3753
|
+
"Homoiconic C could be considered a reincarnation of the BitC[@BitC]",
|
|
3754
|
+
'project, which attempted to add a "bit of C" to Lisp in order to bring',
|
|
3755
|
+
"rigor to systems programming. As far as we know, they are the only group",
|
|
3756
|
+
"to have tackled the gap between the elegance of lambda calculus and",
|
|
3757
|
+
"efficient use of actual computing hardware. They appeared to have stalled",
|
|
3758
|
+
"due to a lack of funding, and also the difficultly of grafting a rich",
|
|
3759
|
+
"enough type system onto Lisp syntax.",
|
|
3760
|
+
"",
|
|
3761
|
+
"Homoiconic C hopes to avoid those problems through the pursuit of extreme",
|
|
3762
|
+
"simplicity. We start with a variant of the Lisp evaluation model",
|
|
3763
|
+
"explicitly designed to work with numbers and strings, not just lists.",
|
|
3764
|
+
"Next, we carefully design our identifiers to encode the critical",
|
|
3765
|
+
'information needed for "sound and complete type inference" across',
|
|
3766
|
+
"invocation boundaries. Finally, we leverage Open Source to bootstrap the",
|
|
3767
|
+
"project so that we are not dependent on external funding.",
|
|
3768
|
+
"",
|
|
3769
|
+
"## Julia",
|
|
3770
|
+
"",
|
|
3771
|
+
"Though developed independently, Homoiconic C shares many goals and features",
|
|
3772
|
+
"with the emerging Julia[@Julia] language for numerical computing:",
|
|
3773
|
+
"* multiple dispatch",
|
|
3774
|
+
"* homoiconicity, macros, and meta-programming",
|
|
3775
|
+
"* a type system optimized for performance",
|
|
3776
|
+
"",
|
|
3777
|
+
"We admire and hope to emulate Julia's achievements, particularly in terms",
|
|
3778
|
+
"of interoperability with existing languages and creative support for",
|
|
3779
|
+
"concurrency. Though Julia is currently far ahead in terms of both",
|
|
3780
|
+
"implementation and ecosystem, we believe that HC's use of BitC's type",
|
|
3781
|
+
"system plus the extreme simplicity of the syntax and implementation will",
|
|
3782
|
+
"still enable us to provide a compelling alternative.",
|
|
3783
|
+
"",
|
|
3784
|
+
"## Mathematica",
|
|
3785
|
+
"",
|
|
3786
|
+
"The most widely used homoiconic language in use today is probably",
|
|
3787
|
+
"Mathematica [@Mathematica]. However, despite several notable attempts to",
|
|
3788
|
+
"broaden its reach, Mathematica remains primarily a prototyping tool",
|
|
3789
|
+
"within Wolfram's products rather than remains primarily a prototyping",
|
|
3790
|
+
"tool within Wolfram's products rather than a general-purpose language[@MathematicaPrototype].",
|
|
3791
|
+
"",
|
|
3792
|
+
"## STEPS",
|
|
3793
|
+
"",
|
|
3794
|
+
"Homoiconic C was also inspired by and shares many goals with Alan Kay's",
|
|
3795
|
+
"ambitious STEPS [@STEPS] project for reinventing programming. From our",
|
|
3796
|
+
"perspective, the tragic flaw with his approach was starting from the",
|
|
3797
|
+
"(admittedly ubiquitous) assumption that computation should be built upon",
|
|
3798
|
+
"mathematics. Despite a promising start at replacing operating systems",
|
|
3799
|
+
"with a robust language runtime, the project appeared to eventually",
|
|
3800
|
+
"collapse under the weight of its leaky abstractions.",
|
|
3801
|
+
"",
|
|
3802
|
+
"We believe it is possible to achieve his dream by building on a different",
|
|
3803
|
+
'foundation. Rather than the traditional mantra of "Sequence, Selection,',
|
|
3804
|
+
'and Repetition", Homoiconic C is build around "Dependency, Effect, and',
|
|
3805
|
+
'Interrupts." We believe this choice of basis enables us to generate',
|
|
3806
|
+
'"leak-proof" abstractions that scale seamlessly from individual circuits to complex distributed',
|
|
3807
|
+
"platforms.",
|
|
3808
|
+
"",
|
|
3809
|
+
"## Water",
|
|
3810
|
+
"",
|
|
3811
|
+
"The idea of expressing programs in a data format is not in itself new. A",
|
|
3812
|
+
"relatively modern attempt was Water[@Water], which attempted to program",
|
|
3813
|
+
"web applications using a more concise variant of XML. Though extremely",
|
|
3814
|
+
"clever, it suffered not just from the awkwardness of XML as a data",
|
|
3815
|
+
"format, but from the use of existing imperative programming paradigms.",
|
|
3816
|
+
"",
|
|
3817
|
+
"HC plan to avoid that fate by adopting the more streamlined dataflow paradigm,",
|
|
3818
|
+
"supported by a custom-designed data format optimized for readability.",
|
|
3819
|
+
"",
|
|
3820
|
+
"",
|
|
3821
|
+
"# Conclusion",
|
|
3822
|
+
"",
|
|
3823
|
+
"We believe the historical accident of confusing computation with",
|
|
3824
|
+
"mathematics and programming with natural languages has resulted in",
|
|
3825
|
+
"massive accidental complexity. We believe this is a primary cause of the",
|
|
3826
|
+
"buggy software, complicated tools, and steep learning curve that plague software",
|
|
3827
|
+
"engineering today.",
|
|
3828
|
+
"",
|
|
3829
|
+
"By eliminated that complexity, Homoiconic C hopes to usher in a new",
|
|
3830
|
+
"Golden Age of software that is:",
|
|
3831
|
+
"* Inherently and provably secure",
|
|
3832
|
+
"* Both inherently efficient and easily optimized",
|
|
3833
|
+
"* Easy to learn, read, and modify",
|
|
3834
|
+
"* Trivial to statically analyze, visualize, and automatically evolve",
|
|
3835
|
+
"",
|
|
3836
|
+
"If Homoiconic C fulfills that promise, we can finally make programming an",
|
|
3837
|
+
"everyday skill, used by ordinary people (even children) to solve the",
|
|
3838
|
+
"problems *they* care about, in the same way they use writing and",
|
|
3839
|
+
"arithmetic. Not everyone will be an expert or professional programmer --",
|
|
3840
|
+
"anymore than everyone who sings is an expert or professional musician --",
|
|
3841
|
+
"but the ability to read, understand, and personalize code will be",
|
|
3842
|
+
"available to all.",
|
|
3843
|
+
"",
|
|
3844
|
+
"It may be true that there is no silver bullet[@Cite]. But we believe",
|
|
3845
|
+
'Homoiconic C can at least be a "diamond sword", enabling courageous individuals',
|
|
3846
|
+
"to bring safety, performance, usability, and clarity to the software that",
|
|
3847
|
+
"impacts their corner of the world. We hope you will join us on that quest.",
|
|
3848
|
+
"",
|
|
3849
|
+
"",
|
|
3850
|
+
"# Appendices",
|
|
3851
|
+
"",
|
|
3852
|
+
"## Appendix A. On Turing Completeness",
|
|
3853
|
+
"",
|
|
3854
|
+
"Turing undecidability, like Godelian incompleteness, starts by assuming",
|
|
3855
|
+
'"basic arithmetic" (add, subtract, multiply, divide) -- i.e. the Peano',
|
|
3856
|
+
'Axioms. However, this glosses over the fact that division is a "type',
|
|
3857
|
+
"violation\", and can't be fully represented using the same data structures",
|
|
3858
|
+
"as for addition and subtraction.",
|
|
3859
|
+
"",
|
|
3860
|
+
"We believe that a better starting point for modeling computation are the",
|
|
3861
|
+
"Presburger Axioms. These give up multiplication and division as",
|
|
3862
|
+
"first-class operations (though you can emulate them to some extent using",
|
|
3863
|
+
"repeated addition and subtraction, respectively). The big win, though, is",
|
|
3864
|
+
"that Presburger arithmetic is both consistent **and** complete. This",
|
|
3865
|
+
"eliminates the halting problem, and massively simplifies analyses (though",
|
|
3866
|
+
"it may restrict what is possible).",
|
|
3867
|
+
"",
|
|
3868
|
+
'Instead of Turing completeness, we prefer to focus on "Circuit',
|
|
3869
|
+
'Universality" (a la Scott Aaronson): the ability to represent the effect',
|
|
3870
|
+
"of any Boolean circuit, including multiple levels of abstraction above",
|
|
3871
|
+
"them.",
|
|
3872
|
+
"",
|
|
3873
|
+
"[BIB]",
|
|
3874
|
+
"`````",
|
|
3875
|
+
"",
|
|
3876
|
+
].join("\n"),
|
|
3877
|
+
],
|
|
3878
|
+
]);
|