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
|
<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">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">spec</a></div>
<h1 id="specification-bqn-system-provided-values">Specification: BQN system-provided values</h1>
<p>This portion of the spec is definitely still a draft.</p>
<p>The <code><span class='Value'>•</span></code> symbol is used to access values other than primitives provided by BQN.</p>
<h2 id="scripts">Scripts</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'>•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>
</tbody>
</table>
<p><code><span class='Function'>•Import</span></code> loads another BQN script. The script is evaluated in its own 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.</p>
<h2 id="file-access">File access</h2>
<table>
<thead>
<tr>
<th>Name</th>
<th>Summary</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>•FChars</span></code></td>
<td>Read from or write to an entire file, as characters</td>
</tr>
<tr>
<td><code><span class='Function'>•FLines</span></code></td>
<td>Read from or write to an entire file, as lines</td>
</tr>
<tr>
<td><code><span class='Function'>•FBytes</span></code></td>
<td>Read from or write to an entire file, as bytes</td>
</tr>
</tbody>
</table>
<p>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>.</p>
<p>Functions <code><span class='Function'>•FChars</span></code>, <code><span class='Function'>•FLines</span></code>, and <code><span class='Function'>•FBytes</span></code> are all ambivalent. If only one argument is given, then it must be the name of a file, and the result is the contents of the file in the appropriate format. If there are two arguments, then the left argument is the filename and the right is the desired contents. These are written to the file, overwriting its contents, and the 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>
<h2 id="execution-and-scope-manipulation">Execution and scope manipulation</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'>•Eval</span></code></td>
<td>Evaluate the argument string in the current scope</td>
</tr>
<tr>
<td><code><span class='Function'>•Using</span></code></td>
<td>Import all values from the argument namespace</td>
</tr>
</tbody>
</table>
<p>The effect of <code><span class='Function'>•Eval</span></code> should be the same as if its argument were written as source code in the scope where <code><span class='Function'>•Eval</span></code> appears. It can define variables, and modify those in the current scope or a parent.</p>
<h2 id="input-and-output">Input and output</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'>•Fmt</span></code></td>
<td>Format value for printing</td>
</tr>
</tbody>
</table>
<h2 id="operation-properties">Operation properties</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>
</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 primitive.</p>
<p><code><span class='Function'>•Decompose</span></code> breaks down one level of a compound function or modifier, returning a list with a code giving what kind of structure it has (as listed in the table below) followed by each of its components. Non-operations do not cause an error, but return code -1, then the argument as a single component. 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>Block</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>
<tr>
<td>Left partial</td>
<td>6</td>
<td><code><span class='Value'>𝕗</span><span class='Separator'>,</span><span class='Value'>𝕣</span></code></td>
</tr>
<tr>
<td>Right partial</td>
<td>7</td>
<td><code> <span class='Value'>𝕣</span><span class='Separator'>,</span><span class='Value'>𝕘</span></code></td>
</tr>
</tbody>
</table>
<h2 id="timing">Timing</h2>
|
