1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
|
<head>
<link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
<link href="../style.css" rel="stylesheet"/>
<title>Specification: BQN system-provided values</title>
</head>
<div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">spec</a></div>
<h1 id="specification-bqn-system-provided-values"><a class="header" href="#specification-bqn-system-provided-values">Specification: BQN system-provided values</a></h1>
<p>This portion of the spec is still potentially subject to major changes.</p>
<p>The <code><span class='Value'>•</span></code> symbol is used to access values other than primitives provided by BQN.</p>
<p>All system values described in the BQN specification are optional: an implementation does not have to include any of them. However, if a system value with one of the names given below is included, then it must have the specified behavior. For namespaces this rule applies to individual fields as well: a namespace may be provided with only some of the fields, but a field with one of the given names must behave as specified.</p>
<h2 id="execution"><a class="header" href="#execution">Execution</a></h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•BQN</span></code></td>
<td>Evaluate the argument string in an isolated scope</td>
</tr>
<tr>
<td><code><span class='Function'>•ReBQN</span></code></td>
<td>Create a BQN-like evaluation function with options <code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Value'>•primitives</span></code></td>
<td>List of primitives as glyph-value pairs</td>
</tr>
</tbody>
</table>
<p>The left argument to <code><span class='Function'>•BQN</span></code> or the result of <code><span class='Function'>•ReBQN</span></code>, if given, is a list of up to three elements, giving a prefix of <code><span class='Value'>•state</span></code> (see next section) during evaluations of that function. Thus <code><span class='Bracket'>⟨</span><span class='String'>""</span><span class='Separator'>,</span><span class='String'>"xyz"</span><span class='Bracket'>⟩</span><span class='Function'>•BQN</span><span class='String'>"•name"</span></code> returns <code><span class='String'>"xyz"</span></code>.</p>
<p><code><span class='Function'>•ReBQN</span></code> accepts a namespace <code><span class='Value'>𝕩</span></code>. The following options are specified if supported:</p>
<table>
<thead>
<tr>
<th>Option</th>
<th>Values (default first)</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Value'>repl</span></code></td>
<td><code><span class='String'>"none"</span></code>, <code><span class='String'>"strict"</span></code>, <code><span class='String'>"loose"</span></code></td>
</tr>
<tr>
<td><code><span class='Value'>primitives</span></code></td>
<td>List of glyph-value pairs; default <code><span class='Value'>•primitives</span></code></td>
</tr>
<tr>
<td><code><span class='Value'>system</span></code></td>
<td><code><span class='String'>"all"</span></code>, <code><span class='String'>"none"</span></code>, <code><span class='String'>"safe"</span></code> or list of names</td>
</tr>
<tr>
<td><code><span class='Value'>scope</span></code></td>
<td><code><span class='String'>"none"</span></code>, <code><span class='String'>"read"</span></code>, <code><span class='String'>"modify"</span></code> or list of name-setting pairs</td>
</tr>
</tbody>
</table>
<p>The option <code><span class='Value'>repl</span></code> indicates how variables are retained across calls: with "none" they are not saved; with "strict", they are saved and can't be redefined; and with "loose" they may be redefined. Each element in <code><span class='Value'>primitives</span></code> gives the glyph and value for a primitive to be made available. The value must have an operation type and its type determines the primitive's role. <code><span class='Value'>system</span></code> in general gives the list of system values to be made available, with shorthand values to indicate all currently-available ones, none of them, or only a subset that cannot be used to interact with anything outside of the execution context. <code><span class='Value'>scope</span></code> indicates allowed interaction with the scope in which <code><span class='Function'>•ReBQN</span></code> is <em>called</em> (not loaded): with "read" variables may be read and with "modify" they may be read or modified.</p>
<h2 id="scripts"><a class="header" href="#scripts">Scripts</a></h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•Import</span></code></td>
<td>Load a script file</td>
</tr>
<tr>
<td><code><span class='Value'>•state</span></code></td>
<td><code><span class='Bracket'>⟨</span><span class='Value'>•path</span><span class='Separator'>,</span> <span class='Value'>•name</span><span class='Separator'>,</span> <span class='Value'>•args</span><span class='Bracket'>⟩</span></code></td>
</tr>
<tr>
<td><code><span class='Value'>•args</span></code></td>
<td>Arguments passed to current file</td>
</tr>
<tr>
<td><code><span class='Value'>•path</span></code></td>
<td>Current file's path</td>
</tr>
<tr>
<td><code><span class='Value'>•name</span></code></td>
<td>Current filename</td>
</tr>
<tr>
<td><code><span class='Value'>•wdpath</span></code></td>
<td>Shell's working directory path</td>
</tr>
<tr>
<td><code><span class='Function'>•Exit</span></code></td>
<td>Leave the top-level running program</td>
</tr>
</tbody>
</table>
<p><code><span class='Function'>•Import</span></code> loads another BQN script. The script is evaluated in its own isolated scope, and its result is either the result of the last line, or a module if it exports with <code><span class='Gets'>⇐</span></code> at the top level. If it is a module, then it must be destructured immediately unless first-class namespaces are possible.</p>
<p>The right argument is a filename, which may be relative or absolute. Relative paths are taken relative to the source file where this instance of <code><span class='Function'>•Import</span></code> was written. The left argument, if given, is the list of arguments that should be passed through to the file as <code><span class='Value'>•args</span></code>. If no left argument is given then <code><span class='Bracket'>⟨⟩</span></code> is used for <code><span class='Value'>•args</span></code>. However, the behavior is different in this case. The same file will only be loaded once in a given BQN program by <code><span class='Function'>•Import</span></code> calls with no left argument: the first such call saves the returned value, even if it is mutable, and subsequent calls return this saved value. To avoid this and reload the file, pass a left argument of <code><span class='Bracket'>⟨⟩</span></code>.</p>
<p><code><span class='Value'>•args</span></code> is the arguments passed as the file was invoked, either from the command line or <code><span class='Function'>•Import</span></code>. For command line calls it is a list of strings.</p>
<p><code><span class='Value'>•path</span></code> simply gives the path of the file in which it appears. It includes a trailing slash but not the name of the file itself.</p>
<p><code><span class='Value'>•name</span></code> gives the name, including the extension, of the file in which it appears. It doesn't include the path.</p>
<p><code><span class='Value'>•wdpath</span></code> returns the path of the current working directory, like the Unix <code><span class='Value'>pwd</span></code> command, but including a trailing slash.</p>
<p><code><span class='Function'>•Exit</span></code> immediately terminates the running BQN process. If the argument is a valid return code (on Unix, an integer), it is returned; otherwise, the default return code (the one returned when the end of the program is reached) is used.</p>
<h2 id="files"><a class="header" href="#files">Files</a></h2>
<p>The system namespace value <code><span class='Value'>•file</span></code> deals with file operations. For the purposes of <code><span class='Value'>•file</span></code>, paths in the filesystem are always strings. As with <code><span class='Function'>•Import</span></code>, file paths may be relative or absolute, and relative paths are relative to <code><span class='Value'>•path</span></code>, except in <code><span class='Value'>•file.</span><span class='Function'>At</span></code> which allows <code><span class='Value'>𝕨</span></code> to specify an alternate base directory. The value <code><span class='Value'>•path</span></code> used for a particular instance of <code><span class='Value'>•file</span></code> is determined by the file that contains that instance.</p>
<p>When a <code><span class='Value'>•file</span></code> function returns a file path or portion of a path, the path is always absolute and canonical, with <code><span class='Value'>.</span></code> and <code><span class='Value'>..</span></code> components removed.</p>
<p>Possible fields of <code><span class='Value'>•file</span></code> are given in the subsections below.</p>
<h3 id="file-paths"><a class="header" href="#file-paths">File paths</a></h3>
<p>The following functions manipulate paths and don't access files. Each takes a relative or absolute path <code><span class='Value'>𝕩</span></code>, and <code><span class='Function'>At</span></code> may also take a base directory <code><span class='Value'>𝕨</span></code>.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Value'>path</span></code></td>
<td>Path of this source file, that is, <code><span class='Value'>•path</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>At</span></code></td>
<td>Absolute path of file, with optional base <code><span class='Value'>𝕨</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Name</span></code></td>
<td>File name including extension</td>
</tr>
<tr>
<td><code><span class='Function'>Parent</span></code></td>
<td>Path of the containing directory, with trailing backslash</td>
</tr>
<tr>
<td><code><span class='Function'>BaseName</span></code></td>
<td>File name, with dot and extension removed</td>
</tr>
<tr>
<td><code><span class='Function'>Extension</span></code></td>
<td>File extension, including leading dot</td>
</tr>
<tr>
<td><code><span class='Function'>Parts</span></code></td>
<td>List of parent, base name, and extension</td>
</tr>
</tbody>
</table>
<h3 id="file-metadata"><a class="header" href="#file-metadata">File metadata</a></h3>
<p>Metadata functions may query information about a file or directory but do not read to or write from it. Each takes a path <code><span class='Value'>𝕩</span></code>, and some functions also allow new data in <code><span class='Value'>𝕨</span></code>. The returned data in any case is the specified property.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>Exists</span></code></td>
<td><code><span class='Number'>1</span></code> if the file exists and <code><span class='Number'>0</span></code> otherwise</td>
</tr>
<tr>
<td><code><span class='Function'>Type</span></code></td>
<td>A character indicating the file's type</td>
</tr>
<tr>
<td><code><span class='Function'>Created</span></code></td>
<td>Time created</td>
</tr>
<tr>
<td><code><span class='Function'>Accessed</span></code></td>
<td>Time of last access</td>
</tr>
<tr>
<td><code><span class='Function'>Modified</span></code></td>
<td>Time of last modification</td>
</tr>
<tr>
<td><code><span class='Function'>Size</span></code></td>
<td>Total size in bytes</td>
</tr>
<tr>
<td><code><span class='Function'>Permissions</span></code></td>
<td>Query or set file permissions</td>
</tr>
<tr>
<td><code><span class='Function'>Owner</span></code></td>
<td>Query or set owner user ID and group ID number</td>
</tr>
</tbody>
</table>
<p>Times are Unix timestamps, that is, non-leap seconds since the Unix epoch, as used by <a href="#time">time</a> system values. File permissions on Unix are a three-element list of numbers giving the permissions for the owner, group, and other users. The file type is one of the following characters for the POSIX file types, matching Unix <code><span class='Value'>ls</span> <span class='Function'>-</span><span class='Value'>l</span></code> with <code><span class='String'>'f'</span></code> instead of <code><span class='String'>'-'</span></code>.</p>
<ul>
<li><code><span class='String'>'f'</span></code>: File</li>
<li><code><span class='String'>'d'</span></code>: Directory</li>
<li><code><span class='String'>'l'</span></code>: Symlink</li>
<li><code><span class='String'>'p'</span></code>: Pipe (FIFO)</li>
<li><code><span class='String'>'s'</span></code>: Socket</li>
<li><code><span class='String'>'b'</span></code>: Block device</li>
<li><code><span class='String'>'c'</span></code>: Character device</li>
</ul>
<h3 id="file-access"><a class="header" href="#file-access">File access</a></h3>
<p>File access functions read or write files, either by manipulating files as a whole or interacting with the contents. Whole-file functions cannot overwrite target files: that is, <code><span class='Function'>Rename</span></code> and <code><span class='Function'>Copy</span></code> must give an error if a file exists at <code><span class='Value'>𝕨</span></code>, and <code><span class='Function'>CreateDir</span></code> if a file exists at <code><span class='Value'>𝕩</span></code>, while <code><span class='Function'>Chars</span></code>, <code><span class='Function'>Lines</span></code>, and <code><span class='Function'>Bytes</span></code> can overwrite the contents of an existing file <code><span class='Value'>𝕨</span></code>. However, these three functions must give an error if <code><span class='Value'>𝕨</span></code> exists and is a directory.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>Open</span></code></td>
<td>Return an open file object based on <code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Rename</span></code></td>
<td>Rename file <code><span class='Value'>𝕩</span></code> with path <code><span class='Value'>𝕨</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Copy</span></code></td>
<td>Copy file <code><span class='Value'>𝕩</span></code> to path <code><span class='Value'>𝕨</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>CreateDir</span></code></td>
<td>Create a directory at path <code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Remove</span></code></td>
<td>Delete file <code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>RemoveDir</span></code></td>
<td>Recursively delete directory <code><span class='Value'>𝕩</span></code> and all contents</td>
</tr>
<tr>
<td><code><span class='Function'>List</span></code></td>
<td>Return names of all files in directory <code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Chars</span></code></td>
<td>Read from or write to entire file, as characters</td>
</tr>
<tr>
<td><code><span class='Function'>Lines</span></code></td>
<td>Read from or write to entire file, as lines</td>
</tr>
<tr>
<td><code><span class='Function'>Bytes</span></code></td>
<td>Read from or write to entire file, as bytes</td>
</tr>
</tbody>
</table>
<p><code><span class='Function'>Rename</span></code>, <code><span class='Function'>Copy</span></code>, and <code><span class='Function'>CreateDir</span></code> return the path of the new file. <code><span class='Function'>Remove</span></code> and <code><span class='Function'>RemoveDir</span></code> return <code><span class='Number'>1</span></code> to indicate successful removal (and error otherwise).</p>
<p><code><span class='Function'>List</span></code> returns filenames only, without full paths. It lists all files and directories including hidden ones, but not the current and parent directory names <code><span class='Value'>.</span></code> and <code><span class='Value'>..</span></code>.</p>
<p>Functions <code><span class='Function'>Chars</span></code>, <code><span class='Function'>Lines</span></code>, and <code><span class='Function'>Bytes</span></code> are all ambivalent. If only <code><span class='Value'>𝕩</span></code> is given, then it is a filename, and the result is the contents of the file in the appropriate format. If there are two arguments, then <code><span class='Value'>𝕨</span></code> is the filename and <code><span class='Value'>𝕩</span></code> is the desired contents. These are written to the file, overwriting its contents, and the absolute filename <code><span class='Value'>𝕨</span></code> is returned. The three formats are:</p>
<ul>
<li>Chars: BQN characters, or UTF-32. The file is assumed to be UTF-8 encoded.</li>
<li>Lines: BQN strings. The file is decoded as with chars, then split into lines by CR, LR, or CRLF line endings.</li>
<li>Bytes: Single-byte values, stored as BQN characters from <code><span class='String'>@</span></code> to <code><span class='String'>@</span><span class='Function'>+</span><span class='Number'>255</span></code>.</li>
</ul>
<p>The following short names can also be provided for file access. They can be provided, and use the definitions from above even if <code><span class='Value'>•file</span></code> is not provided.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Equivalent</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•FChars</span></code></td>
<td><code><span class='Value'>•file.</span><span class='Function'>Chars</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>•FLines</span></code></td>
<td><code><span class='Value'>•file.</span><span class='Function'>Lines</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>•FBytes</span></code></td>
<td><code><span class='Value'>•file.</span><span class='Function'>Bytes</span></code></td>
</tr>
</tbody>
</table>
<h3 id="open-file-object"><a class="header" href="#open-file-object">Open file object</a></h3>
<h2 id="input-and-output"><a class="header" href="#input-and-output">Input and output</a></h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•Out</span></code></td>
<td>Print argument string</td>
</tr>
<tr>
<td><code><span class='Function'>•Show</span></code></td>
<td>Print argument value</td>
</tr>
<tr>
<td><code><span class='Function'>•Repr</span></code></td>
<td>String representation of <code><span class='Value'>𝕩</span></code>, if possible</td>
</tr>
<tr>
<td><code><span class='Function'>•Fmt</span></code></td>
<td>Format value for printing</td>
</tr>
</tbody>
</table>
<p><code><span class='Function'>•Out</span></code> prints a string to stdout, with a trailing newline. <code><span class='Function'>•Show</span></code> displays a BQN value to the programmer (the representation is not specified, and does not need to be plain text). <code><span class='Function'>•Fmt</span></code> returns a string (not a character table: lines are separated by linefeeds) indicating how <code><span class='Value'>𝕩</span></code> would be printed by the interactive environment. Both <code><span class='Function'>•Show</span></code> and <code><span class='Function'>•Fmt</span></code> may take a left argument configuring how the value should be formatted.</p>
<p><code><span class='Function'>•Repr</span></code> attempts to return a string so that <code><span class='Function'>•BQN</span> <span class='Function'>•Repr</span> <span class='Value'>𝕩</span></code> matches <code><span class='Value'>𝕩</span></code>. If <code><span class='Value'>𝕩</span></code> contains any mutable values (operations or namespaces), this is not possible. However, if such a values is stateless, in the sense that they don't access variables outside of their own scopes, it is permissible for <code><span class='Function'>•Repr</span></code> to return source code that would create a value with identical behavior.</p>
<h2 id="interface"><a class="header" href="#interface">Interface</a></h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•SH</span></code></td>
<td>Execute shell command and return <code><span class='Value'>exitcode</span><span class='Ligature'>‿</span><span class='Value'>stdout</span><span class='Ligature'>‿</span><span class='Value'>stderr</span></code></td>
</tr>
</tbody>
</table>
<p>The argument to <code><span class='Function'>•SH</span></code> is a list of strings giving the command and its arguments (for example <code><span class='String'>"mv"</span><span class='Ligature'>‿</span><span class='String'>"old"</span><span class='Ligature'>‿</span><span class='String'>"new"</span></code>). The command is executed synchronously, and the result is a list of three elements: the command's exit code, text written to stdout, and text written to stderr. In both cases the text is a plain string containing all text emitted by the program. Text is interpreted as UTF-8, with an error if it's not valid UTF-8.</p>
<h2 id="operation-properties"><a class="header" href="#operation-properties">Operation properties</a></h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•Type</span></code></td>
<td>Return a number indicating type</td>
</tr>
<tr>
<td><code><span class='Function'>•Glyph</span></code></td>
<td>Return the glyph for a primitive</td>
</tr>
<tr>
<td><code><span class='Function'>•Source</span></code></td>
<td>Return the source of a block, as a string</td>
</tr>
<tr>
<td><code><span class='Function'>•Decompose</span></code></td>
<td>Show the parts of a compound function</td>
</tr>
</tbody>
</table>
<p>Each function in this section is monadic.</p>
<p><code><span class='Function'>•Type</span></code> gives its argument's type, as a number from the table below:</p>
<table>
<thead>
<tr>
<th>Number</th>
<th>Type</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>Array</td>
</tr>
<tr>
<td>1</td>
<td>Number</td>
</tr>
<tr>
<td>2</td>
<td>Character</td>
</tr>
<tr>
<td>3</td>
<td>Function</td>
</tr>
<tr>
<td>4</td>
<td>1-modifier</td>
</tr>
<tr>
<td>5</td>
<td>2-modifier</td>
</tr>
<tr>
<td>6</td>
<td>Namespace</td>
</tr>
</tbody>
</table>
<p><code><span class='Function'>•Glyph</span></code> gives the glyph corresponding to a primitive as a single character, for example returning <code><span class='String'>'+'</span></code> given an argument matching <code><span class='Function'>+</span></code>. It causes an error if the argument is not a primitive.</p>
<p><code><span class='Function'>•Source</span></code> gives a string containing a block's source, including the enclosing braces <code><span class='Brace'>{}</span></code>. It causes an error if the argument is not a block. In contrast to <code><span class='Function'>•Glyph</span></code>, this function does not give full information about <code><span class='Value'>𝕩</span></code> because the result cannot convey environment or mutable identity.</p>
<p><code><span class='Function'>•Decompose</span></code> breaks down one level of a compound function, returning a list with a code giving what kind of structure it has followed by each of its components. Possible codes are listed in the table below according to the rule that forms the derived function—train or 2-modifier application. Non-function values, and some functions, can't be broken down. They are still classified with a code: -1 for a non-operation, 0 for a primitive, and 1 for other operations. "Other" includes blocks and system operations. The result is thus a list of length 2 to 4, and <code><span class='Function'>•Decompose</span></code> cannot cause an error.</p>
<table>
<thead>
<tr>
<th>Kind</th>
<th>Code</th>
<th>Components</th>
</tr>
</thead>
<tbody>
<tr>
<td>Non-operation</td>
<td>-1</td>
<td><code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td>Primitive</td>
<td>0</td>
<td><code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td>Other</td>
<td>1</td>
<td><code><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td>2-train</td>
<td>2</td>
<td><code> <span class='Value'>g</span><span class='Separator'>,</span><span class='Value'>h</span></code></td>
</tr>
<tr>
<td>3-train</td>
<td>3</td>
<td><code><span class='Value'>f</span><span class='Separator'>,</span><span class='Value'>g</span><span class='Separator'>,</span><span class='Value'>h</span></code></td>
</tr>
<tr>
<td>1-mod</td>
<td>4</td>
<td><code><span class='Value'>𝕗</span><span class='Separator'>,</span><span class='Value'>𝕣</span></code></td>
</tr>
<tr>
<td>2-mod</td>
<td>5</td>
<td><code><span class='Value'>𝕗</span><span class='Separator'>,</span><span class='Value'>𝕣</span><span class='Separator'>,</span><span class='Value'>𝕘</span></code></td>
</tr>
</tbody>
</table>
<h2 id="time"><a class="header" href="#time">Time</a></h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•UnixTime</span></code></td>
<td>Time between Unix epoch and function call</td>
</tr>
<tr>
<td><code><span class='Function'>•MonoTime</span></code></td>
<td>Monotonically-increasing time counter for relative measurement</td>
</tr>
<tr>
<td><code><span class='Function'>•Delay</span></code></td>
<td>Wait at least <code><span class='Value'>𝕩</span></code> seconds, and return the actual wait time</td>
</tr>
<tr>
<td><code><span class='Modifier'>•_timed</span></code></td>
<td>Call <code><span class='Function'>𝔽</span></code> on <code><span class='Value'>𝕩</span></code> <code><span class='Value'>𝕨</span><span class='Function'>⊣</span><span class='Number'>1</span></code> times, and return the average duration</td>
</tr>
<tr>
<td><code><span class='Modifier2'>•_maxTime_</span></code></td>
<td>Call <code><span class='Function'>𝔽</span></code> on the arguments, but fail if it takes over <code><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span></code> seconds</td>
</tr>
</tbody>
</table>
<p>All times are measured in seconds.</p>
<p>The <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a> is 1970-01-01 00:00:00 UTC, and <a href="https://en.wikipedia.org/wiki/Unix_time">Unix time</a> is the number of seconds since this epoch, with adjustments for leap seconds. <code><span class='Function'>•UnixTime</span></code> is intended for absolute time measurement and should use the source most accurate reflects Unix time when it's called. <code><span class='Function'>•MonoTime</span></code> is intended for relative measurement and should use the method that gives the most precise time differences over the course of the program. Its return value must never decrease between calls.</p>
<p><code><span class='Modifier'>•_timed</span></code> returns the total time taken divided by the number of function calls (<code><span class='Value'>𝕨</span></code> if provided and 1 otherwise), including the overhead required for the outer loop that counts iterations (which will typically be negligible in comparison to the BQN code).</p>
<p>More accurately the modifier <code><span class='Modifier2'>•_maxTime_</span></code> <em>may</em> fail if execution of <code><span class='Function'>𝔽</span></code> takes over <code><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span></code> seconds, and should fail as quickly as it is practically able to. The most likely way to implement this modifier is to interrupt execution at the given time. If <code><span class='Function'>𝔽</span></code> completes before the interrupt there is no need to measure the amount of time it actually took.</p>
<h2 id="math"><a class="header" href="#math">Math</a></h2>
<p>System namespace <code><span class='Value'>•math</span></code> contains mathematical utilities that are not easily implemented with basic arithmetic, analogous to C's <code><span class='Value'>math.h</span></code>.</p>
<p>Constants <code><span class='Value'>ln10</span><span class='Gets'>⇐</span><span class='Function'>⋆</span><span class='Modifier'>⁼</span><span class='Number'>10</span></code>, <code><span class='Value'>ln2</span><span class='Gets'>⇐</span><span class='Function'>⋆</span><span class='Modifier'>⁼</span><span class='Number'>2</span></code>, <code><span class='Value'>log10e</span><span class='Gets'>⇐</span><span class='Function'>÷⋆</span><span class='Modifier'>⁼</span><span class='Number'>10</span></code>, <code><span class='Value'>log2e</span><span class='Gets'>⇐</span><span class='Function'>÷⋆</span><span class='Modifier'>⁼</span><span class='Number'>2</span></code> computed in full precision.</p>
<p>Other correctly-rounded arithmetic: monadic <code><span class='Function'>Cbrt</span><span class='Gets'>⇐</span><span class='Number'>3</span><span class='Modifier2'>⊸</span><span class='Function'>√</span></code>, <code><span class='Function'>Log2</span><span class='Gets'>⇐</span><span class='Number'>2</span><span class='Function'>⋆</span><span class='Modifier'>⁼</span><span class='Function'>⊢</span></code>, <code><span class='Function'>Log10</span><span class='Gets'>⇐</span><span class='Number'>10</span><span class='Function'>⋆</span><span class='Modifier'>⁼</span><span class='Function'>⊢</span></code>, <code><span class='Function'>Log1p</span><span class='Gets'>⇐</span><span class='Function'>⋆</span><span class='Modifier'>⁼</span><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>+</span></code>, <code><span class='Function'>Expm1</span><span class='Gets'>⇐</span><span class='Number'>1</span><span class='Function'>-</span><span class='Modifier'>˜</span><span class='Function'>⋆</span></code>; dyadic <code><span class='Function'>Hypot</span><span class='Gets'>⇐</span><span class='Function'>+</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Function'>×</span><span class='Modifier'>˜</span><span class='Paren'>)</span></code>.</p>
<p>Standard trigonometric functions <code><span class='Function'>Sin</span></code>, <code><span class='Function'>Cos</span></code>, <code><span class='Function'>Tan</span></code>, <code><span class='Function'>Sinh</span></code>, <code><span class='Function'>Cosh</span></code>, <code><span class='Function'>Tanh</span></code>, with inverses preceded by <code><span class='Value'>a</span></code> (<code><span class='Function'>ASin</span></code>, etc.) and accessable with <code><span class='Modifier'>⁼</span></code>. Additionally, the dyadic function <code><span class='Function'>ATan2</span></code> giving the angle of vector <code><span class='Value'>𝕨</span><span class='Ligature'>‿</span><span class='Value'>𝕩</span></code> relative to <code><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span></code>. All trig functions measure angles in radians.</p>
<h2 id="random-generation"><a class="header" href="#random-generation">Random generation</a></h2>
<p><code><span class='Function'>•MakeRand</span></code> initializes a deterministic pseudorandom number generator with seed value <code><span class='Value'>𝕩</span></code>. <code><span class='Value'>•rand</span></code>, if it exists, is a globally accessible generator initialized at first use; this initialization should use randomness from an outside source if available. These random generators aren't required to be cryptographically secure and should always be treated as insecure. A random generator has the following member functions:</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>Range</span></code></td>
<td>A number, or array of shape <code><span class='Value'>𝕨</span></code>, selected from <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Deal</span></code></td>
<td>A simple random sample of <code><span class='Value'>𝕨</span><span class='Function'>⊣</span><span class='Value'>𝕩</span></code> elements of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code></td>
</tr>
<tr>
<td><code><span class='Function'>Subset</span></code></td>
<td>A sorted SRS of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code>, with <code><span class='Value'>𝕨</span></code> elements if given</td>
</tr>
</tbody>
</table>
<p>For each of these functions, <code><span class='Value'>𝕩</span></code> is a natural number. For <code><span class='Function'>Range</span></code>, <code><span class='Value'>𝕨</span></code> must be a valid shape (natural number, or list or unit array of natural numbers) if given, and for <code><span class='Function'>Deal</span></code> and <code><span class='Function'>Subset</span></code> it's a natural number less than or equal to <code><span class='Value'>𝕩</span></code>. All selections are made uniformly at random, that is, each possible result is equally likely. A simple random sample (SRS) of <code><span class='Value'>k</span></code> elements from list <code><span class='Value'>s</span></code> is a list of <code><span class='Value'>k</span></code> distinct elements of <code><span class='Value'>s</span></code> in any order. Both the choice of elements and their ordering must be uniformly random. <a href="../implementation/primitive/random.html#simple-random-sample">Recommended algorithms</a> for SRS selection are variants of a partial Knuth shuffle.</p>
<p>When <code><span class='Value'>𝕨</span></code> isn't given, <code><span class='Function'>Deal</span></code>'s result contains all elements of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code>, making it a random shuffle of those values, or random permutation. In <code><span class='Function'>Subset</span></code>, a random choice is made uniformly from the <code><span class='Number'>2</span><span class='Function'>⋆</span><span class='Value'>𝕩</span></code> subsets of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code>, so that a subset of any length may be returned.</p>
<p>In <code><span class='Function'>Range</span></code>, <code><span class='Value'>𝕩</span></code> may be <code><span class='Number'>0</span></code>. In this case the result consists of floating-point numbers in the unit interval from 0 to 1. The numbers should have an overall uniform distribution, but their precision and whether the endpoints 0 and 1 are possible may depend on the implementation.</p>
<p>Ranges up to <code><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>32</span></code> must be supported (that is, a maximum integer result of <code><span class='Paren'>(</span><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>32</span><span class='Paren'>)</span><span class='Function'>-</span><span class='Number'>1</span></code>) if the number system accommodates it. In implementations based on double-precision floats it's preferable but not required to support ranges up to <code><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>53</span></code>.</p>
<h2 id="bitwise-operations"><a class="header" href="#bitwise-operations">Bitwise operations</a></h2>
<p>The system namespace <code><span class='Value'>•bits</span></code> gives functions for efficiently applying bitwise and two's complement integer operations to arrays of data. These functions should compute result values with native CPU instructions, preferably SIMD if available.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Args</th>
<th>Type</th>
<th>Behavior</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Modifier'>_not</span></code></td>
<td>1</td>
<td>bit</td>
<td><code><span class='Function'>¬</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_and</span></code></td>
<td>2</td>
<td>bit</td>
<td><code><span class='Function'>∧</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_or</span></code></td>
<td>2</td>
<td>bit</td>
<td><code><span class='Function'>∨</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_xor</span></code></td>
<td>2</td>
<td>bit</td>
<td><code><span class='Function'>≠</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_neg</span></code></td>
<td>1</td>
<td>integer</td>
<td><code><span class='Function'>-</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_add</span></code></td>
<td>2</td>
<td>integer</td>
<td><code><span class='Function'>+</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_sub</span></code></td>
<td>2</td>
<td>integer</td>
<td><code><span class='Function'>-</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_mul</span></code></td>
<td>2</td>
<td>integer</td>
<td><code><span class='Function'>×</span></code></td>
</tr>
<tr>
<td><code><span class='Modifier'>_mulu</span></code></td>
<td>2</td>
<td>unsigned</td>
<td><code><span class='Function'>×</span></code></td>
</tr>
</tbody>
</table>
<p>An operation is exposed as a 1-modifier that takes up to four numbers for its operand.</p>
<ul>
<li>Operation width</li>
<li>Result element width</li>
<li>Right argument element width</li>
<li>Left argument element width</li>
</ul>
<p>The operand is extended to length 3 for monadic operations, and 4 for dyadic operations, by repeating the last element (like <code><span class='Function'>»</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Number'>4</span><span class='Function'>⥊⊢</span><span class='Modifier'>´</span><span class='Paren'>)</span></code>). It must be a number, or array of numbers with rank at most 1.</p>
<p>An example call is <code><span class='Value'>a</span> <span class='Number'>16</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Value'>•bit.</span><span class='Modifier'>_add</span> <span class='Value'>b</span></code>, to perform 16-bit additions on two boolean arrays with a boolean result.</p>
<p>To apply a bitwise operation, each argument is represented as a stream of bits based on the width given for it, then split into units whose width is the operation width. The operation is applied to these units. The result is again treated as a stream of bits and split according to the result width, with each unit forming a result element.</p>
<p>The operation width, along with the "Type" column above, determines what operation is performed. For bit operations it has no effect, except to constrain the argument sizes according to the shape rules below. Integer (meaning signed) and unsigned operations support widths of 8 and above, and should support higher values such as 128 if available.</p>
<p>Argument and result widths correspond to little-endian binary representations according to the following table (operation widths don't—see the "type" field in the table above). Here "boolean" indicates value 0 or 1, "signed integer" indicates two's complement representation, and "character" is a code point in an unsigned representation. Either type may be used for an argument, but the result will always use a primary type.</p>
<table>
<thead>
<tr>
<th>Width</th>
<th>Primary type</th>
<th>Also</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>Boolean</td>
<td></td>
</tr>
<tr>
<td>8</td>
<td>Signed integer</td>
<td>Character</td>
</tr>
<tr>
<td>16</td>
<td>Signed integer</td>
<td>Character</td>
</tr>
<tr>
<td>32</td>
<td>Signed integer</td>
<td>Character</td>
</tr>
<tr>
<td>64</td>
<td>IEEE 754 double</td>
<td></td>
</tr>
</tbody>
</table>
<p>An argument must be an array of numbers or an array of characters. Its elements must fit into the appropriate type. The "cell size" is the length in bits of a 1-cell, that is, <code><span class='Value'>width</span><span class='Function'>×</span><span class='Number'>¯1</span><span class='Function'>⊑</span><span class='Number'>1</span><span class='Function'>∾≢</span><span class='Value'>arg</span></code>, and must be a multiple of the operation width. Both arguments must have the same cell size, and the same leading shape <code><span class='Number'>¯1</span><span class='Function'>↓≢</span><span class='Value'>arg</span></code>. The result shape is this leading shape followed by the cell size divided by the result element width.</p>
<p>Another tool is provided for performing direct conversions, with no operation applied. The 1-modifier <code><span class='Value'>•bit.</span><span class='Modifier'>_cast</span></code> takes a two-element operand and one argument, for example <code><span class='Bracket'>⟨</span><span class='Number'>8</span><span class='Separator'>,</span><span class='Number'>16</span><span class='Ligature'>‿</span><span class='String'>'c'</span><span class='Bracket'>⟩</span><span class='Value'>•bit.</span><span class='Modifier'>_cast</span> <span class='Value'>ints</span></code> to convert each pair of numbers in <code><span class='Value'>ints</span></code> into a 2-byte character. Each element of <code><span class='Value'>𝕗</span></code> is a number or number-character pair giving width and type. The argument is encoded according to the first and decoded according to the second.</p>
|
