diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/doc/context.html | 5 | ||||
| -rw-r--r-- | docs/doc/depth.html | 82 | ||||
| -rw-r--r-- | docs/doc/embed.html | 10 | ||||
| -rw-r--r-- | docs/doc/enclose.html | 20 | ||||
| -rw-r--r-- | docs/doc/expression.html | 50 | ||||
| -rw-r--r-- | docs/doc/syntax.html | 2 | ||||
| -rw-r--r-- | docs/help/export.html | 4 |
7 files changed, 86 insertions, 87 deletions
diff --git a/docs/doc/context.html b/docs/doc/context.html index 23422fac..6a093c43 100644 --- a/docs/doc/context.html +++ b/docs/doc/context.html @@ -55,10 +55,7 @@ </tr> </tbody> </table> -<p>Unlike variables, BQN primitives have only one spelling, and a fixed role (but their values can be used in a different role by storing them in variables). Superscript glyphs <code><span class='Modifier'>˙˜˘¨⌜⁼´˝`</span></code> are used for 1-modifiers, and glyphs <code><span class='Modifier2'>∘○⊸⟜⌾⊘◶⎉⚇⍟⎊</span></code> with an unbroken circle are 2-modifiers. Other primitives are functions. String and numeric literals are subjects.</p> -<p>BQN's variables use another system, where the spelling indicates how the variable's value is used. A variable spelled with a lowercase first letter, like <code><span class='Value'>var</span></code>, is a subject. Spelled with an uppercase first letter, like <code><span class='Function'>Var</span></code>, it is a function. Underscores are placed where operands apply to indicate a 1-modifier <code><span class='Modifier'>_var</span></code> or 2-modifier <code><span class='Modifier2'>_var_</span></code>. Other than the first letter or underscore, variables are case-insensitive.</p> -<p>The associations between spelling and syntactic role are considered part of BQN's <a href="../spec/token.html">token formation rules</a>.</p> -<p>One rule for typing is also best considered to be a pre-parsing rule like the spelling system: the role of a headerless <a href="block.html">block</a> <code><span class='Brace'>{}</span></code> is determined by which special arguments it uses: it's a subject if there aren't any, 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>BQN uses <a href="expression.html#role-spellings">a few rules</a> to determine what role various parts of the grammar have. Primitive glyphs follow patterns: 1-modifiers like <code><span class='Modifier'>˝</span></code> are superscripts and 2-modifiers like <code><span class='Modifier2'>○</span></code> use circles. A variable can be spelled with different casing or underscores to indicate the role each time it's used.</p> <p>The syntactic role is a property of an expression, and BQN's grammar determines how roles interact in expressions. But <a href="types.html">type</a> is a property of a value, and evaluation rules control what types can be used. This means that roles exist statically in the code (context-free grammar!) while values can change between or within runs of the program. This is necessary to have a context-free grammar with unrestricted dynamic types. Are unrestricted dynamic types useful? Read on…</p> <h2 id="mixing-roles"><a class="header" href="#mixing-roles">Mixing roles</a></h2> <p>BQN's value types align closely with its syntactic roles: functions, 1-modifiers, and 2-modifiers are all types (<em>operation</em> types) as well as roles, while the other types (<em>data</em> types) are split into numbers, characters, and arrays. This is no accident, and usually values will be used in roles that correspond to their underlying type. However, the ability to use a role that doesn't match the type is also useful.</p> diff --git a/docs/doc/depth.html b/docs/doc/depth.html index 6d043d8d..53518c35 100644 --- a/docs/doc/depth.html +++ b/docs/doc/depth.html @@ -64,7 +64,7 @@ </g> </svg> -<p>The depth of an array is the greatest level of array nesting it attains, or, put another way, the greatest number of times you can pick an element starting from the original array before reaching an atom. The monadic function Depth (<code><span class='Function'>≡</span></code>) returns the depth of its argument, while the 2-modifier Depth (<code><span class='Modifier2'>⚇</span></code>) can control the way its left operand is applied based on the depth of its arguments. Several primitive functions also use the depth of the left argument to decide whether it applies to a single axis of the right argument or to several axes.</p> +<p>The depth of an array is the greatest level of array nesting it attains, or, put another way, the greatest number of times you can pick an element starting from the original array before reaching an atom. The monadic function Depth (<code><span class='Function'>≡</span></code>) returns the depth of its argument, while the 2-modifier Depth (<code><span class='Modifier2'>⚇</span></code>) controls the way its left operand is applied based on the depth of its arguments. Several primitive functions also check the depth of the left argument to decide whether it applies to a single axis of the right argument or to several axes.</p> <h2 id="the-depth-function"><a class="header" href="#the-depth-function">The Depth function</a></h2> <p>To find the depth of an array, use Depth (<code><span class='Function'>≡</span></code>). For example, the depth of a list of numbers or characters is 1:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omhIDLigL8z4oC/NAriiaEgImEgc3RyaW5nIGlzIGEgbGlzdCBvZiBjaGFyYWN0ZXJzIg==">↗️</a><pre> <span class='Function'>≡</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span> @@ -72,13 +72,13 @@ <span class='Function'>≡</span> <span class='String'>"a string is a list of characters"</span> 1 </pre> -<p>Depth is somewhat analogous to an array's <a href="shape.html">rank</a> <code><span class='Function'>=</span><span class='Value'>𝕩</span></code>, and in fact rank can be "converted" to depth by splitting rows with <code><span class='Function'><</span><span class='Modifier2'>⎉</span><span class='Number'>1</span></code>, reducing the rank by 1 and increasing the depth. Unlike rank, Depth doesn't care at all about its argument's shape:</p> +<p>Depth is somewhat analogous to an array's <a href="shape.html">rank</a> <code><span class='Function'>=</span><span class='Value'>𝕩</span></code>, and in fact rank can be "converted" to depth by splitting rows with <code><span class='Function'><</span><span class='Modifier2'>⎉</span><span class='Number'>1</span></code> (<a href="enclose.html">Enclose</a> <a href="rank.html">Rank</a> 1), reducing the rank by 1 and increasing the depth. Unlike rank, Depth doesn't care at all about its argument's shape:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omhIDPigL804qWKImNoYXJhY3RlcnMiCuKJoSAoMSvihpUxMCnipYoiY2hhcmFjdGVycyI=">↗️</a><pre> <span class='Function'>≡</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Function'>⥊</span><span class='String'>"characters"</span> 1 <span class='Function'>≡</span> <span class='Paren'>(</span><span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>10</span><span class='Paren'>)</span><span class='Function'>⥊</span><span class='String'>"characters"</span> 1 </pre> -<p>Also unlike rank, Depth <em>does</em> care about the elements of its argument: in fact, to find the depth of an array, every element must be inspected.</p> +<p>Also unlike rank, Depth <em>does</em> care about the elements of its argument: in fact, to find the depth of an array, every element must be inspected recursively.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omhIOKfqDIsMyw0LDXin6kK4omhIOKfqDIsPDMsNCw14p+pCuKJoSDin6gyLDwzLDQsPDw8NeKfqQ==">↗️</a><pre> <span class='Function'>≡</span> <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Number'>5</span><span class='Bracket'>⟩</span> 1 <span class='Function'>≡</span> <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Function'><</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Number'>5</span><span class='Bracket'>⟩</span> @@ -86,18 +86,16 @@ <span class='Function'>≡</span> <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Function'><</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Function'><<<</span><span class='Number'>5</span><span class='Bracket'>⟩</span> 4 </pre> -<p>As the above expressions suggest, the depth of an array is the maximum of its elements' depths, plus one. The base case, an atom (including a function or modifier), has depth 0.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omhJ2MnCkbihpAr4ouE4omhZgriiaHin6gnYycsZiwy4p+pCuKJoeKfqDUs4p+oJ2MnLGYsMuKfqeKfqQ==">↗️</a><pre> <span class='Function'>≡</span><span class='String'>'c'</span> +<p>The depth of an array is the maximum of its elements' depths, plus one. The base case, an atom (including a function or modifier), has depth 0.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omhICdjJwpG4oaQKyDii4Qg4omhZgriiaEg4p+oJ2MnLGYsMuKfqQ==">↗️</a><pre> <span class='Function'>≡</span> <span class='String'>'c'</span> 0 - <span class='Function'>F</span><span class='Gets'>←</span><span class='Function'>+</span><span class='Separator'>⋄</span><span class='Function'>≡</span><span class='Value'>f</span> + <span class='Function'>F</span><span class='Gets'>←</span><span class='Function'>+</span> <span class='Separator'>⋄</span> <span class='Function'>≡</span><span class='Value'>f</span> 0 - <span class='Function'>≡</span><span class='Bracket'>⟨</span><span class='String'>'c'</span><span class='Separator'>,</span><span class='Value'>f</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Bracket'>⟩</span> + <span class='Function'>≡</span> <span class='Bracket'>⟨</span><span class='String'>'c'</span><span class='Separator'>,</span><span class='Value'>f</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Bracket'>⟩</span> 1 - <span class='Function'>≡</span><span class='Bracket'>⟨</span><span class='Number'>5</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='String'>'c'</span><span class='Separator'>,</span><span class='Value'>f</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Bracket'>⟩⟩</span> -2 </pre> -<p>If the function <code><span class='Function'>IsArray</span></code> indicates whether its argument is an array, then we can write a recursive definition of Depth using the Choose modifier.</p> -<pre><span class='Function'>Depth</span><span class='Gets'>←</span><span class='Function'>IsArray</span><span class='Modifier2'>◶</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Brace'>{</span><span class='Number'>1</span><span class='Function'>+</span><span class='Number'>0</span><span class='Function'>⌈</span><span class='Modifier'>´</span><span class='Function'>Depth</span><span class='Modifier'>¨</span><span class='Function'>⥊</span><span class='Value'>𝕩</span><span class='Brace'>}</span> +<p>Using <code><span class='Number'>0</span><span class='Function'>=•Type</span></code> to test whether <code><span class='Value'>𝕩</span></code> is an array, as well as the <a href="choose.html">Choose</a> modifier, we can write a recursive definition of Depth.</p> +<pre><span class='Function'>Depth</span> <span class='Gets'>←</span> <span class='Paren'>(</span><span class='Number'>0</span><span class='Function'>=•Type</span><span class='Paren'>)</span><span class='Modifier2'>◶</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Brace'>{</span><span class='Number'>1</span><span class='Function'>+</span><span class='Number'>0</span><span class='Function'>⌈</span><span class='Modifier'>´</span><span class='Function'>Depth</span><span class='Modifier'>¨</span><span class='Function'>⥊</span><span class='Value'>𝕩</span><span class='Brace'>}</span> </pre> <p>The minimum element depth of 0 implies that an empty array's depth is 1.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omh4p+o4p+pCuKJoTLigL8w4oC/M+KlijA=">↗️</a><pre> <span class='Function'>≡</span><span class='Bracket'>⟨⟩</span> @@ -106,7 +104,7 @@ 1 </pre> <h2 id="testing-depth-for-multiple-axis-primitives"><a class="header" href="#testing-depth-for-multiple-axis-primitives">Testing depth for multiple-axis primitives</a></h2> -<p>Several primitive functions use the left argument to manipulate the right argument along one or more axes, using <a href="leading.html#multiple-axes">the leading axis convention</a>.</p> +<p>Several primitive functions manipulate <code><span class='Value'>𝕩</span></code> along one or more axes based on <code><span class='Value'>𝕨</span></code>, according to <a href="leading.html#multiple-axes">the leading axis convention</a>.</p> <table> <thead> <tr> @@ -125,24 +123,24 @@ </tr> </tbody> </table> -<p>Functions such as <a href="take.html">Take and Drop</a> use a single number per axis. When the left argument is a list of numbers, they apply to initial axes. But for convenience, a single number is also accepted, and applied to the first axis only. This is equivalent to <a href="reshape.html">deshaping</a> the left argument before applying the function.</p> +<p>Functions such as <a href="take.html">Take and Drop</a> accept a single number per axis in <code><span class='Value'>𝕨</span></code>. If given a list of numbers, they apply to initial axes. But for convenience, a single number is also accepted, and applied to the first axis only. This is equivalent to <a href="reshape.html">deshaping</a> the left argument before applying the function.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omiMuKGkTfigL834oC/N+KAvzfipYoiYWJjIgriiaIy4oC/MeKAvzHihpE34oC/N+KAvzfigL834qWKImFiYyI=">↗️</a><pre> <span class='Function'>≢</span><span class='Number'>2</span><span class='Function'>↑</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Function'>⥊</span><span class='String'>"abc"</span> ⟨ 2 7 7 7 ⟩ <span class='Function'>≢</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Function'>↑</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Function'>⥊</span><span class='String'>"abc"</span> ⟨ 2 1 1 7 ⟩ </pre> -<p>In these cases the flexibility seems trivial because the left argument has depth 1 or 0: it is an array or isn't, and it's obvious what a plain number should do. But for the second row in the table, the left argument is always an array. The general case (<a href="select.html">Select</a> below) is that the left argument is a list and its elements correspond to right argument axes:</p> +<p>In these cases the flexibility seems trivial because <code><span class='Value'>𝕨</span></code> has depth 1 or 0: it is an array or isn't, and it's obvious what a plain number should do. But for the second row in the table, <code><span class='Value'>𝕨</span></code> is always an array. The general case (<a href="select.html">Select</a> below) is that its elements are lists, each corresponding to one axis of <code><span class='Value'>𝕩</span></code>:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oM+KAvzIsMeKAvzTigL8x4p+pIOKKjyDihpU24oC/Nw==">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'>⊏</span> <span class='Function'>↕</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>7</span> ┌─ ╵ ⟨ 3 1 ⟩ ⟨ 3 4 ⟩ ⟨ 3 1 ⟩ ⟨ 2 1 ⟩ ⟨ 2 4 ⟩ ⟨ 2 1 ⟩ ┘ </pre> -<p>This means the left argument is homogeneous of depth 2. What should an argument of depth 1, that is, an array of atoms, do? One option is to continue to require the left argument to be a list, and convert any atom argument into an array by enclosing it:</p> +<p>This means <code><span class='Value'>𝕨</span></code> is homogeneous of depth 2. What should an argument of depth 1, that is, an array of atoms, do? One option is to continue to require the left argument to be a list, and convert any atom argument into an array by enclosing it:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oM+KAvzIsMeKfqSA84o2fKDA94omhKcKo4oq44oqPIOKGlTbigL83">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'><</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Number'>0</span><span class='Function'>=≡</span><span class='Paren'>)</span><span class='Modifier'>¨</span><span class='Modifier2'>⊸</span><span class='Function'>⊏</span> <span class='Function'>↕</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>7</span> ⟨ ⟨ 3 1 ⟩ ⟨ 2 1 ⟩ ⟩ </pre> -<p>While very consistent, this extension represents a small convenience and makes it difficult to act on a single axis, which for <a href="replicate.html">Replicate</a> and <a href="group.html">Group</a> is probably the most common way the primitive is used:</p> +<p>While very consistent, this extension represents a small convenience and makes it difficult to act on a single axis, which (particularly for <a href="replicate.html">Replicate</a> and <a href="group.html">Group</a>) is probably the most common way the primitive is used:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=M+KAvzLigL8x4oC/MuKAvzMgLyAiYWJjZGUi">↗️</a><pre> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span> <span class='Function'>/</span> <span class='String'>"abcde"</span> "aaabbcddeee" </pre> @@ -152,41 +150,41 @@ ⟨ ⟨ 2 1 4 0 ⟩ ⟨ 2 1 4 1 ⟩ ⟩ </pre> <h2 id="the-depth-modifier"><a class="header" href="#the-depth-modifier">The Depth modifier</a></h2> -<p>The Depth 2-modifier (<code><span class='Modifier2'>⚇</span></code>) is a generalization of <a href="map.html">Each</a> that allows diving deeper into an array. To illustrate it we'll use a shape <code><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span></code> array of lists of lists.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIG4g4oaQIDzijokx4o2fMiA04oC/M+KAvzLigL8y4qWK4oaVNDgK4omhIG4=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>n</span> <span class='Gets'>←</span> <span class='Function'><</span><span class='Modifier2'>⎉</span><span class='Number'>1</span><span class='Modifier2'>⍟</span><span class='Number'>2</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Function'>⥊↕</span><span class='Number'>48</span> -┌─ -╵ ⟨ ⟨ 0 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 ⟩ ⟩ - ┘ +<p>The Depth 2-modifier (<code><span class='Modifier2'>⚇</span></code>) is a generalization of <a href="map.html">Each</a> that allows diving deeper into an array. To illustrate it we'll use a shape <code><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span></code> array of lists of lists.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIG4g4oaQIDzijokx4o2fMiA04oC/MuKAvzLigL8z4qWK4oaVNDgK4omhIG4=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>n</span> <span class='Gets'>←</span> <span class='Function'><</span><span class='Modifier2'>⎉</span><span class='Number'>1</span><span class='Modifier2'>⍟</span><span class='Number'>2</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Function'>⥊↕</span><span class='Number'>48</span> +┌─ +╵ ⟨ ⟨ 0 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 ⟩ ⟩ + ┘ <span class='Function'>≡</span> <span class='Value'>n</span> 3 </pre> <p>Reversing <code><span class='Value'>n</span></code> swaps all the rows:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy9IG4=">↗️</a><pre> <span class='Function'>⌽</span> <span class='Value'>n</span> -┌─ -╵ ⟨ ⟨ 36 37 ⟩ ⟨ 38 39 ⟩ ⟩ ⟨ ⟨ 40 41 ⟩ ⟨ 42 43 ⟩ ⟩ ⟨ ⟨ 44 45 ⟩ ⟨ 46 47 ⟩ ⟩ - ⟨ ⟨ 24 25 ⟩ ⟨ 26 27 ⟩ ⟩ ⟨ ⟨ 28 29 ⟩ ⟨ 30 31 ⟩ ⟩ ⟨ ⟨ 32 33 ⟩ ⟨ 34 35 ⟩ ⟩ - ⟨ ⟨ 12 13 ⟩ ⟨ 14 15 ⟩ ⟩ ⟨ ⟨ 16 17 ⟩ ⟨ 18 19 ⟩ ⟩ ⟨ ⟨ 20 21 ⟩ ⟨ 22 23 ⟩ ⟩ - ⟨ ⟨ 0 1 ⟩ ⟨ 2 3 ⟩ ⟩ ⟨ ⟨ 4 5 ⟩ ⟨ 6 7 ⟩ ⟩ ⟨ ⟨ 8 9 ⟩ ⟨ 10 11 ⟩ ⟩ - ┘ +┌─ +╵ ⟨ ⟨ 36 37 38 ⟩ ⟨ 39 40 41 ⟩ ⟩ ⟨ ⟨ 42 43 44 ⟩ ⟨ 45 46 47 ⟩ ⟩ + ⟨ ⟨ 24 25 26 ⟩ ⟨ 27 28 29 ⟩ ⟩ ⟨ ⟨ 30 31 32 ⟩ ⟨ 33 34 35 ⟩ ⟩ + ⟨ ⟨ 12 13 14 ⟩ ⟨ 15 16 17 ⟩ ⟩ ⟨ ⟨ 18 19 20 ⟩ ⟨ 21 22 23 ⟩ ⟩ + ⟨ ⟨ 0 1 2 ⟩ ⟨ 3 4 5 ⟩ ⟩ ⟨ ⟨ 6 7 8 ⟩ ⟨ 9 10 11 ⟩ ⟩ + ┘ </pre> <p>Depth <code><span class='Number'>¯1</span></code> is equivalent to Each, and reverses the larger lists, while depth <code><span class='Number'>¯2</span></code> applies Each twice to reverse the smaller lists:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy94pqHwq8xIG4K4oy94pqHwq8yIG4=">↗️</a><pre> <span class='Function'>⌽</span><span class='Modifier2'>⚇</span><span class='Number'>¯1</span> <span class='Value'>n</span> -┌─ -╵ ⟨ ⟨ 2 3 ⟩ ⟨ 0 1 ⟩ ⟩ ⟨ ⟨ 6 7 ⟩ ⟨ 4 5 ⟩ ⟩ ⟨ ⟨ 10 11 ⟩ ⟨ 8 9 ⟩ ⟩ - ⟨ ⟨ 14 15 ⟩ ⟨ 12 13 ⟩ ⟩ ⟨ ⟨ 18 19 ⟩ ⟨ 16 17 ⟩ ⟩ ⟨ ⟨ 22 23 ⟩ ⟨ 20 21 ⟩ ⟩ - ⟨ ⟨ 26 27 ⟩ ⟨ 24 25 ⟩ ⟩ ⟨ ⟨ 30 31 ⟩ ⟨ 28 29 ⟩ ⟩ ⟨ ⟨ 34 35 ⟩ ⟨ 32 33 ⟩ ⟩ - ⟨ ⟨ 38 39 ⟩ ⟨ 36 37 ⟩ ⟩ ⟨ ⟨ 42 43 ⟩ ⟨ 40 41 ⟩ ⟩ ⟨ ⟨ 46 47 ⟩ ⟨ 44 45 ⟩ ⟩ - ┘ +┌─ +╵ ⟨ ⟨ 3 4 5 ⟩ ⟨ 0 1 2 ⟩ ⟩ ⟨ ⟨ 9 10 11 ⟩ ⟨ 6 7 8 ⟩ ⟩ + ⟨ ⟨ 15 16 17 ⟩ ⟨ 12 13 14 ⟩ ⟩ ⟨ ⟨ 21 22 23 ⟩ ⟨ 18 19 20 ⟩ ⟩ + ⟨ ⟨ 27 28 29 ⟩ ⟨ 24 25 26 ⟩ ⟩ ⟨ ⟨ 33 34 35 ⟩ ⟨ 30 31 32 ⟩ ⟩ + ⟨ ⟨ 39 40 41 ⟩ ⟨ 36 37 38 ⟩ ⟩ ⟨ ⟨ 45 46 47 ⟩ ⟨ 42 43 44 ⟩ ⟩ + ┘ <span class='Function'>⌽</span><span class='Modifier2'>⚇</span><span class='Number'>¯2</span> <span class='Value'>n</span> -┌─ -╵ ⟨ ⟨ 1 0 ⟩ ⟨ 3 2 ⟩ ⟩ ⟨ ⟨ 5 4 ⟩ ⟨ 7 6 ⟩ ⟩ ⟨ ⟨ 9 8 ⟩ ⟨ 11 10 ⟩ ⟩ - ⟨ ⟨ 13 12 ⟩ ⟨ 15 14 ⟩ ⟩ ⟨ ⟨ 17 16 ⟩ ⟨ 19 18 ⟩ ⟩ ⟨ ⟨ 21 20 ⟩ ⟨ 23 22 ⟩ ⟩ - ⟨ ⟨ 25 24 ⟩ ⟨ 27 26 ⟩ ⟩ ⟨ ⟨ 29 28 ⟩ ⟨ 31 30 ⟩ ⟩ ⟨ ⟨ 33 32 ⟩ ⟨ 35 34 ⟩ ⟩ - ⟨ ⟨ 37 36 ⟩ ⟨ 39 38 ⟩ ⟩ ⟨ ⟨ 41 40 ⟩ ⟨ 43 42 ⟩ ⟩ ⟨ ⟨ 45 44 ⟩ ⟨ 47 46 ⟩ ⟩ - ┘ +┌─ +╵ ⟨ ⟨ 2 1 0 ⟩ ⟨ 5 4 3 ⟩ ⟩ ⟨ ⟨ 8 7 6 ⟩ ⟨ 11 10 9 ⟩ ⟩ + ⟨ ⟨ 14 13 12 ⟩ ⟨ 17 16 15 ⟩ ⟩ ⟨ ⟨ 20 19 18 ⟩ ⟨ 23 22 21 ⟩ ⟩ + ⟨ ⟨ 26 25 24 ⟩ ⟨ 29 28 27 ⟩ ⟩ ⟨ ⟨ 32 31 30 ⟩ ⟨ 35 34 33 ⟩ ⟩ + ⟨ ⟨ 38 37 36 ⟩ ⟨ 41 40 39 ⟩ ⟩ ⟨ ⟨ 44 43 42 ⟩ ⟨ 47 46 45 ⟩ ⟩ + ┘ </pre> <p>While a negative depth tells how many levels to go down, a non-negative depth gives the maximum depth of the argument before applying the left operand. On a depth-3 array like above, depth <code><span class='Number'>2</span></code> is equivalent to <code><span class='Number'>¯1</span></code> and depth <code><span class='Number'>1</span></code> is equivalent to <code><span class='Number'>¯2</span></code>. A depth of <code><span class='Number'>0</span></code> means to descend all the way to the level of atoms, that is, apply <a href="arithmetic.html#pervasion">pervasively</a>, like an arithmetic function.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oJ2EnLCJiYyLin6kg4omN4pqHMCDin6gy4oC/Myw04p+p">↗️</a><pre> <span class='Bracket'>⟨</span><span class='String'>'a'</span><span class='Separator'>,</span><span class='String'>"bc"</span><span class='Bracket'>⟩</span> <span class='Function'>≍</span><span class='Modifier2'>⚇</span><span class='Number'>0</span> <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Bracket'>⟩</span> diff --git a/docs/doc/embed.html b/docs/doc/embed.html index b911046d..ea1d8e5c 100644 --- a/docs/doc/embed.html +++ b/docs/doc/embed.html @@ -5,13 +5,13 @@ </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="using-embedded-bqn"><a class="header" href="#using-embedded-bqn">Using embedded BQN</a></h1> -<p>The Javascript implementation of BQN, <a href="https://github.com/mlochbaum/BQN/blob/master/doc/../docs/bqn.js">docs/bqn.js</a>, can be <a href="https://mlochbaum.github.io/BQN/try.html">used</a> as a standalone interpreter, but it can also be called from JS, which in combination with BQN's first-class functions allows the two language to interoperate well. Similar functionality will most likely be brought to other host languages in the future. Languages that (like JS) allow functions and arrays to be tagged with extra properties can host a full BQN implementation with good interoperability. Other languages would either require functions and arrays to be stored in specialized data structures, making interoperability a little harder, or would miss out on some inferred properties like function inverses and array fills.</p> +<p>The Javascript implementation of BQN, <a href="https://github.com/mlochbaum/BQN/blob/master/doc/../docs/bqn.js">docs/bqn.js</a>, can be <a href="https://mlochbaum.github.io/BQN/try.html">used</a> as a standalone interpreter, but it can also be called from JS, which in combination with BQN's first-class functions allows the two languages to interoperate well. Similar functionality will most likely be brought to other host languages in the future (and there's a <a href="https://detegr.github.io/cbqn-rs/cbqn/">Rust binding</a> to CBQN that works a lot like an embedding). Languages that (like JS) allow functions and arrays to be tagged with extra properties can host a full BQN implementation with good interoperability. Other languages would either require functions and arrays to be stored in specialized data structures, making interoperability a little harder, or would miss out on some inferred properties like function <a href="undo.html">inverses</a> and array <a href="fill.html">fills</a>.</p> <p>There is only one mechanism to interface between the host language and BQN: the function <code><span class='Value'>bqn</span></code> evaluates a string containing a BQN program and returns the result. Doesn't sound like much, especially considering these programs can't share any state such as global variables (BQN doesn't have those). But taking first-class functions and closures into account, it's all you could ever need!</p> <h2 id="passing-closures"><a class="header" href="#passing-closures">Passing closures</a></h2> <p>Probably you can figure out the easy things like calling <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"×´1+↕6"</span><span class='Paren'>)</span></code> to compute six factorial. But how do you get JS and BQN to <em>talk</em> to each other, for example to compute the factorial of a number <code><span class='Value'>n</span></code>? Constructing a source string with <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"×´1+↕"</span><span class='Function'>+</span><span class='Value'>n</span><span class='Paren'>)</span></code> isn't the best way—in fact I would recommend you never use this strategy.</p> <p>Instead, return a function from BQN and call it: <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"{×´1+↕𝕩}"</span><span class='Paren'>)(</span><span class='Value'>n</span><span class='Paren'>)</span></code>. This strategy also has the advantage that you can store the function, so that it will only be compiled once. Define <code><span class='Value'>let</span> <span class='Value'>fact</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"{×´1+↕𝕩}"</span><span class='Paren'>)</span><span class='Head'>;</span></code> at the top of your program and use it as a function elsewhere.</p> <p>BQN can also call JS functions, to use functionality that isn't native to BQN or interact with a program written in JS. For example, <code><span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"{𝕏'a'+↕26}"</span><span class='Paren'>)(</span><span class='Value'>alert</span><span class='Paren'>)</span></code> calls the argument <code><span class='Value'>alert</span></code> from within BQN. The displayed output isn't quite right here, because a BQN string is stored as a JS array, not a string. See the next section for more information.</p> -<p>Cool, but none of these examples really use closures, just self-contained functions. <a href="lexical.html#closures">Closures</a> are functions that use outside state, which is maintained over the course of the program. Here's an example program that defines <code><span class='Value'>i</span></code> and then returns a function that manipulates <code><span class='Value'>i</span></code> and returns its new value.</p> +<p>Cool, but none of these examples really use closures, just self-contained functions. <a href="lexical.html#closures">Closures</a> are functions that use outside state, which is maintained over the course of the program. Here's an example program that defines <code><span class='Value'>i</span></code>, and then returns a function that manipulates <code><span class='Value'>i</span></code> and returns its new value.</p> <pre><span class='Value'>let</span> <span class='Value'>push</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='Modifier'>`</span> <span class='Value'>i</span><span class='Gets'>←</span><span class='Number'>4</span><span class='Function'>⥊</span><span class='Number'>0</span> <span class='Brace'>{</span><span class='Value'>i</span><span class='Function'>+</span><span class='Gets'>↩</span><span class='Value'>𝕩</span><span class='Function'>»</span><span class='Value'>i</span><span class='Brace'>}</span> @@ -20,17 +20,17 @@ <span class='Value'>push</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Number'>2</span><span class='Paren'>)</span><span class='Head'>;</span> <span class='Function'>//</span> <span class='Bracket'>[</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Bracket'>]</span> <span class='Value'>push</span><span class='Paren'>(</span><span class='Number'>4</span><span class='Paren'>)</span><span class='Head'>;</span> <span class='Function'>//</span> <span class='Bracket'>[</span><span class='Number'>5</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Bracket'>]</span> </pre> -<p>Note that this program doesn't have any outer braces. It's only run once, and it initializes <code><span class='Value'>i</span></code> and returns a function. Just putting braces around it wouldn't have any effect—it just changes it from a program that does something to a program that runs a block that does the same thing—but adding braces and using <code><span class='Value'>𝕨</span></code> or <code><span class='Value'>𝕩</span></code> inside them would turn it into a function that could be run multiple times to create different closures. For example, <code><span class='Value'>pushGen</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"{i←4⥊𝕩⋄{i+↩𝕩»i}}"</span><span class='Paren'>)</span></code> causes <code><span class='Value'>pushGen</span><span class='Paren'>(</span><span class='Value'>n</span><span class='Paren'>)</span></code> to create a new closure with <code><span class='Value'>i</span></code> initialized to <code><span class='Number'>4</span><span class='Function'>⥊</span><span class='Value'>n</span></code>.</p> +<p>Note that this program doesn't have any outer braces. It's only run once, and it initializes <code><span class='Value'>i</span></code> and returns a function. Just putting braces around it wouldn't have any effect—it just changes it from a program that does something to a program that runs a block that does the same thing—but adding braces and using <code><span class='Value'>𝕨</span></code> or <code><span class='Value'>𝕩</span></code> inside would turn it into a function that could be run multiple times to create different closures. For example, <code><span class='Value'>pushGen</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='String'>"{i←4⥊𝕩⋄{i+↩𝕩»i}}"</span><span class='Paren'>)</span></code> causes <code><span class='Value'>pushGen</span><span class='Paren'>(</span><span class='Value'>n</span><span class='Paren'>)</span></code> to create a new closure with <code><span class='Value'>i</span></code> initialized to <code><span class='Number'>4</span><span class='Function'>⥊</span><span class='Value'>n</span></code>.</p> <p>The program also returns only one function, which can be limiting. But it's possible to get multiple closures out of the same program by returning a list of functions. For example, the following program defines three functions that manipulate a shared array in different ways.</p> <pre><span class='Value'>let</span> <span class='Bracket'>[</span><span class='Value'>rotx</span><span class='Separator'>,</span> <span class='Value'>roty</span><span class='Separator'>,</span> <span class='Value'>flip</span><span class='Bracket'>]</span> <span class='Function'>=</span> <span class='Value'>bqn</span><span class='Paren'>(</span><span class='Modifier'>`</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Function'>⥊↕</span><span class='Number'>6</span> <span class='Function'>RotX</span> <span class='Gets'>←</span> <span class='Brace'>{</span><span class='Value'>a</span><span class='Gets'>↩</span><span class='Value'>𝕩</span><span class='Function'>⌽</span><span class='Modifier'>˘</span><span class='Value'>a</span><span class='Brace'>}</span> <span class='Function'>RotY</span> <span class='Gets'>←</span> <span class='Brace'>{</span><span class='Value'>a</span><span class='Gets'>↩</span><span class='Value'>𝕩</span><span class='Function'>⌽</span><span class='Value'>a</span><span class='Brace'>}</span> - <span class='Function'>Flip</span> <span class='Gets'>←</span> <span class='Brace'>{</span><span class='Value'>𝕤</span><span class='Separator'>⋄</span><span class='Value'>a</span><span class='Gets'>↩</span><span class='Function'>⍉</span><span class='Value'>a</span><span class='Brace'>}</span> + <span class='Function'>Flip</span> <span class='Gets'>←</span> <span class='Brace'>{</span><span class='Function'>𝕊</span><span class='Head'>:</span><span class='Value'>a</span><span class='Gets'>↩</span><span class='Function'>⍉</span><span class='Value'>a</span><span class='Brace'>}</span> <span class='Function'>RotX</span><span class='Ligature'>‿</span><span class='Function'>RotY</span><span class='Ligature'>‿</span><span class='Function'>Flip</span> <span class='Modifier'>`</span><span class='Paren'>)</span><span class='Head'>;</span> </pre> -<p>When defining closures for their side effects like this, make sure they are actually functions! For example, since <code><span class='Value'>flip</span></code> ignores its argument (you can call it with <code><span class='Value'>flip</span><span class='Paren'>()</span></code>, because a right argument of <code><span class='Value'>undefined</span></code> isn't valid but will just be ignored), it needs an extra <code><span class='Value'>𝕤</span></code> in the definition to be a function instead of an immediate block.</p> +<p>When defining closures for their side effects like this, make sure they are actually functions! For example, since <code><span class='Value'>flip</span></code> ignores its argument (you can call it with <code><span class='Value'>flip</span><span class='Paren'>()</span></code>, because a right argument of <code><span class='Value'>undefined</span></code> isn't valid but will just be ignored), it needs an <code><span class='Function'>𝕊</span><span class='Head'>:</span></code> in the definition to be a function instead of an immediate block.</p> <p>You can also use an array to pass multiple functions or other values from JS into BQN all at once. However, a JS array can't be used directly in BQN because its shape isn't known. The function <code><span class='Value'>list</span><span class='Paren'>()</span></code> converts a JS array into a BQN list by using its length for the shape; the next section has a few more details.</p> <h2 id="js-encodings"><a class="header" href="#js-encodings">JS encodings</a></h2> <p>In the programs above we've used numbers and functions of one argument, which mean the same thing in BQN and JS. This isn't the case for all types: although every BQN value is stored as some JS value, the way it's represented may not be obvious and there are many JS values that don't represent any BQN value and could cause errors. BQN operations don't verify that their inputs are valid BQN values (this would have a large performance cost), so it's up to the JS programmer to make sure that values passed in are valid. To do this, you need to know the encodings for each of the seven BQN <a href="types.html">types</a> you're going to use.</p> diff --git a/docs/doc/enclose.html b/docs/doc/enclose.html index e00d168b..5d117405 100644 --- a/docs/doc/enclose.html +++ b/docs/doc/enclose.html @@ -5,7 +5,7 @@ </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="enclose"><a class="header" href="#enclose">Enclose</a></h1> -<p>The function enclose creates a unit array whose only element is <code><span class='Value'>𝕩</span></code>.</p> +<p>The function Enclose creates a unit array whose only element is <code><span class='Value'>𝕩</span></code>.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=PCAieHl6Ig==">↗️</a><pre> <span class='Function'><</span> <span class='String'>"xyz"</span> ┌· · "xyz" @@ -22,7 +22,7 @@ </pre> <p>If there are no axes, what use is an array? Rank 0 certainly qualifies as an edge case, as there's no rank -1 below it. Most often when a unit array is used it's because there <em>are</em> relevant axes, but we want an array that doesn't include them (sound cryptic? Just keep reading…).</p> <p>This contrasts with an atom like <code><span class='Number'>137</span></code>, which is considered a unit but not a unit <em>array</em>. An atom has no axes just because it doesn't have axes. But because it has no axes, it has the same shape <code><span class='Bracket'>⟨⟩</span></code> as a unit array, by convention.</p> -<p>Some unit arrays are made by removing an axis from an existing array. First Cell (<code><span class='Function'>⊏</span></code>) or <a href="fold.html">Insert</a> (<code><span class='Modifier'>˝</span></code>) might do this:</p> +<p>Some unit arrays are made by removing an axis from an existing array. <a href="select.html#first-cell">First Cell</a> (<code><span class='Function'>⊏</span></code>) or <a href="fold.html">Insert</a> (<code><span class='Modifier'>˝</span></code>) might do this:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=bCDihpAgMuKAvzfigL8x4oC/OOKAvzLigL84CuKKjyBsCivLnSBs">↗️</a><pre> <span class='Value'>l</span> <span class='Gets'>←</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>8</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>8</span> <span class='Function'>⊏</span> <span class='Value'>l</span> ┌· @@ -37,11 +37,11 @@ <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8udy5ggM+KAvzTipYrihpUxMg==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>˝˘</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Function'>⥊↕</span><span class='Number'>12</span> ⟨ 6 22 38 ⟩ </pre> -<p>In this case each call to <code><span class='Function'>+</span><span class='Modifier'>˝</span></code> returns a cell of the result. The result is a list, so its cells are units! Here, <a href="rank.html">Cells</a> (<code><span class='Modifier'>˘</span></code>) "hides" one axis from its operand, and the operand <code><span class='Function'>+</span><span class='Modifier'>˝</span></code> reduces out an axis, leaving zero axes—until Cells assembles the results, putting its axis back. In this case, <code><span class='Function'>+</span><span class='Modifier'>´</span></code> would also be tolerated. But it's wrong, because each result really should be a zero-axis array. We can reveal this by making an array whose elements aren't atoms.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0y5gg4p+o4oaVMiwiYWIi4p+p4omN4p+o4oaVMywiQUJDIuKfqQoKK8udy5gg4p+o4oaVMiwiYWIi4p+p4omN4p+o4oaVMywiQUJDIuKfqQ==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´˘</span> <span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>2</span><span class='Separator'>,</span><span class='String'>"ab"</span><span class='Bracket'>⟩</span><span class='Function'>≍</span><span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>3</span><span class='Separator'>,</span><span class='String'>"ABC"</span><span class='Bracket'>⟩</span> +<p>In this case each call to <code><span class='Function'>+</span><span class='Modifier'>˝</span></code> returns a cell of the result. The result is a list, so its cells are units! Here, <a href="rank.html">Cells</a> (<code><span class='Modifier'>˘</span></code>) "hides" one axis from its operand, and the operand <code><span class='Function'>+</span><span class='Modifier'>˝</span></code> reduces out an axis, leaving zero axes—until Cells assembles the results, putting its axis back. Here, <code><span class='Function'>+</span><span class='Modifier'>´</span></code> would also be tolerated. But it's wrong, because each result really should be a zero-axis array. We can reveal this by making an array whose elements aren't atoms.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0y5ggW+KfqOKGlTIsImFiIuKfqSzin6jihpUzLCJBQkMi4p+pXQoKK8udy5ggW+KfqOKGlTIsImFiIuKfqSzin6jihpUzLCJBQkMi4p+pXQ==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´˘</span> <span class='Bracket'>[⟨</span><span class='Function'>↕</span><span class='Number'>2</span><span class='Separator'>,</span><span class='String'>"ab"</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>3</span><span class='Separator'>,</span><span class='String'>"ABC"</span><span class='Bracket'>⟩]</span> <span class='Error'>Error: >: Elements didn't have equal shapes (contained shapes ⟨2⟩ and ⟨3⟩)</span> - <span class='Function'>+</span><span class='Modifier'>˝˘</span> <span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>2</span><span class='Separator'>,</span><span class='String'>"ab"</span><span class='Bracket'>⟩</span><span class='Function'>≍</span><span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>3</span><span class='Separator'>,</span><span class='String'>"ABC"</span><span class='Bracket'>⟩</span> + <span class='Function'>+</span><span class='Modifier'>˝˘</span> <span class='Bracket'>[⟨</span><span class='Function'>↕</span><span class='Number'>2</span><span class='Separator'>,</span><span class='String'>"ab"</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>3</span><span class='Separator'>,</span><span class='String'>"ABC"</span><span class='Bracket'>⟩]</span> ⟨ "ac" "ACE" ⟩ </pre> <p>The function <code><span class='Function'>+</span><span class='Modifier'>´˘</span></code> tries to mix together the result elements into one big array, causing an error because they have different lengths, but <code><span class='Function'>+</span><span class='Modifier'>˝˘</span></code> keeps them as elements.</p> @@ -61,14 +61,14 @@ ⟨ "anti" "green" "up" ⟩ ⟨ "anti" "green" "down" ⟩ ┘ </pre> -<p>One use is in the function <code><span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span></code>, which encloses the left argument before (<code><span class='Modifier2'>⊸</span></code>) <a href="join.html">joining</a> (<code><span class='Function'>∾</span></code>) it to the right argument. This is different from Join on its own because it treats the left argument as a single element.</p> +<p>One use is in the function <code><span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span></code>, which encloses the left argument <a href="hook.html">before</a> (<code><span class='Modifier2'>⊸</span></code>) <a href="join.html">joining</a> (<code><span class='Function'>∾</span></code>) it to the right argument. This is different from Join on its own because it treats the left argument as a single element.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=InN0YXJ0IiDiiL4gIm1pZGRsZSLigL8iZW5kIgoKInN0YXJ0IiA84oq44oi+ICJtaWRkbGUi4oC/ImVuZCI=">↗️</a><pre> <span class='String'>"start"</span> <span class='Function'>∾</span> <span class='String'>"middle"</span><span class='Ligature'>‿</span><span class='String'>"end"</span> ⟨ 's' 't' 'a' 'r' 't' "middle" "end" ⟩ <span class='String'>"start"</span> <span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span> <span class='String'>"middle"</span><span class='Ligature'>‿</span><span class='String'>"end"</span> ⟨ "start" "middle" "end" ⟩ </pre> -<p>For this purpose <code><span class='Brace'>{</span><span class='Bracket'>⟨</span><span class='Value'>𝕩</span><span class='Bracket'>⟩</span><span class='Brace'>}</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span></code>, which turns the left argument into a 1-element list, also works. But maybe it doesn't really capture the intended meaning: it makes <code><span class='Value'>𝕨</span></code> into a whole new list to be added when all that's needed is to add one cell. This cell will be placed along the first axis, but it doesn't have an axis of its own. A similar example, showing how units are used as part of a computation, is to join each row of a matrix to the corresponding item of a list.</p> +<p>For this purpose <code><span class='Function'>⋈</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span></code>, which <a href="pair.html">enlists</a> the left argument giving the list <code><span class='Bracket'>⟨</span><span class='Value'>𝕨</span><span class='Bracket'>⟩</span></code>, also works. But maybe it doesn't really capture the intended meaning: it makes <code><span class='Value'>𝕨</span></code> into a whole new list to be added when all that's needed is to add one cell. This cell will be placed along the first axis, but it doesn't have an axis of its own. A similar example, showing how units are used as part of a computation, is to join each row of a matrix to the corresponding item of a list.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KD3ijJzLnOKGlTQpIOKIvsuYIOKGlTQ=">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>=</span><span class='Modifier'>⌜˜</span><span class='Function'>↕</span><span class='Number'>4</span><span class='Paren'>)</span> <span class='Function'>∾</span><span class='Modifier'>˘</span> <span class='Function'>↕</span><span class='Number'>4</span> ┌─ ╵ 1 0 0 0 0 @@ -90,7 +90,7 @@ <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=POKKuOKIvuKMnMK0IOKfqCJ1cCLigL8iZG93biLin6k=">↗️</a><pre> <span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Modifier'>⌜´</span> <span class='Bracket'>⟨</span><span class='String'>"up"</span><span class='Ligature'>‿</span><span class='String'>"down"</span><span class='Bracket'>⟩</span> ⟨ "up" "down" ⟩ </pre> -<p>But this is only an array of strings, and not an array of lists of strings: the right result is <code><span class='Bracket'>⟨⟨</span><span class='String'>"up"</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='String'>"down"</span><span class='Bracket'>⟩⟩</span></code>. And that's not the extend of our troubles: without an initial value we'll get the wrong result on longer arguments too, because the elements of the rightmost array get joined to the result lists as lists, not as elements.</p> +<p>But this is only an array of strings, and not an array of lists of strings: the right result is <code><span class='Bracket'>⟨⟨</span><span class='String'>"up"</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='String'>"down"</span><span class='Bracket'>⟩⟩</span></code>. And that's not the extent of our troubles: without an initial value we'll get the wrong result on longer arguments too, because the elements of the rightmost array get joined to the result lists as lists, not as elements.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=POKKuOKIvuKMnMK0IOKfqCJyZWQi4oC/ImJsdWUi4oC/ImdyZWVuIiwgInVwIuKAvyJkb3duIuKfqQ==">↗️</a><pre> <span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Modifier'>⌜´</span> <span class='Bracket'>⟨</span><span class='String'>"red"</span><span class='Ligature'>‿</span><span class='String'>"blue"</span><span class='Ligature'>‿</span><span class='String'>"green"</span><span class='Separator'>,</span> <span class='String'>"up"</span><span class='Ligature'>‿</span><span class='String'>"down"</span><span class='Bracket'>⟩</span> ┌─ ╵ ⟨ "red" 'u' 'p' ⟩ ⟨ "red" 'd' 'o' 'w' 'n' ⟩ @@ -99,7 +99,7 @@ ┘ </pre> <p>To make things right, we need an array of lists for an initial value. Since it shouldn't add anything to the result, any lists it contains need to be empty. But what should its shape be? The result shape from Table is always the argument shapes joined together (<code><span class='Value'>𝕨</span><span class='Function'>∾</span><span class='Modifier2'>○</span><span class='Function'>≢</span><span class='Value'>𝕩</span></code>). The initial value shouldn't contribute the result shape, so it needs to have empty shape, or rank 0! We use Enclose to create the array <code><span class='Function'><</span><span class='Bracket'>⟨⟩</span></code> with no axes, because the result <em>will</em> have axes but the initial element needs to start without any. All the axes come from the list of choices.</p> -<p>It goes deeper! The following (pretty tough) example uses arrays with various ranks in the argument, and they're handled quite well. The last one isn't really a choice, so it has no axes. If it were a one-element list then the result would have a meaningless length-1 axis. But not enclosing it would cause each character to be treated as an option, with unpleasant results.</p> +<p>It goes deeper! The following (pretty tough) example uses arrays with various ranks in the argument, and they're handled just fine. The last one isn't really a choice, so it has no axes. If it were a one-element list then the result would have a meaningless length-1 axis. But not enclosing it would cause each character to be treated as an option, with unpleasant results.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Zmxhdm9yIOKGkCDijYkg4oiY4oC/MiDipYogInVwIuKAvyJkb3duIuKAvyJjaGFybSLigL8ic3RyYW5nZSLigL8idG9wIuKAvyJib3R0b20iCig84p+o4p+pKSA84oq44oi+4oycwrQg4p+oInJlZCLigL8iYmx1ZSLigL8iZ3JlZW4iLCBmbGF2b3IsIDwicXVhcmsi4p+p">↗️</a><pre> <span class='Value'>flavor</span> <span class='Gets'>←</span> <span class='Function'>⍉</span> <span class='Modifier2'>∘</span><span class='Ligature'>‿</span><span class='Number'>2</span> <span class='Function'>⥊</span> <span class='String'>"up"</span><span class='Ligature'>‿</span><span class='String'>"down"</span><span class='Ligature'>‿</span><span class='String'>"charm"</span><span class='Ligature'>‿</span><span class='String'>"strange"</span><span class='Ligature'>‿</span><span class='String'>"top"</span><span class='Ligature'>‿</span><span class='String'>"bottom"</span> <span class='Paren'>(</span><span class='Function'><</span><span class='Bracket'>⟨⟩</span><span class='Paren'>)</span> <span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Modifier'>⌜´</span> <span class='Bracket'>⟨</span><span class='String'>"red"</span><span class='Ligature'>‿</span><span class='String'>"blue"</span><span class='Ligature'>‿</span><span class='String'>"green"</span><span class='Separator'>,</span> <span class='Value'>flavor</span><span class='Separator'>,</span> <span class='Function'><</span><span class='String'>"quark"</span><span class='Bracket'>⟩</span> ┌─ @@ -114,7 +114,7 @@ ┘ </pre> <h3 id="broadcasting"><a class="header" href="#broadcasting">Broadcasting</a></h3> -<p>Table isn't the only mapping function that gets along well with units. Here's an example with Each (<code><span class='Modifier'>¨</span></code>).</p> +<p>Table isn't the only mapping function that gets along well with units. Here's an example with <a href="map.html#each">Each</a> (<code><span class='Modifier'>¨</span></code>).</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=PeKAv+KJoOKAv+KJoeKAv+KJoiB78J2VjvCdlal9wqggPCAz4oC/MuKliiJhYmNkZWYi">↗️</a><pre> <span class='Function'>=</span><span class='Ligature'>‿</span><span class='Function'>≠</span><span class='Ligature'>‿</span><span class='Function'>≡</span><span class='Ligature'>‿</span><span class='Function'>≢</span> <span class='Brace'>{</span><span class='Function'>𝕎</span><span class='Value'>𝕩</span><span class='Brace'>}</span><span class='Modifier'>¨</span> <span class='Function'><</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Function'>⥊</span><span class='String'>"abcdef"</span> ⟨ 2 3 1 ⟨ 3 2 ⟩ ⟩ </pre> diff --git a/docs/doc/expression.html b/docs/doc/expression.html index 067eed73..81f2a048 100644 --- a/docs/doc/expression.html +++ b/docs/doc/expression.html @@ -8,7 +8,7 @@ <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="syntax.html#constants">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 behave similar to functions. Functions can be applied to subjects or grouped into trains, while modifiers can be applied to subjects or functions. The most important kinds of application are:</p> +<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> @@ -55,11 +55,9 @@ </tr> </tbody> </table> -<p>The four roles (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>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="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="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> @@ -72,7 +70,7 @@ ┘ </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 (with non-operation types all corresponding to subjects), and the value of an expression will often have a matching type, but it doesn't have to.</p> +<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> @@ -104,10 +102,12 @@ </tr> </tbody> </table> -<p>Primitive tokens, since they have a fixed value, always have a role that matches their type. They are functions, unless they fall into one of the two modifier 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>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.</p> -<p>The role of a compound expression, formed by applying an operation to some inputs, depends on the operation applied. This system is discussed in the remaining sections below.</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> @@ -115,10 +115,10 @@ <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 would 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 argument in a train because 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> +<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 modifier and function application rules:</p> +<p>Here is a table of the <a href="ops.html">function and modifier</a> application rules:</p> <table> <thead> <tr> @@ -174,15 +174,20 @@ </tr> </tbody> </table> -<p>A function with an asterisk 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> +<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>Another element that can be included in expressions is assignment, which is written with <code><span class='Gets'>←</span></code> to <em>define</em> (also called "declare" in many other languages) a variable and <code><span class='Gets'>↩</span></code> to <em>change</em> its definition. 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 it is defined again in an inner scope even though it has a definition in an outer scope already.</p> +<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 value being assigned. The role of the identifier used must match the value being assigned.</p> +<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> @@ -218,7 +223,7 @@ <span class='Value'>s</span> ⟨ 0 1 2 3 ⟩ </pre> -<p>Array destructuring using <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> +<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 ⟩ @@ -228,7 +233,7 @@ <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> +<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> @@ -237,12 +242,11 @@ </span>6 </pre> <h3 id="exports"><a class="header" href="#exports">Exports</a></h3> -<p>The double arrow <code><span class='Gets'>⇐</span></code> is used to export variables from a block or program, causing the result to be a <a href="namespace.html">namespace</a>. There are two ways to export variables. First, <code><span class='Gets'>←</span></code> in the variable definition can be replaced with <code><span class='Gets'>⇐</span></code> to export the variable as it's defined. Second, an export statement consisting of an assignment target followed by <code><span class='Gets'>⇐</span></code> with nothing to the right exports the variables in the assignment target and does nothing else. Export statements can be placed anywhere in the relevant program or body, including before declaration or on the last line, and a given variable can be exported any number of times.</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='Separator'>,</span> <span class='Value'>c0</span><span class='Ligature'>‿</span><span class='Value'>c1</span><span class='Gets'>⇐</span><span class='Value'>c</span><span class='Separator'>,</span> <span class='Value'>b2</span><span class='Gets'>⇐</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='Comment'># Non-definition exports can go anywhere -</span> <span class='Value'>a</span><span class='Gets'>⇐</span><span class='Number'>2</span> <span class='Comment'># Define and export -</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='Value'>c</span><span class='Gets'>←</span><span class='Value'>b</span><span class='Ligature'>‿</span><span class='String'>"str"</span> +<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> -<p>Fields of the resulting namespace can be accessed either directly using <code><span class='Value'>namespace.field</span></code> syntax, or with a destructuring assignment as shown above. This assignment's target is a list where each element specifies one of the names exported by the block and what it should be assigned to. The element can be either a single name (such as <code><span class='Value'>b</span></code> above), which gives both, or a combination of the assignment target, then <code><span class='Gets'>⇐</span></code>, then a name. If <code><span class='Gets'>⇐</span></code> is never used, the names can be given as a strand with <code><span class='Ligature'>‿</span></code>. To use <code><span class='Gets'>⇐</span></code> for aliases, bracket syntax <code><span class='Bracket'>⟨⟩</span></code> is needed. Imported names can be repeated and can be spelled with any role (the role is ignored).</p> diff --git a/docs/doc/syntax.html b/docs/doc/syntax.html index a5c75b6e..431156d3 100644 --- a/docs/doc/syntax.html +++ b/docs/doc/syntax.html @@ -46,7 +46,7 @@ </tr> <tr> <td><code><span class='Gets'>⇐</span></code></td> -<td><a href="expression.html#exports">Export</a></td> +<td><a href="namespace.html#exports">Export</a></td> </tr> <tr> <td><code><span class='Gets'>↩</span></code></td> diff --git a/docs/help/export.html b/docs/help/export.html index a693a7a6..cf213787 100644 --- a/docs/help/export.html +++ b/docs/help/export.html @@ -6,7 +6,7 @@ <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">help</a></div> <h1 id="leftward-double-arrow-"><a class="header" href="#leftward-double-arrow-">Leftward Double Arrow (<code><span class='Gets'>⇐</span></code>)</a></h1> <h2 id="n--v-export-definition"><a class="header" href="#n--v-export-definition"><code><span class='Value'>n</span> <span class='Gets'>⇐</span> <span class='Value'>v</span></code>: Export Definition</a></h2> -<p><a class="fulldoc" href="../doc/expression.html#exports">→full documentation</a></p> +<p><a class="fulldoc" href="../doc/namespace.html#exports">→full documentation</a></p> <p>Define a variable with name <code><span class='Value'>n</span></code> and export it from the current namespace.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=bnMg4oaQIHsgZXhwb3J0ZWQg4oeQIDUsIHVuZXhwb3J0ZWQg4oaQIDB9Cm5zLmV4cG9ydGVkCm5zLnVuZXhwb3J0ZWQ=">↗️</a><pre> <span class='Value'>ns</span> <span class='Gets'>←</span> <span class='Brace'>{</span> <span class='Value'>exported</span> <span class='Gets'>⇐</span> <span class='Number'>5</span><span class='Separator'>,</span> <span class='Value'>unexported</span> <span class='Gets'>←</span> <span class='Number'>0</span><span class='Brace'>}</span> <span class='Value'>ns.exported</span> @@ -15,7 +15,7 @@ <span class='Error'>Error: No key found</span> </pre> <h2 id="n--export-names"><a class="header" href="#n--export-names"><code><span class='Value'>n</span> <span class='Gets'>⇐</span></code>: Export names</a></h2> -<p><a class="fulldoc" href="../doc/expression.html#exports">→full documentation</a></p> +<p><a class="fulldoc" href="../doc/namespace.html#exports">→full documentation</a></p> <p>Export the names given in <code><span class='Value'>n</span></code> from the current namespace. Names must be defined somewhere in the scope.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=bnMxIOKGkCB7IOKfqGFsc29leHBvcnRlZOKfqeKHkCwgZXhwb3J0ZWQg4oeQIDUsIGFsc29leHBvcnRlZCDihpAgMH0KbnMxLmV4cG9ydGVkCm5zMS5hbHNvZXhwb3J0ZWQ=">↗️</a><pre> <span class='Value'>ns1</span> <span class='Gets'>←</span> <span class='Brace'>{</span> <span class='Bracket'>⟨</span><span class='Value'>alsoexported</span><span class='Bracket'>⟩</span><span class='Gets'>⇐</span><span class='Separator'>,</span> <span class='Value'>exported</span> <span class='Gets'>⇐</span> <span class='Number'>5</span><span class='Separator'>,</span> <span class='Value'>alsoexported</span> <span class='Gets'>←</span> <span class='Number'>0</span><span class='Brace'>}</span> <span class='Value'>ns1.exported</span> |