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
|
<head>
<link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
<link href="../style.css" rel="stylesheet"/>
<title>BQN: Expression syntax</title>
</head>
<div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">doc</a></div>
<h1 id="expression-syntax"><a class="header" href="#expression-syntax">Expression syntax</a></h1>
<p>BQN expressions are the part of <a href="syntax.html">syntax</a> that describes computations to perform. Programs are mainly made up of expressions with a little organizing material like <a href="block.html">blocks</a> and <a href="namespace.html">namespaces</a> around them. This page explains how functions, modifiers, and assignment combine with their inputs. It doesn't describe <a href="token.html">constant</a> and <a href="arrayrepr.html#array-literals">array</a> literals, which each form a single subject for grammatical purposes.</p>
<p>The <a href="../tutorial/expression.html">first tutorial</a> also covers how to build and read BQN expressions.</p>
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>BQN expressions consist of subjects, functions, and modifiers arranged in sequence, with parentheses to group parts into subexpressions. Assignment arrows <code><span class='Gets'>←</span></code> and <code><span class='Gets'>↩</span></code> can also be present and mostly act like functions. <a href="ops.html#functions">Functions</a> can be applied to subjects or grouped into <a href="train.html">trains</a>, while <a href="ops.html#modifiers">modifiers</a> can be applied to subjects or functions. The most important kinds of application are:</p>
<table>
<thead>
<tr>
<th>left</th>
<th>main</th>
<th>right</th>
<th>output</th>
<th>name</th>
<th>binding</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Value'>w</span><span class='Head'>?</span></code></td>
<td><code><span class='Function'>F</span></code></td>
<td><code><span class='Value'>x</span></code></td>
<td>Subject</td>
<td>Function</td>
<td>RtL, looser</td>
</tr>
<tr>
<td><code><span class='Function'>F</span><span class='Head'>?</span></code></td>
<td><code><span class='Function'>G</span></code></td>
<td><code><span class='Function'>H</span></code></td>
<td>Function</td>
<td>Train</td>
<td></td>
</tr>
<tr>
<td><code><span class='Function'>F</span></code></td>
<td><code><span class='Modifier'>_m</span></code></td>
<td></td>
<td>Function</td>
<td>1-Modifier</td>
<td>LtR, tighter</td>
</tr>
<tr>
<td><code><span class='Function'>F</span></code></td>
<td><code><span class='Modifier2'>_c_</span></code></td>
<td><code><span class='Function'>G</span></code></td>
<td>Function</td>
<td>2-Modifier</td>
<td></td>
</tr>
</tbody>
</table>
<p>The four <a href="#syntactic-role">roles</a> (subject, function, two kinds of modifier) describe expressions, not values. When an expression is evaluated, the value's <a href="types.html">type</a> doesn't have to correspond to its role, and can even change from one evaluation to another. An expression's role is determined entirely by its source code, so it's fixed.</p>
<p>In the table, <code><span class='Head'>?</span></code> marks an optional left argument. If there isn't a value in that position, or it's <a href="#nothing">Nothing</a> (<code><span class='Nothing'>·</span></code>), the middle function will be called with only one argument.</p>
<p>If you're comfortable reading <a href="https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form">BNF</a> and want to understand things in more detail than described below, you might check the <a href="../spec/grammar.html">grammar specification</a> as well.</p>
<h2 id="syntactic-role"><a class="header" href="#syntactic-role">Syntactic role</a></h2>
<p><em>This issue is approached from a different angle in <a href="context.html">Context free grammar</a>.</em></p>
<p>In APL, the way one part of an expression interacts with others is determined by its value. That means that to parse an expression, in general you would have to evaluate that part, get a value, check its type, and then figure out how it fits in with the rest of the expression. This is a lot of work. BQN changes things so that you can determine how to parse an expression just by looking at its source code. But because it still needs to support expressions that can evaluate to more than one possible <a href="types.html">type</a>, BQN has to introduce a new and independent concept, called <strong>syntactic role</strong>, in order to support APL-like expressions.</p>
<p>Syntactic role is a property of an expression, not its value. To describe it in terms of English grammar, you might say "I like BQN", using "BQN" as an object, or "BQN scares me", using it as a subject. BQN itself isn't a subject or object, it's a programming language. Similarly you might write <code><span class='Function'>F</span> <span class='Value'>g</span></code>, placing <code><span class='Value'>f</span></code> in a function role to apply it to <code><span class='Value'>g</span></code>, or <code><span class='Function'>G</span> <span class='Value'>f</span></code> to use <code><span class='Value'>f</span></code> as an argument. Maybe even in the same program, although it's unlikely.</p>
<p>Below, the function <code><span class='Brace'>{</span><span class='Function'>𝕎</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code> treats its left argument <code><span class='Function'>𝕎</span></code> as a function and its right argument <code><span class='Value'>𝕩</span></code> as a subject. With a list of functions, we can make a table of the square and square root of a few numbers:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+ow5fLnCziiJrin6kge/CdlY7wnZWpfeKMnCAx4oC/NOKAvzk=">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Function'>×</span><span class='Modifier'>˜</span><span class='Separator'>,</span><span class='Function'>√</span><span class='Bracket'>⟩</span> <span class='Brace'>{</span><span class='Function'>𝕎</span><span class='Value'>𝕩</span><span class='Brace'>}</span><span class='Modifier'>⌜</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>9</span>
┌─
╵ 1 16 81
1 2 3
┘
</pre>
<h3 id="role-spellings"><a class="header" href="#role-spellings">Role spellings</a></h3>
<p>The four roles are <strong>subject</strong>, <strong>function</strong>, <strong>1-modifier</strong>, and <strong>2-modifier</strong>, as shown in the table below. Each type has an associated role (non-operation types all correspond to subjects), and the value of an expression will often have a type that fits the role, but it doesn't have to.</p>
<table>
<thead>
<tr>
<th>BQN</th>
<th>Names</th>
<th>Primitives</th>
</tr>
</thead>
<tbody>
<tr>
<td>Subject</td>
<td><code><span class='Value'>lowerCase</span></code></td>
<td>Literals</td>
</tr>
<tr>
<td>Function</td>
<td><code><span class='Function'>UpperCase</span></code></td>
<td><code><span class='Function'>+-×÷⋆√⌊⌈|¬∧∨</span></code>…</td>
</tr>
<tr>
<td>1-modifier</td>
<td><code><span class='Modifier'>_leading</span></code></td>
<td><code><span class='Modifier'>˙˜˘¨⌜⁼´˝`</span></code></td>
</tr>
<tr>
<td>2-modifier</td>
<td><code><span class='Modifier2'>_both_</span></code></td>
<td><code><span class='Modifier2'>∘○⊸⟜⌾⊘◶⎉⚇⍟⎊</span></code></td>
</tr>
</tbody>
</table>
<p>Primitive tokens, since they have a fixed value, always have a role that matches their type. They're functions by default, as the modifiers have glyphs that fit specific patterns. 1-modifiers have superscript glyphs, and 2-modifiers have glyphs with an unbroken circle—that is, one without a line through it, excluding functions <code><span class='Function'>⌽</span></code> and <code><span class='Function'>⍉</span></code>.</p>
<p>Variable names can be written in any case and with underscores added, and these changes don't affect what <a href="lexical.html">identifier</a> the name refers to. <code><span class='Value'>ab</span></code>, <code><span class='Value'>aB</span></code>, <code><span class='Function'>AB</span></code>, and <code><span class='Modifier2'>_a_B_</span></code> are all the same variable. However, the spelling—specifically the first and last characters—determine the variable's role. A lowercase first letter indicates a subject, and an uppercase first letter makes it a function. A leading underscore (regardless of the following character) indicates a 1-modifier, and both leading and trailing underscores makes a 2-modifier.</p>
<p>Besides these, character, string, and <a href="arrayrepr.html#array-literals">array literals</a> always have a subject role, and the role of a <a href="block.html">block</a> is determined by its type, which depends either on the header it has or which special variables it uses. If headerless, a block is a subject if it has no special names, but a <code><span class='Value'>𝕨</span></code> or <code><span class='Value'>𝕩</span></code> makes it at least a function, an <code><span class='Function'>𝔽</span></code> makes it a 1- or 2-modifier, and a <code><span class='Function'>𝔾</span></code> always makes it a 2-modifier.</p>
<p>The role of a compound expression, formed by applying an operation to some inputs, depends on the operation applied. This system is covered in the remaining sections below.</p>
<h2 id="parentheses"><a class="header" href="#parentheses">Parentheses</a></h2>
<p>As in most programming languages, parentheses <code><span class='Paren'>()</span></code> are for grouping. The code inside a balanced set of parentheses is a single expression, which produces one value to be used by the expression that contains it—for example, in <code><span class='Paren'>(</span><span class='Number'>2</span><span class='Function'>×</span><span class='Number'>3</span><span class='Paren'>)</span><span class='Function'>+</span><span class='Number'>4</span></code>, <code><span class='Number'>2</span><span class='Function'>×</span><span class='Number'>3</span></code> is a subexpression evaluating to <code><span class='Number'>6</span></code>, so that larger expression is equivalent to <code><span class='Number'>6</span><span class='Function'>+</span><span class='Number'>4</span></code>. The syntactic role of a set of parentheses is also the same as that of the expression inside.</p>
<h2 id="nothing"><a class="header" href="#nothing">Nothing</a></h2>
<p>The character <code><span class='Nothing'>·</span></code> is called Nothing. While it can be easier to think of it as a value, it can't be passed around in variables, and so can also be interpreted as an element of syntax. The special name <code><span class='Value'>𝕨</span></code> also functions as Nothing if the block that contains it is called with one argument (the uppercase spelling <code><span class='Function'>𝕎</span></code> doesn't, but instead immediately causes an error). Both <code><span class='Nothing'>·</span></code> and <code><span class='Value'>𝕨</span></code> have a subject role.</p>
<p>The following rules apply to Nothing:</p>
<ul>
<li>If it's the left argument in a function call, the function is called with no left argument.</li>
<li>If it's the right argument, the function isn't called, and "returns" Nothing.</li>
</ul>
<p>For example, the expression <code><span class='Paren'>(</span><span class='Function'>F</span> <span class='Number'>2</span> <span class='Function'>G</span> <span class='Nothing'>·</span><span class='Paren'>)</span> <span class='Function'>H</span> <span class='Function'>I</span> <span class='Value'>j</span></code> is equivalent to <code><span class='Function'>H</span> <span class='Function'>I</span> <span class='Value'>j</span></code>. But functions and arguments that will be discarded by the second rule are still evaluated, so that for example <code><span class='Paren'>(</span><span class='Value'>a</span><span class='Function'>+</span><span class='Gets'>↩</span><span class='Number'>1</span><span class='Paren'>)</span> <span class='Function'>F</span> <span class='Nothing'>·</span></code> increments <code><span class='Value'>a</span></code> when run.</p>
<p>Nothing can only be used as an argument to a function, or the left argument in a train (it can't be the right—a train ends with a function by definition). In another position where a subject could appear, like as an operand or in a list, it causes an error: either at compile time, for <code><span class='Nothing'>·</span></code>, or when the function is called with no left argument, for <code><span class='Value'>𝕨</span></code>.</p>
<h2 id="kinds-of-application"><a class="header" href="#kinds-of-application">Kinds of application</a></h2>
<p>Here is a table of the <a href="ops.html">function and modifier</a> application rules:</p>
<table>
<thead>
<tr>
<th>left</th>
<th>main</th>
<th>right</th>
<th>output</th>
<th>name</th>
</tr>
</thead>
<tbody>
<tr>
<td></td>
<td><code><span class='Function'>F</span></code></td>
<td><code><span class='Value'>x</span></code></td>
<td>Subject</td>
<td>Monadic function</td>
</tr>
<tr>
<td><code><span class='Value'>w</span></code></td>
<td><code><span class='Function'>F</span></code></td>
<td><code><span class='Value'>x</span></code></td>
<td>Subject</td>
<td>Dyadic function</td>
</tr>
<tr>
<td></td>
<td><code><span class='Function'>F</span></code></td>
<td><code><span class='Function'>G</span></code></td>
<td>Function</td>
<td>2-train</td>
</tr>
<tr>
<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
<td><code><span class='Function'>G</span></code></td>
<td><code><span class='Function'>H</span></code></td>
<td>Function</td>
<td>3-train</td>
</tr>
<tr>
<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
<td><code><span class='Modifier'>_m</span></code></td>
<td></td>
<td>Function</td>
<td>1-Modifier</td>
</tr>
<tr>
<td><code><span class='Function'>F</span><span class='Value'>*</span></code></td>
<td><code><span class='Modifier2'>_c_</span></code></td>
<td><code><span class='Function'>G</span><span class='Value'>*</span></code></td>
<td>Function</td>
<td>2-Modifier</td>
</tr>
</tbody>
</table>
<p>An asterisk <code><span class='Value'>*</span></code> indicates that a subject can also be used. Since the role doesn't exist after parsing, function and subject spellings are indistinguishable in these positions. Modifier applications bind more tightly than functions, and associate left-to-right while functions associate right-to-left.</p>
<h2 id="assignment"><a class="header" href="#assignment">Assignment</a></h2>
<p>Expressions may also include assignment, which is written with <code><span class='Gets'>←</span></code> or <code><span class='Gets'>⇐</span></code> to <em>define</em> (similar to "declare" in many other languages) a variable and <code><span class='Gets'>↩</span></code> to <em>change</em> its definition. Assignment has a left-hand side (<code><span class='Value'>name</span></code> below) which is usually a variable name, and a right-hand side (<code><span class='Function'>↕</span><span class='Number'>4</span></code>) which can be any expression. The roles of the two sides have to match. It sets the value of the variable to be the result of the expression.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=bmFtZSDihpAg4oaVNApuYW1l">↗️</a><pre> <span class='Value'>name</span> <span class='Gets'>←</span> <span class='Function'>↕</span><span class='Number'>4</span>
<span class='Value'>name</span>
⟨ 0 1 2 3 ⟩
</pre>
<p>A variable can only be defined once within a <a href="lexical.html">scope</a>, and can only be changed if it has already been defined. However, it can be shadowed, meaning that an inner scope can define it even if it has a definition in an outer scope already.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=eOKGkDEg4ouEIHt44oaQMiDii4QgeOKGqTMg4ouEIHh9Cng=">↗️</a><pre> <span class='Value'>x</span><span class='Gets'>←</span><span class='Number'>1</span> <span class='Separator'>⋄</span> <span class='Brace'>{</span><span class='Value'>x</span><span class='Gets'>←</span><span class='Number'>2</span> <span class='Separator'>⋄</span> <span class='Value'>x</span><span class='Gets'>↩</span><span class='Number'>3</span> <span class='Separator'>⋄</span> <span class='Value'>x</span><span class='Brace'>}</span>
3
<span class='Value'>x</span>
1
</pre>
<p>Assignment can be used inline in an expression, and its result is always the new value of the assignment target. Function or modifier assignment must be parenthesized, while subject assignment doesn't have to be: in a subject expression, assignment arrows have the same precedence as functions.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MsOXYeKGkChOZWfihpAtKTMKYQ==">↗️</a><pre> <span class='Number'>2</span><span class='Function'>×</span><span class='Value'>a</span><span class='Gets'>←</span><span class='Paren'>(</span><span class='Function'>Neg</span><span class='Gets'>←</span><span class='Function'>-</span><span class='Paren'>)</span><span class='Number'>3</span>
¯6
<span class='Value'>a</span>
¯3
</pre>
<p>The modification arrow <code><span class='Gets'>↩</span></code> can also be used to <em>update</em> the value of a variable by applying a function. This meaning applies only when there is no expression to the right of <code><span class='Gets'>↩</span></code> or that expression has a subject role, and there's a function to the left of <code><span class='Gets'>↩</span></code> (in terms of precedence this function is like an operand—a train must be parenthesized). The two forms of modified assignment are shown below along with equivalent expansions.</p>
<table>
<thead>
<tr>
<th>Syntax</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Value'>a</span> <span class='Function'>F</span><span class='Gets'>↩</span></code></td>
<td><code><span class='Value'>a</span> <span class='Gets'>↩</span> <span class='Function'>F</span> <span class='Value'>a</span></code></td>
</tr>
<tr>
<td><code><span class='Value'>a</span> <span class='Function'>F</span><span class='Gets'>↩</span> <span class='Value'>b</span></code></td>
<td><code><span class='Value'>a</span> <span class='Gets'>↩</span> <span class='Value'>a</span> <span class='Function'>F</span> <span class='Value'>b</span></code></td>
</tr>
</tbody>
</table>
<h3 id="destructuring"><a class="header" href="#destructuring">Destructuring</a></h3>
<p>The left hand side of assignment in a subject expression can be <em>compound</em>, so that assigned values are extracted from lists or namespaces. This is called a <em>destructuring</em> assignment. The most common case is list destructuring: the left hand side's written as a list, and the value on the right has to be a list of the same length. Assignments are made element-wise, and the elements can destructure things further.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oceKAv3Isc+KfqSDihpAg4p+oInFyIizihpU04p+pCgpyCgpz">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Value'>q</span><span class='Ligature'>‿</span><span class='Value'>r</span><span class='Separator'>,</span><span class='Value'>s</span><span class='Bracket'>⟩</span> <span class='Gets'>←</span> <span class='Bracket'>⟨</span><span class='String'>"qr"</span><span class='Separator'>,</span><span class='Function'>↕</span><span class='Number'>4</span><span class='Bracket'>⟩</span>
⟨ "qr" ⟨ 0 1 2 3 ⟩ ⟩
<span class='Value'>r</span>
'r'
<span class='Value'>s</span>
⟨ 0 1 2 3 ⟩
</pre>
<p>Array destructuring using <a href="arrayrepr.html#high-rank-arrays">array notation</a> <code><span class='Bracket'>[]</span></code> is also possible: it's equivalent to splitting the right-hand side with <code><span class='Function'><</span><span class='Modifier'>˘</span></code> and then applying list destructuring.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=W3QsdV0g4oaQIOKGlTLigL8zCgp1">↗️</a><pre> <span class='Bracket'>[</span><span class='Value'>t</span><span class='Separator'>,</span><span class='Value'>u</span><span class='Bracket'>]</span> <span class='Gets'>←</span> <span class='Function'>↕</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span>
┌─
╵ ⟨ 0 0 ⟩ ⟨ 0 1 ⟩ ⟨ 0 2 ⟩
⟨ 1 0 ⟩ ⟨ 1 1 ⟩ ⟨ 1 2 ⟩
┘
<span class='Value'>u</span>
⟨ ⟨ 1 0 ⟩ ⟨ 1 1 ⟩ ⟨ 1 2 ⟩ ⟩
</pre>
<p>Namespace destructuring uses an overlapping syntax, fully described in <a href="namespace.html#imports">its own section</a>. The left hand side is a list of names, or aliases <code><span class='Value'>to</span><span class='Gets'>⇐</span><span class='Value'>from</span></code>.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ceKAv3Ig4oapIHtx4oeQMity4oeQMC41fSDii4QgcQ==">↗️</a><pre> <span class='Value'>q</span><span class='Ligature'>‿</span><span class='Value'>r</span> <span class='Gets'>↩</span> <span class='Brace'>{</span><span class='Value'>q</span><span class='Gets'>⇐</span><span class='Number'>2</span><span class='Function'>+</span><span class='Value'>r</span><span class='Gets'>⇐</span><span class='Number'>0.5</span><span class='Brace'>}</span> <span class='Separator'>⋄</span> <span class='Value'>q</span>
2.5
</pre>
<p>With destructuring, you might want to discard some values from the right hand side rather than assign them any name. There's special syntax for this: use Nothing (<code><span class='Nothing'>·</span></code>) for a placeholder non-name in the appropriate position, like <code><span class='Nothing'>·</span><span class='Ligature'>‿</span><span class='Value'>y</span><span class='Ligature'>‿</span><span class='Nothing'>·</span> <span class='Gets'>←</span> <span class='Value'>list</span></code>.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=wrcg4oaQIDYgICAjIERvZXNuJ3QgZG8gYW55dGhpbmc=">↗️</a><pre> <span class='Nothing'>·</span> <span class='Gets'>←</span> <span class='Number'>6</span> <span class='Comment'># Doesn't do anything
</span>6
</pre>
<h3 id="exports"><a class="header" href="#exports">Exports</a></h3>
<p><em><a href="namespace.html#exports">Full documentation</a></em></p>
<p>The double arrow <code><span class='Gets'>⇐</span></code> exports variables from a block or program, causing the result to be a namespace. It can be used either in place of normal definition <code><span class='Gets'>←</span></code>, or as a stand-alone statement with nothing to the right; in either case all the variables to its left are exported. An example with both uses, as well as namespace destructuring that uses <code><span class='Gets'>⇐</span></code> to define variable aliases, is shown below.</p>
<pre><span class='Bracket'>⟨</span><span class='Value'>alias</span><span class='Gets'>⇐</span><span class='Value'>a</span><span class='Separator'>,</span> <span class='Value'>b</span><span class='Bracket'>⟩</span> <span class='Gets'>←</span> <span class='Brace'>{</span>
<span class='Value'>b</span><span class='Ligature'>‿</span><span class='Value'>c</span><span class='Gets'>⇐</span>
<span class='Value'>a</span><span class='Gets'>⇐</span><span class='Number'>2</span>
<span class='Value'>c</span><span class='Gets'>←</span><span class='Function'>÷</span><span class='Value'>b</span><span class='Gets'>←</span><span class='Number'>1</span><span class='Function'>+</span><span class='Value'>a</span>
<span class='Brace'>}</span>
</pre>
|