diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2020-07-20 14:05:36 -0400 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2020-07-20 14:05:36 -0400 |
| commit | e52d50ed594dd5626523ca7931315e47bde8c9d1 (patch) | |
| tree | d355718d8f81ea0773cd177e5b5eb17e043a5da3 /docs | |
| parent | 883eda3df8e162e2d8a62b4d1ec03eadcf8b8069 (diff) | |
Make header id slugs match Github's
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/doc/context.html | 8 | ||||
| -rw-r--r-- | docs/doc/fromDyalog.html | 2 | ||||
| -rw-r--r-- | docs/doc/logic.html | 4 | ||||
| -rw-r--r-- | docs/index.html | 6 | ||||
| -rw-r--r-- | docs/problems.html | 36 | ||||
| -rw-r--r-- | docs/running.html | 6 | ||||
| -rw-r--r-- | docs/spec/evaluate.html | 2 | ||||
| -rw-r--r-- | docs/spec/grammar.html | 2 | ||||
| -rw-r--r-- | docs/spec/literal.html | 2 | ||||
| -rw-r--r-- | docs/spec/token.html | 2 | ||||
| -rw-r--r-- | docs/spec/types.html | 2 |
11 files changed, 36 insertions, 36 deletions
diff --git a/docs/doc/context.html b/docs/doc/context.html index 90963840..b4c5616f 100644 --- a/docs/doc/context.html +++ b/docs/doc/context.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="bqn-s-context-free-grammar">BQN's context-free grammar</h1> +<h1 id="bqns-context-free-grammar">BQN's context-free grammar</h1> <p>APL has a problem. To illustrate, let's look at an APL expression:</p> <pre><span class='Value'>a</span> <span class='Value'>b</span> <span class='Value'>c</span> <span class='Value'>d</span> <span class='Value'>e</span> </pre> @@ -12,12 +12,12 @@ <pre><span class='Value'>a</span> <span class='Function'>B</span> <span class='Function'>C</span> <span class='Modifier'>_d</span> <span class='Value'>e</span> </pre> <p>Here, the lowercase spelling indicates that <code><span class='Value'>a</span></code> and <code><span class='Value'>e</span></code> are to be treated as subjects ("arrays" in APL) while the uppercase spelling of variables <code><span class='Function'>B</span></code> and <code><span class='Function'>C</span></code> are used as functions and <code><span class='Modifier'>_d</span></code> is a 1-modifier ("monadic operator"). Like parentheses for function application, the spelling is not inherent to the variable values used, but instead indicates their grammatical role in this particular expression. A variable has no inherent spelling and can be used in any role, so the names <code><span class='Value'>a</span></code>, <code><span class='Function'>A</span></code>, <code><span class='Modifier'>_a</span></code>, and <code><span class='Modifier2'>_a_</span></code> all refer to exact same variable, but in different roles; typically we use the lowercase name to refer to the variable in isolation—all values are nouns when speaking about them in English. While we still don't know anything about what values <code><span class='Value'>a</span></code>, <code><span class='Value'>b</span></code>, <code><span class='Value'>c</span></code>, and so on have, we know how they interact in the line of code above.</p> -<h2 id="is-grammatical-context-really-a-problem-">Is grammatical context really a problem?</h2> +<h2 id="is-grammatical-context-really-a-problem">Is grammatical context really a problem?</h2> <p>Yes, in the sense of <a href="../problems.html">problems with BQN</a>. A grammar that uses context is harder for humans to read and machines to execute. A particular difficulty is that parts of an expression you don't yet understand can interfere with parts you do, making it difficult to work through an unknown codebase.</p> <p>One difficulty beginners to APL will encounter is that code in APL at first appears like a string of undifferentiated symbols. For example, a tacit Unique Mask implementation <code><span class='Value'>⍳⍨</span><span class='Function'>=</span><span class='Value'>⍳</span><span class='Modifier2'>∘</span><span class='Function'>≢</span></code> consists of six largely unfamiliar characters with little to distinguish them (in fact, the one obvious bit of structure, the repeated <code><span class='Value'>⍳</span></code>, is misleading as it means different things in each case!). Simply placing parentheses into the expression, like <code><span class='Paren'>(</span><span class='Value'>⍳⍨</span><span class='Paren'>)</span><span class='Function'>=</span><span class='Paren'>(</span><span class='Value'>⍳</span><span class='Modifier2'>∘</span><span class='Function'>≢</span><span class='Paren'>)</span></code>, can be a great help to a beginner, and part of learning APL is to naturally see where the parentheses should go. The equivalent BQN expression, <code><span class='Function'>⊐</span><span class='Modifier'>˜</span><span class='Function'>=↕</span><span class='Modifier2'>∘</span><span class='Function'>≠</span></code>, will likely appear equally intimidating at first, but the path to learning which things apply to which is much shorter: rather than learning the entire list of APL primitives, a beginner just needs to know that superscript characters like <code><span class='Modifier'>˜</span></code> are 1-modifiers and characters like <code><span class='Modifier2'>∘</span></code> with unbroken circles are 2-modifiers before beginning to learn the BQN grammar that will explain how to tie the various parts together.</p> <p>This sounds like a distant concern to a master of APL or a computer that has no difficulty memorizing a few dozen glyphs. Quite the opposite: the same concern applies to variables whenever you begin work with an unfamiliar codebase! Many APL programmers even enforce variable name conventions to ensure they know the class of a variable. By having such a system built in, BQN keeps you from having to rely on programmers following a style guide, and also allows greater flexibility, including <a href="functional.html">functional programming</a>, as we'll see later.</p> <p>Shouldn't a codebase define all the variables it uses, so we can see their class from the definition? Not always: consider that in a language with libraries, code might be imported from dependencies. Many APLs also have some dynamic features that can allow a variable to have more than one class, such as the <code><span class='Value'>⍺</span><span class='Gets'>←</span><span class='Function'>⊢</span></code> pattern in a dfn that makes <code><span class='Value'>⍺</span></code> an array in the dyadic case but a function in the monadic case. Regardless, searching for a definition somewhere in the code is certainly a lot more work than knowing the class just from looking! One final difficulty is that even one unknown can delay understanding of an entire expression. Suppose in <code><span class='Function'>A</span> <span class='Function'>B</span> <span class='Value'>c</span></code>, <code><span class='Function'>B</span></code> is a function and <code><span class='Value'>c</span></code> is an array, and both values are known to be constant. If <code><span class='Function'>A</span></code> is known to be a function (even if its value is not yet known), its right argument <code><span class='Function'>B</span> <span class='Value'>c</span></code> can be evaluated ahead of time. But if <code><span class='Function'>A</span></code>'s type isn't known, it's impossible to know if this optimization is worth it, because if it is an array, <code><span class='Function'>B</span></code> will instead be called dyadically.</p> -<h2 id="bqn-s-spelling-system">BQN's spelling system</h2> +<h2 id="bqns-spelling-system">BQN's spelling system</h2> <p>BQN's expression grammar is a simplified version of the typical APL, removing some oddities like niladic functions and the two-glyph Outer Product operator. Every value can be used in any of four syntactic roles:</p> <table> <thead> @@ -54,7 +54,7 @@ <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 brace construct <code><span class='Brace'>{}</span></code> with no header is determined by which special arguments it uses: it's a subject if there are none, 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> -<h2 id="bqn-s-grammar">BQN's grammar</h2> +<h2 id="bqns-grammar">BQN's grammar</h2> <p>A formal treatment is included in <a href="../spec/grammar.html">the spec</a>. BQN's grammar—the ways syntactic roles interact—follows the original APL model (plus trains) closely, with allowances for new features like list notation. In order to keep BQN's syntax context-free, the syntactic role of any expression must be known from its contents, just like tokens.</p> <p>Here is a table of the APL-derived modifier and function application rules:</p> <table> diff --git a/docs/doc/fromDyalog.html b/docs/doc/fromDyalog.html index 70bdb134..0b9ca972 100644 --- a/docs/doc/fromDyalog.html +++ b/docs/doc/fromDyalog.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="bqn-dyalog-apl-dictionary">BQN–Dyalog APL dictionary</h1> +<h1 id="bqndyalog-apl-dictionary">BQN–Dyalog APL dictionary</h1> <p>A few tables to help users of Dyalog APL (or similar) get started quickly on BQN. Here we assume <code><span class='Value'>⎕</span><span class='Function'>ML</span></code> is 1 for Dyalog.</p> <h2 id="for-reading">For reading</h2> <p>Here are some closest equivalents in Dyalog APL for the BQN functions that don't use the same glyphs as APL. Correspondence can be approximate, and <code><span class='Function'>⌽</span></code> is just used as a decorator to mean "reverse some things".</p> diff --git a/docs/doc/logic.html b/docs/doc/logic.html index 7ac951d8..d9d8a405 100644 --- a/docs/doc/logic.html +++ b/docs/doc/logic.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="logic-functions--and--or--not--also-span-">Logic functions: And, Or, Not (also Span)</h1> +<h1 id="logic-functions-and-or-not-also-span">Logic functions: And, Or, Not (also Span)</h1> <p>BQN retains the APL symbols <code><span class='Function'>∧</span></code> and <code><span class='Function'>∨</span></code> for logical <em>and</em> and <em>or</em>, and changed APL's <code><span class='Value'>~</span></code> to <code><span class='Function'>¬</span></code> for <em>not</em>, since <code><span class='Value'>~</span></code> looks too much like <code><span class='Modifier'>˜</span></code> and <code><span class='Function'>¬</span></code> is more common in mathematics today. Like J, BQN extends Not to the linear function <code><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>-</span></code>. However, it discards <a href="https://aplwiki.com/wiki/GCD">GCD</a> and <a href="https://aplwiki.com/wiki/LCM">LCM</a> as extensions of And and Or, and instead uses bilinear extensions: And is identical to Times (<code><span class='Function'>×</span></code>), while Or is <code><span class='Function'>×</span><span class='Modifier2'>⌾</span><span class='Function'>¬</span></code>, following De Morgan's laws (other ways of obtaining a function for Or give an equivalent result—there is only one bilinear extension).</p> <p>If the arguments are probabilities of independent events, then an extended function gives the probability of the boolean function on their outcomes (for example, if <em>A</em> occurs with probability <code><span class='Value'>a</span></code> and <em>B</em> with probability <code><span class='Value'>b</span></code> independent of <em>A</em>, then <em>A</em> or <em>B</em> occurs with probability <code><span class='Value'>a</span><span class='Function'>∨</span><span class='Value'>b</span></code>). These extensions have also been used in complexity theory, because they allow mathematicians to transfer a logical circuit from the discrete to the continuous domain in order to use calculus on it.</p> <p>Both valences of <code><span class='Function'>¬</span></code> are equivalent to the fork <code><span class='Number'>1</span><span class='Function'>+-</span></code>. The dyadic valence, called "Span", computes the number of integers in the range from <code><span class='Value'>𝕩</span></code> to <code><span class='Value'>𝕨</span></code>, inclusive, when both arguments are integers and <code><span class='Value'>𝕩</span><span class='Function'>≤</span><span class='Value'>𝕨</span></code> (note the reversed order, which is used for consistency with subtraction). This function has many uses, and in particular is relevant to the <a href="windows.html">Windows</a> function.</p> @@ -29,7 +29,7 @@ 1 1 1 </pre> <p>As with logical And and Or, any value and 0 is 0, while any value or 1 is 1. The other boolean values give the identity elements for the two functions: 1 and any value gives that value, as does 0 or the value.</p> -<h2 id="why-not-gcd-and-lcm-">Why not GCD and LCM?</h2> +<h2 id="why-not-gcd-and-lcm">Why not GCD and LCM?</h2> <p>The main reason for omitting these functions is that they are complicated and, when applied to real or complex numbers, require a significant number of design decisions where there is no obvious choice (for example, whether to use comparison tolerance). On the other hand, these functions are fairly easy to implement, which allows the programmer to control the details, and also add functionality such as the extended GCD.</p> <p>A secondary reason is that the GCD falls short as an extension of Or, because its identity element 0 is not total. <code><span class='Number'>0</span><span class='Function'>∨</span><span class='Value'>x</span></code>, for a real number <code><span class='Value'>x</span></code>, is actually equal to <code><span class='Function'>|</span><span class='Value'>x</span></code> and not <code><span class='Value'>x</span></code>: for example, <code><span class='Number'>0</span><span class='Function'>∨</span><span class='Number'>¯2</span></code> is <code><span class='Number'>2</span></code> in APL. This means the identity <code><span class='Number'>0</span><span class='Function'>∨</span><span class='Value'>x</span> <span class='Gets'>←→</span> <span class='Value'>x</span></code> isn't reliable in APL.</p> <h2 id="identity-elements">Identity elements</h2> diff --git a/docs/index.html b/docs/index.html index fc10eaa2..85f6ac77 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,6 +1,6 @@ <head><link href="style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="bqn--finally--an-apl-for-your-flying-saucer">BQN: finally, an APL for your flying saucer</h1> +<h1 id="bqn-finally-an-apl-for-your-flying-saucer">BQN: finally, an APL for your flying saucer</h1> <p><em>This repository does not yet have a working implementation. However, there are some incomplete implementations you can use, with one you can try online <a href="https://mlochbaum.github.io/BQN2NGN/web/index.html">here</a>. See <a href="running.html">running.md</a> for more.</em></p> <p><strong>BQN</strong> is a new programming language in the APL lineage, which aims to remove inconsistent and burdensome aspects of the APL tradition and put the great ideas on a firmer footing. BQN is aimed at existing and aspiring APL-family programmers, and using it requires a solid understanding of functions and multidimensional arrays. However, because of its focus on providing simple, consistent, and powerful array operations, BQN should also be a good language for learning array programming and building stronger array intuition.</p> <p>BQN maintains many of the ideas that made APL\360 revolutionary in 1966:</p> @@ -22,9 +22,9 @@ <li>Oh, and it naturally leads to <a href="doc/functional.html"><strong>first-class functions</strong></a>, a feature often missed in APL.</li> <li>The <strong>new symbols</strong> for built-in functionality allow the syntactic role of a primitive to be distinguished at a glance, and aim to be more consistent and intuitive.</li> </ul> -<h2 id="what-kind-of-name-is--bqn--">What kind of name is "BQN"?</h2> +<h2 id="what-kind-of-name-is-bqn">What kind of name is "BQN"?</h2> <p>It's three letters, that happen to match the capitals in "Big Questions Notation". You can pronounce it "bacon", but are advised to avoid this unless there's puns.</p> -<h2 id="what-does-bqn-look-like-">What does BQN look like?</h2> +<h2 id="what-does-bqn-look-like">What does BQN look like?</h2> <p>Rather strange, most likely:</p> <pre><span class='Function'>⊑+</span><span class='Modifier'>`</span><span class='Modifier2'>∘</span><span class='Function'>⌽</span><span class='Modifier2'>⍟</span><span class='Number'>12</span><span class='Function'>↕</span><span class='Number'>2</span> <span class='Comment'># The 12th Fibonacci number </span></pre> diff --git a/docs/problems.html b/docs/problems.html index b2ea1faa..252cdb1c 100644 --- a/docs/problems.html +++ b/docs/problems.html @@ -28,9 +28,9 @@ <li><code><span class='Function'>𝔽</span><span class='Modifier'>¨´</span><span class='Function'><</span><span class='Modifier'>˘</span></code> Apply it between elements of an array, enclosing results to get a new array (NARS).</li> </ul> <p>It seems that the first is the most common, but the others aren't really rare. The current list reduction also encourages patterns like <code><span class='Function'>+</span><span class='Modifier'>´˘</span><span class='Number'>2</span><span class='Function'>↕</span><span class='Value'>mat</span></code>, which don't work on higher-rank arrays and mix the result (possibly unwanted).</p> -<h3 id="subtraction--division--and-span-are-backwards">Subtraction, division, and span are backwards</h3> +<h3 id="subtraction-division-and-span-are-backwards">Subtraction, division, and span are backwards</h3> <p>The left argument feels much more like the primary one in these cases (indeed, this matches the typical left-to-right ordering of binary operators in mathematics). Not really fixable; too much precedent.</p> -<h3 id="can-t-access-array-ordering-directly">Can't access array ordering directly</h3> +<h3 id="cant-access-array-ordering-directly">Can't access array ordering directly</h3> <p>Only <code><span class='Function'>⍋⍒</span></code> use array ordering rather than just array equality or numeric ordering. Getting at the actual ordering to just compare two arrays is more difficult than it should be (but not <em>that</em> difficult: <code><span class='Function'>⥊</span><span class='Modifier2'>⊸</span><span class='Function'>⍋</span><span class='Modifier2'>⌾</span><span class='Function'><</span></code> is TAO <code><span class='Function'>≤</span></code>).</p> <h3 id="syntactic-type-erasure">Syntactic type erasure</h3> <p>A programmer can call a modifier on either a syntactic function or subject, but there's no way to know within the modifier which syntax that operand had. Maybe this is a better design, but it doesn't feel quite right that <code><span class='Value'>f</span><span class='Modifier'>˜</span></code> is <code><span class='Value'>f</span></code>-Swap if <code><span class='Value'>f</span></code> has a function value. The subject syntax suggests it should be Constant.</p> @@ -58,35 +58,35 @@ <p>Characters <code><span class='Function'>⥊∾</span><span class='Modifier2'>⟜⎉⚇</span><span class='Modifier'>˜</span></code> and double-struck letters are either missing from many fonts or drawn strangely.</p> <h3 id="index-of-privileges-the-first-match">Index Of privileges the first match</h3> <p>It could be more sound to look at all matches, but using just the first one is too convenient. J has an index-of-last function; in BQN you have to reverse the left argument and then do arithmetic: <code><span class='Function'>≠</span><span class='Modifier2'>∘</span><span class='Function'>⊣-</span><span class='Number'>1</span><span class='Function'>+⌽</span><span class='Modifier2'>⊸</span><span class='Function'>⊐</span></code>.</p> -<h3 id="glyphs-that-aren-t-great">Glyphs that aren't great</h3> +<h3 id="glyphs-that-arent-great">Glyphs that aren't great</h3> <p>Blanket issue for glyphs that need work. Currently I find <code><span class='Function'>⥊⊏⊑⊐⊒⍷</span><span class='Modifier'>⁼</span><span class='Modifier2'>⎉⚇</span></code> to not be particularly good fits for what they describe.</p> <h3 id="axis-ordering-is-big-endian">Axis ordering is big-endian</h3> <p>The most natural ordering for polynomial coefficients and base representations is little-endian, because it aligns element <code><span class='Value'>i</span></code> of the list with power <code><span class='Value'>i</span></code> of the argument or base. It also allows a forward scan instead of a reverse one. Array axes go the other way. However, there are advantages to this ordering as well. For example, it's common to act only on the first few axes, so having them at the beginning of the array is good (<code><span class='Function'>≠</span><span class='Value'>a</span> <span class='Gets'>←→</span> <span class='Function'>⊑</span><span class='Modifier2'>∘</span><span class='Function'>≢</span><span class='Value'>a</span></code>).</p> -<h3 id="trains-don-t-like-monads">Trains don't like monads</h3> +<h3 id="trains-dont-like-monads">Trains don't like monads</h3> <p>If you have the normal mix of monads and dyads you'll need a lot of parentheses and might end up abusing <code><span class='Modifier2'>⟜</span></code>. Largely solved with the "nothing" glyph <code><span class='Nothing'>·</span></code>, which acts like J's Cap (<code><span class='Value'>[:</span></code>) in a train, but still a minor frustration.</p> <h3 id="inverse-is-not-fully-specified">Inverse is not fully specified</h3> <p>So it seems a bit strange to rely on it for core language features like <code><span class='Function'>/</span><span class='Modifier'>⁼</span></code>. On the other hand, this is a good fit for <code><span class='Function'>⋆</span><span class='Modifier'>⁼</span></code> since we are taking an arbitrary branch of a complex function that has many of them. I'm pretty sure it's impossible to solve the issue as stated but it might be possible to move to less hazardous constructs. Structural Under is a start.</p> -<h3 id="monadic-----versus----">Monadic <code><span class='Function'>⊑</span></code> versus <code><span class='Function'>></span></code></h3> +<h3 id="monadic--versus-">Monadic <code><span class='Function'>⊑</span></code> versus <code><span class='Function'>></span></code></h3> <p>Both pull out elements and reduce the depth. But they face in opposite directions.</p> <p>The directions of <code><span class='Function'>⊏⊐</span></code> and so on were mainly chosen to line up with <code><span class='Function'>∊</span></code>: the argument that indices apply to (that is, the one that is searched or selected from) corresponds to the open side of the function. I'd probably prefer new glyphs that don't have this sort of directionality, however.</p> <h3 id="converting-a-function-expression-to-a-subject-is-tricky">Converting a function expression to a subject is tricky</h3> <p>You can name it, you can write <code><span class='Function'>⊑</span><span class='Bracket'>⟨</span><span class='Function'>Expr</span><span class='Bracket'>⟩</span></code>, and if it doesn't use special names you can write <code><span class='Brace'>{</span><span class='Function'>Expr</span><span class='Brace'>}</span></code>. All of these are at least a little awkward in reasonable cases. Should there be a dedicated syntax? Note that going the other way, from subject to function, isn't too bad: the modifier <code><span class='Brace'>{</span><span class='Function'>𝔽</span><span class='Brace'>}</span></code> does it.</p> -<h3 id="monadic-argument-corresponds-to-left-for-----and----">Monadic argument corresponds to left for <code><span class='Function'>/</span></code> and <code><span class='Function'>⊔</span></code></h3> +<h3 id="monadic-argument-corresponds-to-left-for--and-">Monadic argument corresponds to left for <code><span class='Function'>/</span></code> and <code><span class='Function'>⊔</span></code></h3> <p>Called dyadically, both functions shuffle cells of the right argument around, which is consistent with other selection-type functions. But the monadic case applies to what would be the left argument in the dyadic case.</p> -<h3 id="prefixes-suffixes-add-depth-and-windows-doesn-t">Prefixes/Suffixes add depth and Windows doesn't</h3> +<h3 id="prefixessuffixes-add-depth-and-windows-doesnt">Prefixes/Suffixes add depth and Windows doesn't</h3> <p>It's an awkward inconsistency. Prefixes and Suffixes have to have a nested result, but Windows doesn't have to be flat; it's just that making it nested ignores the fact that it does have an array structure.</p> -<h3 id="rank-depth-negative-zero">Rank/Depth negative zero</h3> +<h3 id="rankdepth-negative-zero">Rank/Depth negative zero</h3> <p>A positive operand to Rank indicates the cell rank, so positive zero means to act on 0-cells. A negative operand indicates the frame length, so negative zero should act on the entire array. But it can't because it's equal to positive zero. Similar issue with Depth. Positive/negative is not really the right way to encode the frame/cell distinction, but it's convenient. Fortunately ∞ can be used in place of negative zero, but there can still be problems if the rank is computed.</p> -<h3 id="must-read-the-body-to-find-explicit-definition-s-type">Must read the body to find explicit definition's type</h3> +<h3 id="must-read-the-body-to-find-explicit-definitions-type">Must read the body to find explicit definition's type</h3> <p>You have to scan for headers or double-struck names (and so does a compiler). A little inelegant, and difficult to describe in BNF.</p> -<h3 id="can-t-take-prefixes-or-suffixes-on-multiple-axes">Can't take Prefixes or Suffixes on multiple axes</h3> +<h3 id="cant-take-prefixes-or-suffixes-on-multiple-axes">Can't take Prefixes or Suffixes on multiple axes</h3> <p>This is a natural array operation to do, and results in an array with a joinable structure, but as Prefixes and Suffixes are monadic there's no way to specify the number of axes to use.</p> -<h3 id="and-or-max-min-are-all-tangled-up">And/Or/Max/Min are all tangled up</h3> +<h3 id="andormaxmin-are-all-tangled-up">And/Or/Max/Min are all tangled up</h3> <p>Boolean And (<code><span class='Function'>∧</span></code>) and Or (<code><span class='Function'>∨</span></code>) are identical to Min (<code><span class='Function'>⌊</span></code>) and Max (<code><span class='Function'>⌈</span></code>) when restricted to Boolean arguments, and this would fit nicely with their monadic role as sorting functions: for example <code><span class='Value'>a</span><span class='Function'>∧</span><span class='Value'>b</span> <span class='Gets'>←→</span> <span class='Function'>⊑∧</span><span class='Value'>a</span><span class='Ligature'>‿</span><span class='Value'>b</span></code>. Furthermore the pairing of Min with Floor and Max with Ceiling is mnemonic only and not especially natural. The reason I have not used these glyphs for Min and Max, and have instead extended them to the somewhat superfluous <a href="doc/logic.html">arithmetic logical functions</a> is that Min and Max have different <a href="https://aplwiki.com/wiki/Identity_element">identity elements</a> of <code><span class='Number'>∞</span></code> and <code><span class='Number'>¯∞</span></code> rather than <code><span class='Number'>1</span></code> and <code><span class='Number'>0</span></code>. Having to code around empty arrays when using <code><span class='Function'>∧</span><span class='Modifier'>´</span></code> would be a fairly big issue.</p> <p>The other drawback of Min (<code><span class='Function'>∧</span></code>) and Max (<code><span class='Function'>∨</span></code>) is that the symbols are counterintuitive, but I have found a way to remember them: consider the graph of variables <code><span class='Value'>a</span><span class='Gets'>←</span><span class='Value'>x</span></code> and <code><span class='Value'>b</span><span class='Gets'>←</span><span class='Function'>¬</span><span class='Value'>x</span></code> for x from 0 to 1: two crossed lines. Now the graph of <code><span class='Value'>a</span><span class='Function'>∧</span><span class='Value'>b</span></code> is a caret shape and <code><span class='Value'>a</span><span class='Function'>∨</span><span class='Value'>b</span></code> is a vee.</p> <h3 id="acting-on-windows-can-be-awkward">Acting on windows can be awkward</h3> <p>When taking Windows along more than one axis, acting on the resulting array requires the Rank modifier, duplicating either the right argument rank or (negated) left argument length. A nested Windows would only require Each.</p> -<h3 id="group-doesn-t-include-trailing-empty-groups">Group doesn't include trailing empty groups</h3> +<h3 id="group-doesnt-include-trailing-empty-groups">Group doesn't include trailing empty groups</h3> <p>But there are workarounds, described in <a href="doc/group.html">its documentation</a>. dzaima has suggested allowing a single extra element in the index argument to specify the result shape. Another possibility is for the result prototype to be specified to allow overtaking.</p> <h3 id="scan-ordering-is-weird">Scan ordering is weird</h3> <p>Scan moves along the array so that it uses results as left arguments, which is opposite to the usual right-to-left order of evaluation. But I think this is still better than scanning the array in reverse. You can always use Swap on the operand, or recover the APL scan ordering by doing a Reduce-Each on Prefixes.</p> @@ -104,16 +104,16 @@ <p>I went with "Index of" and "Less Than or Equal to" but the last word blends into surrounding text. Should they be fully capitalized or hyphenated?</p> <h2 id="solved-problems">Solved problems</h2> <p>Problems that existed in mainstream APL or a transitional BQN that have in my opinion been put to rest (while in some cases introducing new problems). Listed in reverse chronological order by time solved, by my recollection.</p> -<h3 id="-modifier--and--composition--terminology">"Modifier" and "composition" terminology</h3> +<h3 id="modifier-and-composition-terminology">"Modifier" and "composition" terminology</h3> <p>1-modifiers and 2-modifiers used to be called "modifiers" and "compositions", respectively, and sometimes "operators" collectively. The new names are much better, although they do leave a disconnect between the names for modifiers, and those for their inputs—"operands".</p> -<h3 id="can-t-return-from-inner-functions">Can't return from inner functions</h3> +<h3 id="cant-return-from-inner-functions">Can't return from inner functions</h3> <p>Fixed by adding block returns such as <code><span class='Value'>label</span><span class='Gets'>←</span></code> to jump out of a block with header name <code><span class='Value'>label</span></code>. Hopefully these don't cause too many new problems.</p> <p>This was an issue with using functions as control flow. For example, when looping through an array with Each, you can't decide to exit early. In a curly-brace language you would just use a for loop and a return. In BQN, we need… longjmp? Maybe not as crazy as it sounds, and potentially worth it in exchange for replacing control structures.</p> <h3 id="ambivalent-explicit-functions">Ambivalent explicit functions</h3> <p>Fixed with multiple bodies: if there are two bodies with no headers such as <code><span class='Brace'>{</span><span class='Number'>2</span><span class='Function'>×</span><span class='Value'>𝕩;𝕨</span><span class='Function'>-</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code>, they are the monadic and dyadic case.</p> -<h3 id="how-to-choose-a-partitioning-function-">How to choose a partitioning function?</h3> +<h3 id="how-to-choose-a-partitioning-function">How to choose a partitioning function?</h3> <p>Fixed with <a href="doc/group.html">Group</a>, which I found May 2020. Group serves as a much improved <a href="https://aplwiki.com/wiki/Partition">Partition</a>. However, it doesn't partition along multiple axes, so a dedicated partition function that does this could also be wanted. Or could Group be made to work with multiple axes as well as multidimensional indices?</p> -<h3 id="key-doesn-t-do-what-you-want">Key doesn't do what you want</h3> +<h3 id="key-doesnt-do-what-you-want">Key doesn't do what you want</h3> <p>Fixed with <a href="doc/group.html">Group</a> to my satisfaction, except for the trailing-empty-group problem. There were various issues with Key operators in J and Dyalog, such as the fact that the ordering and presence of groups depends on where and whether the keys appear. Also, Dyalog's Key can return keys and values, but they are in a different format than the input: an array of pairs instead of two arrays. Monadic Group returns indices, which can be used how the programmer wants.</p> <h3 id="greek-letter-issues">Greek letter issues</h3> <p>Fixed by not using Greek letters. In particular, the idea of using fancy Latin letters as fixed names for function arguments was suggested in proto-BQN sessions, possibly by Nathan Rogers.</p> @@ -125,8 +125,8 @@ <p>Fixed with the casing conventions for variable names, which I think I first saw in <a href="https://aplwiki.com/wiki/APL%5Civ">APL\iv</a>, although the cases are swapped relative to BQN.</p> <h3 id="selective-assignment-requires-a-named-variable">Selective assignment requires a named variable</h3> <p>Fixed with structural Under, which I developed in 2017 and 2018.</p> -<h3 id="it-s-hard-use-an-array-as-a-major-cell">It's hard use an array as a major cell</h3> +<h3 id="its-hard-use-an-array-as-a-major-cell">It's hard use an array as a major cell</h3> <p>Fixed with <code><span class='Function'>≍</span></code>: dyadic form from A+ and monadic/dyadic pair from J.</p> -<h3 id="scan-and-windowed-reduce-shouldn-t-always-reduce">Scan and Windowed Reduce shouldn't always reduce</h3> +<h3 id="scan-and-windowed-reduce-shouldnt-always-reduce">Scan and Windowed Reduce shouldn't always reduce</h3> <p>Fixed with Prefix, Suffix, and Infix operators in J. Changed to functions in BQN.</p> diff --git a/docs/running.html b/docs/running.html index f0050150..ae4ca9ac 100644 --- a/docs/running.html +++ b/docs/running.html @@ -2,12 +2,12 @@ <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> <h1 id="how-to-run-bqn">How to run BQN</h1> <p>BQN is in a very early stage of development, and there is currently no complete implementation of the language. However, it's a relatively simple language to implement, and a few implementations come close.</p> -<h3 id="bqn-ngn">BQN2NGN</h3> +<h3 id="bqn2ngn">BQN2NGN</h3> <p><a href="https://github.com/mlochbaum/BQN2NGN">BQN2NGN</a> is a prototype implementation in Javascript build to experiment with the langauge, which is now abandoned. Because you can <a href="https://mlochbaum.github.io/BQN2NGN/web/index.html">use it online</a>, this is probably the quickest way to get started with BQN. It has good primitive support, with the main issues being that it uses a J-style insert instead of BQN-style vector reduction, that it has a different version of <a href="doc/group.html">Group</a> (<code><span class='Function'>⊔</span></code>), and that it is missing Choose (<code><span class='Modifier2'>◶</span></code>). There are also some spelling differences, with Deduplicate (<code><span class='Function'>⍷</span></code>) spelled with <code><span class='Value'>∪</span></code> and Valences (<code><span class='Modifier2'>⊘</span></code>) spelled with <code><span class='Value'>⍠</span></code>. It is missing value blocks and function headers.</p> <p>For automated testing I run BQN2NGN using the <code><span class='Value'>bqn</span></code> executable, which is just a symlink to <code><span class='Value'>apl.js</span></code> in the BQN2NGN repository. It requires Node to run.</p> -<h3 id="dzaima-bqn">dzaima/BQN</h3> +<h3 id="dzaimabqn">dzaima/BQN</h3> <p><a href="https://github.com/dzaima/BQN/">dzaima/BQN</a> is an implementation in Java created by modifying the existing dzaima/APL. It should be easy to run on desktop Linux and Android. It is still in development and has almost complete syntax support but incomplete primitive support.</p> -<h3 id="dzaima-reference-bqn">dzaima+reference BQN</h3> +<h3 id="dzaimareference-bqn">dzaima+reference BQN</h3> <p>This repository contains a dzaima/BQN script <code><span class='Value'>dzref</span></code> that fills in the gaps in primitive support using BQN implementations of primitives which are not yet up to spec (<a href="https://github.com/mlochbaum/BQN/blob/master/spec/reference.bqn">reference implementations</a> of all primitives starting from a small set of pre-existing functions are part of BQN's specification). These alternate implementations can be very slow.</p> <p>You can run <code><span class='Value'>dzref</span></code> from ordinary dzaima/BQN using the <code><span class='Value'>•</span><span class='Function'>EX</span></code> command; see for example <a href="https://github.com/mlochbaum/BQN/blob/master/dcshim.bqn">dcshim.bqn</a>. For testing, it is run as a Unix script, in which case it depends on an executable <code><span class='Value'>dbqn</span></code> that runs dzaima/BQN on a file argument. I use the following script, using the path to a clone of dzaima/BQN for the jar file.</p> <pre><span class='Comment'>#! /bin/bash diff --git a/docs/spec/evaluate.html b/docs/spec/evaluate.html index 66e49930..9f9781d3 100644 --- a/docs/spec/evaluate.html +++ b/docs/spec/evaluate.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="specification--bqn-evaluation">Specification: BQN evaluation</h1> +<h1 id="specification-bqn-evaluation">Specification: BQN evaluation</h1> <p>This page describes the semantics of the code constructs whose grammar is given in <a href="grammar.html">grammar.md</a>. The formation rules there are not named, and here they are identified by either the name of the term or by copying the rule entirely if there are several alternative productions.</p> <p>Here we assume that the referent of each identifier, or equivalently the connections between identifiers, have been identified according to the <a href="scope.html">scoping rules</a>.</p> <h3 id="programs-and-blocks">Programs and blocks</h3> diff --git a/docs/spec/grammar.html b/docs/spec/grammar.html index 8a3ead18..f6bf3810 100644 --- a/docs/spec/grammar.html +++ b/docs/spec/grammar.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="specification--bqn-grammar">Specification: BQN grammar</h1> +<h1 id="specification-bqn-grammar">Specification: BQN grammar</h1> <p>BQN's grammar is given below. Terms are defined in a <a href="https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form">BNF</a> variant. However, handling special names properly is possible but difficult in BNF, so they are explained in text along with the braced block grammar.</p> <p>The symbols <code><span class='Value'>s</span></code>, <code><span class='Function'>F</span></code>, <code><span class='Modifier'>_m</span></code>, and <code><span class='Modifier2'>_c_</span></code> are identifier tokens with subject, function, 1-modifier, and 2-modifier classes respectively. Similarly, <code><span class='Value'>sl</span></code>, <code><span class='Function'>Fl</span></code>, <code><span class='Modifier'>_ml</span></code>, and <code><span class='Modifier2'>_cl_</span></code> refer to literals and primitives of those classes. While names in the BNF here follow the identifier naming scheme, this is informative only: syntactic classes are no longer used after parsing and cannot be inspected in a running program.</p> <p>A program is a list of statements. Almost all statements are expressions. However, explicit definitions and valueless results stemming from <code><span class='Nothing'>·</span></code>, or <code><span class='Value'>𝕨</span></code> in a monadic brace function, can be used as statements but not expressions.</p> diff --git a/docs/spec/literal.html b/docs/spec/literal.html index 8cac38c5..928e64fc 100644 --- a/docs/spec/literal.html +++ b/docs/spec/literal.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="specification--bqn-literal-notation">Specification: BQN literal notation</h1> +<h1 id="specification-bqn-literal-notation">Specification: BQN literal notation</h1> <p>A <em>literal</em> is a single <a href="token.html">token</a> that indicates a fixed character, number, or array. While literals indicate values of a data type, <a href="primitive.html">primitives</a> indicate values of an operation type: function, 1-modifier, or 2-modifier.</p> <p>Two types of literal deal with text. As the source code is considered to be a sequence of unicode code points ("characters"), and these code points are also used for BQN's character <a href="types.html">data type</a>, the representation of a text literal is very similar to its value. In a text literal, the newline character is always represented using the ASCII line feed character, code point 10. A <em>character literal</em> is enclosed with single quotes <code>'</code> and its value is identical to the single character between them. A <em>string literal</em> is enclosed in double quotes <code>"</code>, and any double quotes between them must come in pairs, as a lone double quote marks the end of the literal. The value of a string literal is a rank-1 array whose elements are the characters in between the enclosing quotes, after replacing each pair of double quotes with only one such quote.</p> <p>The format of a <em>numeric literal</em> is more complicated. From the <a href="token.html">tokenization rules</a>, a numeric literal consists of a numeric character (one of <code><span class='Number'>¯∞π.0123456789</span></code>) followed by any number of numeric or alphabetic characters. Some numeric literals are <em>valid</em> and indicate a number, while others are invalid and cause an error. The grammar for valid numbers is given below in a <a href="https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form">BNF</a> variant. Only four alphabetic characters are allowed: "i", which separates the real and imaginary components of a complex number, "e", which functions as in scientific notation, and the uppercase versions of these letters.</p> diff --git a/docs/spec/token.html b/docs/spec/token.html index 9a121561..c12fc3e4 100644 --- a/docs/spec/token.html +++ b/docs/spec/token.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="specification--bqn-token-formation">Specification: BQN token formation</h1> +<h1 id="specification-bqn-token-formation">Specification: BQN token formation</h1> <p>This page describes BQN's token formation rules (token formation is also called scanning). Most tokens in BQN are a single character long, but quoted characters and strings, identifiers, and numbers can consist of multiple characters, and comments, spaces, and tabs are discarded during token formation.</p> <p>BQN source code should be considered as a series of unicode code points, which we refer to as "characters". The separator between lines in a file is considered to be a single character, newline, even though some operating systems such as Windows typically represent it with a two-character CRLF sequence. Implementers should note that not all languages treat unicode code points as atomic, as exposing the UTF-8 or UTF-16 representation instead is common. For a language such as JavaScript that uses UTF-16, the double-struck characters <code><span class='Value'>𝕨</span><span class='Function'>𝕎</span><span class='Value'>𝕩</span><span class='Function'>𝕏</span><span class='Value'>𝕗</span><span class='Function'>𝔽</span><span class='Value'>𝕘</span><span class='Function'>𝔾</span></code> are represented as two 16-bit surrogate characters, but BQN treats them as a single unit.</p> <p>A BQN <em>character literal</em> consists of a single character between single quotes, such as <code><span class='String'>'a'</span></code>, and a <em>string literal</em> consists of any number of characters between double quotes, such as <code><span class='String'>""</span></code> or <code><span class='String'>"abc"</span></code>. Character and string literals take precedence with comments over other tokenization rules, so that <code><span class='Comment'>#</span></code> between quotes does not start a comment and whitespace between quotes is not removed, but a quote within a comment does not start a character literal. Almost any character can be included directly in a character or string literal without escaping. The only exception is the double quote character <code>"</code>, which must be written twice to include it in a string, as otherwise it would end the string instead. Character literals require no escaping at all, as the length is fixed. In particular, literals for the double and single quote characters are written <code><span class='String'>'''</span></code> and <code><span class='String'>'"'</span></code>, while length-1 strings containing these characters are <code><span class='String'>"'"</span></code> and <code><span class='String'>""""</span></code>.</p> diff --git a/docs/spec/types.html b/docs/spec/types.html index 4570d2da..d3f71050 100644 --- a/docs/spec/types.html +++ b/docs/spec/types.html @@ -1,6 +1,6 @@ <head><link href="../style.css" rel="stylesheet"/></head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div> -<h1 id="specification--bqn-types">Specification: BQN types</h1> +<h1 id="specification-bqn-types">Specification: BQN types</h1> <p>BQN programs manipulate data of six types:</p> <ul> <li>Character</li> |