diff options
Diffstat (limited to 'docs/tutorial')
| -rw-r--r-- | docs/tutorial/combinator.html | 24 | ||||
| -rw-r--r-- | docs/tutorial/expression.html | 16 | ||||
| -rw-r--r-- | docs/tutorial/index.html | 2 | ||||
| -rw-r--r-- | docs/tutorial/list.html | 16 | ||||
| -rw-r--r-- | docs/tutorial/variable.html | 14 |
5 files changed, 36 insertions, 36 deletions
diff --git a/docs/tutorial/combinator.html b/docs/tutorial/combinator.html index 5052aad1..a9cd7627 100644 --- a/docs/tutorial/combinator.html +++ b/docs/tutorial/combinator.html @@ -4,11 +4,11 @@ <title>BQN Tutorial: Combinators</title> </head> <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">tutorial</a></div> -<h1 id="tutorial-combinators">Tutorial: Combinators</h1> +<h1 id="tutorial-combinators"><a class="header" href="#tutorial-combinators">Tutorial: Combinators</a></h1> <p>BQN has a normal enough curly-brace syntax for functions and so on. I don't want to talk about it just yet. Before you get to thinking about how to write <a href="http://www.pbm.com/~lindahl/real.programmers.html">FORTRAN in any language</a> in BQN, let's see if we can acquire some instincts about idiomatic BQN the way that only being stuck in a tightly restricted and horribly confining programming environment can accomplish.</p> <p>There are benefits to being tightly restricted and horribly confined! In programming. I don't just mean that it forces you to learn new techniques like I said, I mean that using the restricted style we will learn is actually a better way to write portions of a program. This is because a restriction you apply in one part of a program is a promise you can rely on in the rest of the program. So what are we giving up, and what can we rely on in return?</p> <p><em>Tacit programming</em> does not use variables during the execution of a function (but you might use them for convenience in order to <em>construct</em> a tacit program). Variables allow you to use any accessible value in the program with the same level of ease. Tacit code doesn't. In fact it becomes pretty unusable when more than about three values are active at once. One consequence is that tacit code won't cause confusion by modifying far-away variables. But something unique to the tacit paradigm is that when only a small number of values are active—which is always true in a small enough portion of a program!—it has more powerful ways to describe the way these values flow through the program. The main way it achieves this is with combinators.</p> -<h2 id="whats-a-combinator">What's a combinator?</h2> +<h2 id="whats-a-combinator"><a class="header" href="#whats-a-combinator">What's a combinator?</a></h2> <p>(It's when you can't stop adding suffixes to "combine"). In the first tutorial, we briefly presented three <em>combinators</em>, <code><span class='Modifier2'>∘</span></code>, <code><span class='Modifier'>˜</span></code>, and <code><span class='Modifier'>˙</span></code>. These are functions or modifiers that produce a result from their inputs (arguments or operands) only by applying functions to arguments. For example, let's look at a composition:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=fOKImC0gNg==">↗️</a><pre> <span class='Function'>|</span><span class='Modifier2'>∘</span><span class='Function'>-</span> <span class='Number'>6</span> 6 @@ -156,7 +156,7 @@ </g> </svg> -<h2 id="comparisons">Comparisons</h2> +<h2 id="comparisons"><a class="header" href="#comparisons">Comparisons</a></h2> <table class='primitives'> <tr> <td><span class='Function'><</span></td> @@ -205,7 +205,7 @@ <span class='Number'>∞</span> <span class='Function'><</span> <span class='String'>@</span> 1 </pre> -<h3 id="booleans">Booleans</h3> +<h3 id="booleans"><a class="header" href="#booleans">Booleans</a></h3> <p>The return values <code><span class='Number'>0</span></code> and <code><span class='Number'>1</span></code> are natural choices because BQN has no dedicated boolean type: instead, in BQN, the word <em>boolean</em> indicates a number that's 0 or 1, much like "natural number" selects a subset of the possible numbers. This is a choice that might be at odds with your own programming experience, and especially clashes with the world of typed functional programming, where even using the boolean type rather than a dedicated type for an option might be considered a code smell! The design principle guiding this decision, and most of BQN's type system, is that there should only be one type that accomplishes any given programming task. Any distinctions that it has are there because they are really necessary: conflating numbers and characters would make working with strings too difficult, and functions can't really be combined with modifiers because one-argument functions and 1-modifiers take their inputs on different sides.</p> <p>The advantage of this strategy is that you will spend much less time thinking about types when writing programs. The decisions are already made: if there are a few things, they go in a list; if there a few possible values in a qualitative category then they should be labelled with numbers. And if some value has multiple interpretations then BQN is less likely to require an explicit conversion between these. For example, while the result of <code><span class='Function'>=</span></code> might be taking to say <em>whether</em> two atoms have equal values, maybe it also says <em>how many times</em> the atom on the left appears in the right argument—which is at most one, because there's only one right argument. A silly distinction, or is it? An important property of counts is that we can add them together, for instance, to find how many times the letter "e" appears in a string.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=J2UnID0gIkdlb3JnZSBCb29sZSIKCivCtCAnZScgPSAiR2VvcmdlIEJvb2xlIgoKJ2UnICvCtOKImD0gIkdlb3JnZSBCb29sZSIgICMgV2l0aCBhIGNvbWJpbmF0b3I=">↗️</a><pre> <span class='String'>'e'</span> <span class='Function'>=</span> <span class='String'>"George Boole"</span> @@ -218,7 +218,7 @@ </span>3 </pre> <p>This, a well-typed and well-spoken programmer should declare, is an outrage! The purpose of types is to <em>protect</em> us from applying functions to types they're not intended for, because the most likely result is that such an application doesn't make sense. Static types provide a valuable service by catching these dangerous actions at compile time and allowing a programmer to prove that they never happen. Well… this is all true. BQN chooses not to pay the type price of this service and so doesn't get the type protection. And it helps that it's consistent about this choice, so you know that BQN's types are never the answer to these sorts of safety concerns. You will have to find a different way to avoid type errors: perhaps just programming carefully in a small or one-off program, and testing and code review or even external tools in a large one. All that said, I think programmers from outside the array programming world (and even many inside!) drastically underestimate how often a boolean value is really just a narrow-minded take on a counting number.</p> -<h3 id="comparing-whole-arrays">Comparing whole arrays</h3> +<h3 id="comparing-whole-arrays"><a class="header" href="#comparing-whole-arrays">Comparing whole arrays</a></h3> <table class='primitives'> <tr> <td><span class='Function'>≡</span></td> @@ -250,7 +250,7 @@ <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span> <span class='Function'>≢</span> <span class='Number'>3</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> 1 </pre> -<h2 id="length-rank-and-depth">Length, rank, and depth</h2> +<h2 id="length-rank-and-depth"><a class="header" href="#length-rank-and-depth">Length, rank, and depth</a></h2> <p>I said above that the comparison functions might have a different meaning when called with only one argument, so let's cover a few of these.</p> <p>Length (<code><span class='Function'>≠</span></code>) gives the number of elements in a list. For atoms it returns 1; it can't result in an error.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omgICJ0ZXN0aW5nIgriiaAg4p+o4p+pCuKJoCDin6ggz4AsIOKImCwgImVsZW1lbnQiIOKLhCDin6gnbCcsMSw1LCd0J+KfqSDin6kK4omgIDQ=">↗️</a><pre> <span class='Function'>≠</span> <span class='String'>"testing"</span> @@ -281,9 +281,9 @@ </span>3 </pre> <p>You probably won't end up using Depth too much. The data in a typical program has a fixed, known depth, so there's no point in asking BQN what it is. But it might be useful if you want to write a utility function that's flexible about its input. <code><span class='Number'>0</span><span class='Function'><≡</span><span class='Value'>a</span></code> is the idiomatic way to test whether <code><span class='Value'>a</span></code> is an array.</p> -<h2 id="composition">Composition</h2> +<h2 id="composition"><a class="header" href="#composition">Composition</a></h2> <p>We've discussed Atop (<code><span class='Modifier2'>∘</span></code>), but hopefully you've intuited that it's not the end of the story as far as compositions go. In fact BQN has <strong>three</strong> more modifiers that could reasonably be interpreted as varieties of composition.</p> -<h3 id="over">Over</h3> +<h3 id="over"><a class="header" href="#over">Over</a></h3> <table class='primitives'> <tr> <td><span class='Modifier2'>○</span></td> @@ -375,7 +375,7 @@ </g> </svg> -<h3 id="before-and-after">Before and After</h3> +<h3 id="before-and-after"><a class="header" href="#before-and-after">Before and After</a></h3> <p>Atop (<code><span class='Modifier2'>∘</span></code>) and Over (<code><span class='Modifier2'>○</span></code>) are both symmetric in some sense: with two arguments, <code><span class='Paren'>(</span><span class='Function'>F</span><span class='Modifier2'>∘</span><span class='Function'>G</span><span class='Paren'>)</span><span class='Modifier'>˜</span></code> is <code><span class='Function'>F</span><span class='Modifier2'>∘</span><span class='Paren'>(</span><span class='Function'>G</span><span class='Modifier'>˜</span><span class='Paren'>)</span></code>, and <code><span class='Paren'>(</span><span class='Function'>F</span><span class='Modifier2'>○</span><span class='Function'>G</span><span class='Paren'>)</span><span class='Modifier'>˜</span></code> is <code><span class='Paren'>(</span><span class='Function'>F</span><span class='Modifier'>˜</span><span class='Paren'>)</span><span class='Modifier2'>○</span><span class='Function'>G</span></code>. Put another way, reversing the order of arguments to Atop or Over as a whole is the same as reversing the order of every two-argument function inside—<code><span class='Function'>G</span></code> for <code><span class='Function'>F</span><span class='Modifier2'>∘</span><span class='Function'>G</span></code> and <code><span class='Function'>F</span></code> for <code><span class='Function'>F</span><span class='Modifier2'>○</span><span class='Function'>G</span></code>. If it's not obvious why this is the case, work it out for yourself by walking through how these functions would apply to their arguments! This causes their diagrams to be symmetric as well. Swap (<code><span class='Modifier'>˜</span></code>) also has a symmetric diagram, and it's very easy to show that it's symmetric: take a look at <code><span class='Paren'>(</span><span class='Function'>F</span><span class='Modifier'>˜</span><span class='Paren'>)</span><span class='Modifier'>˜</span></code> and <code><span class='Paren'>(</span><span class='Function'>F</span><span class='Modifier'>˜</span><span class='Paren'>)</span><span class='Modifier'>˜</span></code>. In both cases I started with <code><span class='Function'>F</span><span class='Modifier'>˜</span></code>, but in one case I applied <code><span class='Modifier'>˜</span></code> to the entire function and in the other I applied it on the inside, to <code><span class='Function'>F</span></code> only. And I won't tell you which is which.</p> <table class='primitives'> <tr> @@ -497,7 +497,7 @@ ⟨ 0 0.109375 0.1875 0.234375 0.25 0.234375 0.1875 0.109375 ⟩ </pre> <p>Our list of arguments stops before reaching 1, because <code><span class='Function'>↕</span><span class='Number'>8</span></code> doesn't include <code><span class='Number'>8</span></code>. If we wanted a list from 0 to 1 <em>inclusive</em>, we'd need to divide by <code><span class='Number'>7</span></code> (that is, <code><span class='Number'>8</span><span class='Function'>-</span><span class='Number'>1</span></code>) instead of <code><span class='Number'>8</span></code>. We can do this as well! But first we need to understand some other ways to apply Before and After.</p> -<h4 id="bind">Bind</h4> +<h4 id="bind"><a class="header" href="#bind">Bind</a></h4> <p>We showed in the first tutorial that a modifier's operand doesn't have to be a function, but can also be a data value. That hasn't come up yet, except for a cryptic use of "Bind" (<code><span class='Modifier2'>⊸</span></code>?) in the function <code><span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>8</span><span class='Paren'>)</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Modifier'>¨</span></code> from the last tutorial. How does that work? Some kind of secret identity for Before and After?</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MeKKuCsgNQor4p+cMSA1">↗️</a><pre> <span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>+</span> <span class='Number'>5</span> 6 @@ -550,7 +550,7 @@ <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKGlcO3LeKfnDEpIDg=">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>↕÷-</span><span class='Modifier2'>⟜</span><span class='Number'>1</span><span class='Paren'>)</span> <span class='Number'>8</span> ⟨ 0 0.14285714285714285 0.2857142857142857 0.42857142857142855 0.5714285714285714 0.7142857142857143 0.8571428571428571 1 ⟩ </pre> -<h2 id="base-decoding-continued">Base decoding continued</h2> +<h2 id="base-decoding-continued"><a class="header" href="#base-decoding-continued">Base decoding continued</a></h2> <p>We're speeding up a bit now, so in the examples below it might take some time for you to break down what I did and why. Remember that you can open any expression in the REPL in order to change parts of it or view the syntax. And don't get discouraged just because of how long it takes to understand a line of code! First, you'll surely get faster in fitting the pieces together. Second, a line of BQN often has more code in it than a line in other languages, because primitives have such short names. Think about how much <em>functionality</em> you can read and understand rather than how few <em>lines</em> you get through.</p> <p>In the last tutorial I <a href="list.html#example-base-decoding">went over</a> a way to decode a list of strings containing binary codes for ASCII characters:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=QCArICvCtMKoICjijL0y4ouG4oaVOCniirjDl8KoICcwJyAty5wgIjAxMDAwMDEwIuKAvyIwMTAxMDAwMSLigL8iMDEwMDExMTAi">↗️</a><pre> <span class='String'>@</span> <span class='Function'>+</span> <span class='Function'>+</span><span class='Modifier'>´¨</span> <span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>8</span><span class='Paren'>)</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Modifier'>¨</span> <span class='String'>'0'</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>"01000010"</span><span class='Ligature'>‿</span><span class='String'>"01010001"</span><span class='Ligature'>‿</span><span class='String'>"01001110"</span> @@ -597,7 +597,7 @@ <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KEArIMK3K+KfnCgy4oq4w5cpwrTiiJjijL3CqCAt4p+cJzAnKSAiMDEwMDAwMTAi4oC/IjAxMDEwMDAxIuKAvyIwMTAwMTExMCI=">↗️</a><pre> <span class='Paren'>(</span><span class='String'>@</span><span class='Function'>+</span> <span class='Nothing'>·</span><span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Paren'>)</span><span class='Modifier'>´</span><span class='Modifier2'>∘</span><span class='Function'>⌽</span><span class='Modifier'>¨</span> <span class='Function'>-</span><span class='Modifier2'>⟜</span><span class='String'>'0'</span><span class='Paren'>)</span> <span class='String'>"01000010"</span><span class='Ligature'>‿</span><span class='String'>"01010001"</span><span class='Ligature'>‿</span><span class='String'>"01001110"</span> "BQN" </pre> -<h2 id="summary">Summary</h2> +<h2 id="summary"><a class="header" href="#summary">Summary</a></h2> <p>BQN has a full complement of comparison functions, which are pervasive (work on atoms only) like arithmetic functions. The non-pervasive functions Match (<code><span class='Function'>≡</span></code>) and Not Match (<code><span class='Function'>≢</span></code>) compare entire arrays. Comparison functions return <code><span class='Number'>1</span></code> if the comparison holds and <code><span class='Number'>0</span></code> if it doesn't; these two numbers make up the "booleans".</p> <table> <thead> diff --git a/docs/tutorial/expression.html b/docs/tutorial/expression.html index 840ec4fd..89a43380 100644 --- a/docs/tutorial/expression.html +++ b/docs/tutorial/expression.html @@ -4,8 +4,8 @@ <title>Tutorial: BQN expressions</title> </head> <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">tutorial</a></div> -<h1 id="tutorial-bqn-expressions">Tutorial: BQN expressions</h1> -<h2 id="arithmetic">Arithmetic</h2> +<h1 id="tutorial-bqn-expressions"><a class="header" href="#tutorial-bqn-expressions">Tutorial: BQN expressions</a></h1> +<h2 id="arithmetic"><a class="header" href="#arithmetic">Arithmetic</a></h2> <p>All right, let's get started! Since you can run BQN online from the <a href="https://mlochbaum.github.io/BQN/try.html">REPL</a> there aren't any real technical preliminaries, but if you'd like to look at non-web-based options head over to <a href="../running.html">running.md</a>.</p> <p>In the code blocks shown here, input is highlighted and indented, while output is not colored or indented. To experiment with the code, you can click the <code><span class='Value'>↗️</span></code> arrow in the top right corner to open it in the REPL.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiArIDMKNi0gICA1Ci0gMS41">↗️</a><pre> <span class='Number'>2</span> <span class='Function'>+</span> <span class='Number'>3</span> @@ -102,7 +102,7 @@ </span><span class='Function'>√</span> <span class='Function'>⋆</span> <span class='Comment'># \ shift </span></pre> <p>In case you're wondering, Logarithm—the other inverse of Power—is written <code><span class='Function'>⋆</span><span class='Modifier'>⁼</span></code>. We'll see how that works when we introduce <code><span class='Modifier'>⁼</span></code> in the section on 1-modifiers.</p> -<h2 id="compound-expressions">Compound expressions</h2> +<h2 id="compound-expressions"><a class="header" href="#compound-expressions">Compound expressions</a></h2> <p>It's sometimes useful to write programs with more than one function in them. Here is where BQN and any sort of normality part ways.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MsOXMyAtIDUKKDLDlzMpIC0gNQ==">↗️</a><pre> <span class='Number'>2</span><span class='Function'>×</span><span class='Number'>3</span> <span class='Function'>-</span> <span class='Number'>5</span> ¯4 @@ -157,7 +157,7 @@ <p>The online REPL includes a tool to create diagrams like the one shown above. To enable it, click the "explain" button. Then a diagram of your source code will be shown above the result each time you run an expression.</p> <p>The following rule might help you to internalize this system in addition to identifying when parentheses are needed: an expression never needs to end with a parenthesis, or have two closing parentheses in a row. If it does, at least one set of parentheses can be removed without changing the meaning.</p> -<h2 id="one-or-two-arguments">One or two arguments?</h2> +<h2 id="one-or-two-arguments"><a class="header" href="#one-or-two-arguments">One or two arguments?</a></h2> <p>What about functions without a left argument? Let's find an equation with lots of square roots in it… <a href="https://en.wikipedia.org/wiki/Nested_radical#Denesting">looks good</a>.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oiaIDMgKyAyIMOXIOKImjIKMSArIOKImjI=">↗️</a><pre> <span class='Function'>√</span> <span class='Number'>3</span> <span class='Function'>+</span> <span class='Number'>2</span> <span class='Function'>×</span> <span class='Function'>√</span><span class='Number'>2</span> 2.414213562373095 @@ -227,7 +227,7 @@ <li>A set of parentheses has the same role as whatever's inside it.</li> </ul> <p>Perhaps more than you thought! To really get roles, it's important to understand that a role is properly a property of an expression, and not its value. In language implementation terms, roles are used only to parse expressions, giving a syntax tree, but don't dictate what values are possible when the tree is evaluated. So it's possible to have a function with a number role or a number with a function role. The reason this doesn't happen with the numeric literals and primitives we've introduced is that these tokens have a constant value. <code><span class='Function'>×</span></code> or <code><span class='Number'>∞</span></code> have the same value in any possible program, and so it makes sense that their types and roles should correspond. When we introduce identifiers, we'll see this correspondence break down—and why that's good!</p> -<h2 id="character-arithmetic">Character arithmetic</h2> +<h2 id="character-arithmetic"><a class="header" href="#character-arithmetic">Character arithmetic</a></h2> <p>Gosh, that's a lot of arithmetic up there. Maybe adding characters will mix things up a bit? Hang on, you can't add characters, only subtract them… let's back up.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=J2Mn">↗️</a><pre> <span class='String'>'c'</span> 'c' @@ -279,7 +279,7 @@ <p>It's a convenient way to write non-printing characters without having to include them in your source code: for example <code><span class='String'>@</span><span class='Function'>+</span><span class='Number'>10</span></code> is the newline character.</p> <p>Addition and subtraction with affine characters have all the same algebraic properties that they do with numbers. One way to see this is to think of values as a combination of "characterness" (0 for numbers and 1 for characters) and either numeric value or code point. Addition and subtraction are done element-wise on these pairs of numbers, and are allowed if the result is a valid value, that is, its characterness is 0 or 1 and its value is a valid code point if the characterness is 1. However, because the space of values is no longer closed under addition and subtraction, certain rearrangements of valid computations might not work, if one of the values produced in the middle isn't legal.</p> -<h2 id="modifiers">Modifiers</h2> +<h2 id="modifiers"><a class="header" href="#modifiers">Modifiers</a></h2> <p>Functions are nice and all, but to really bring us into the space age BQN has a second level of function called <em>modifiers</em> (the space age in this case is when operators were introduced to APL in the early 60s—hey, did you know the <a href="https://aplwiki.com/wiki/APL_conference#1970">second APL conference</a> was held at Goddard Space Flight Center?). While functions apply to subjects, modifiers can apply to functions <em>or</em> subjects, and return functions. For example, the 1-modifier <code><span class='Modifier'>˜</span></code> modifies one function by swapping the arguments before calling it (Swap), or copying the right argument to the left if there's only one (Self).</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiAty5wgJ2QnICAjIFN1YnRyYWN0IGZyb20KK8ucIDMgICAgICAjIEFkZCB0byBpdHNlbGY=">↗️</a><pre> <span class='Number'>2</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>'d'</span> <span class='Comment'># Subtract from </span>'b' @@ -332,7 +332,7 @@ </pre> <p>Well, I guess it's not pedagogically useless, as it does demonstrate that a modifier can be applied to subjects as well as functions. Even though <code><span class='Number'>3</span></code> is a subject, <code><span class='Number'>3</span><span class='Modifier'>˙</span></code> is a function, and can be applied to and ignore the two arguments <code><span class='Number'>2</span></code> and <code><span class='Number'>4</span></code>.</p> <p>With three examples you may have noticed that 1-modifiers tend to cluster at the top of the screen. In fact, every primitive 1-modifer is a superscript character: we've covered <code><span class='Modifier'>˜⁼˙</span></code>, and the remaining array-based modifiers <code><span class='Modifier'>˘¨⌜´˝`</span></code> will show up later.</p> -<h2 id="2-modifiers">2-modifiers</h2> +<h2 id="2-modifiers"><a class="header" href="#2-modifiers">2-modifiers</a></h2> <p>Made it to the last role, the 2-modifier (if you think something's been skipped, you're free to call subjects 0-modifiers. They don't modify anything. Just not when other people can hear you). To introduce them we'll use Atop <code><span class='Modifier2'>∘</span></code>, which works a lot like mathematical composition, except that it's extended to use one or two arguments. These arguments are passed to the function on the right, and the result is passed to the function on the left. So the function on the left is only ever called with one argument.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MyDDl8uc4oiYKyA0ICAjIFNxdWFyZSBvZiAzIHBsdXMgNAot4oiYKMOXy5wpIDUgICMgTmVnYXRpdmUgc3F1YXJlIG9mIDU=">↗️</a><pre> <span class='Number'>3</span> <span class='Function'>×</span><span class='Modifier'>˜</span><span class='Modifier2'>∘</span><span class='Function'>+</span> <span class='Number'>4</span> <span class='Comment'># Square of 3 plus 4 </span>49 @@ -384,7 +384,7 @@ <p>This ordering is more consistent with the rule that a 1-modifier's operand should go to its left. If we tried going from right to left we'd end up with <code><span class='Function'>×</span><span class='Paren'>(</span><span class='Modifier'>˜</span><span class='Modifier2'>∘</span><span class='Function'>+</span><span class='Paren'>)</span></code>, which uses <code><span class='Modifier'>˜</span></code> as an operand to <code><span class='Modifier2'>∘</span></code>. But a modifier can't be used as an operand. To make it work we'd have to give 1-modifiers a higher precedence than 2-modifiers.</p> <p>In fact, the rules for modifiers are exactly the same as those for functions, but reversed. So why is there a distinction between 1- and 2-modifiers, when for functions we can look to the left to see whether there is a left argument? The reason is that it's natural to follow a 1-modifier by a subject or function that isn't supposed to be its operand. Using an example from the last section, <code><span class='Function'>+</span><span class='Modifier'>˜</span> <span class='Number'>3</span></code> has a subject to the right of the 1-modifier <code><span class='Modifier'>˜</span></code>. Even worse, <code><span class='Function'>+</span><span class='Modifier'>˜</span> <span class='Function'>÷</span> <span class='Number'>3</span></code> looks just like <code><span class='Function'>+</span><span class='Modifier2'>∘</span> <span class='Function'>÷</span> <span class='Number'>3</span></code>, but it's two functions <code><span class='Function'>+</span><span class='Modifier'>˜</span></code> and <code><span class='Function'>÷</span></code> applied to <code><span class='Number'>3</span></code> while the version with Atop is a single function <code><span class='Function'>+</span><span class='Modifier2'>∘</span><span class='Function'>÷</span></code> applied to <code><span class='Number'>3</span></code>. So the two-layer system of functions and modifiers forces modifiers to have a fixed number of operands even though every function (including those derived by applying modifiers) can be called with one or two arguments.</p> <p>Remember that 1-modifiers are all superscripts? The characters for 2-modifiers use a different rule: each contains an <em>unbroken</em> circle (that is, lines might touch it but not go through it). The 2-modifiers in BQN are the combinators <code><span class='Modifier2'>∘○⊸⟜⊘</span></code>, the sort-of-combinators <code><span class='Modifier2'>⌾◶⍟</span></code>, and the not-at-all-combinators <code><span class='Modifier2'>⎉⚇⎊</span></code>. And the functions that make that unbroken circle rule necessary are written <code><span class='Function'>⌽⍉</span></code>. Since every primitive is a function, 1-modifier, or 2-modifier, you can always tell what type (and role) it has: a superscript is a 1-modifier, an unbroken circle makes it a 2-modifier, and otherwise it's a function.</p> -<h2 id="summary">Summary</h2> +<h2 id="summary"><a class="header" href="#summary">Summary</a></h2> <p>The objects we've seen so far are:</p> <table> <thead> diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html index 396aabe4..85a2431f 100644 --- a/docs/tutorial/index.html +++ b/docs/tutorial/index.html @@ -4,7 +4,7 @@ <title>BQN tutorials</title> </head> <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a></div> -<h1 id="bqn-tutorials">BQN tutorials</h1> +<h1 id="bqn-tutorials"><a class="header" href="#bqn-tutorials">BQN tutorials</a></h1> <p>BQN tutorials explain how to approach and use the language as a newcomer (or they try; please get in touch if you find that they skip ahead!). Tutorials are meant to explain key ideas and may ignore details that would be included in the <a href="../doc/index.html">documentation</a>; also unlike the documentation they're meant to be read in order, as each tutorial will build on ideas from the previous ones.</p> <p>Tutorials assume (pretty presumptively, really. Disgusting.) that you are already motivated to learn BQN and use simple rather than flashy examples. Documents to induce motivation beyond the README are not yet available. Do feel free to skim or jump around if you find you are reading a lot of things that are already obvious.</p> <p>The tutorials available so far:</p> diff --git a/docs/tutorial/list.html b/docs/tutorial/list.html index a44c30b4..0e032b98 100644 --- a/docs/tutorial/list.html +++ b/docs/tutorial/list.html @@ -4,7 +4,7 @@ <title>BQN Tutorial: Working with lists</title> </head> <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">tutorial</a></div> -<h1 id="tutorial-working-with-lists">Tutorial: Working with lists</h1> +<h1 id="tutorial-working-with-lists"><a class="header" href="#tutorial-working-with-lists">Tutorial: Working with lists</a></h1> <p>Enough with all these preliminaries like learning how to read basic expressions. Let's get into what makes BQN special.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMSwgMiwgM+KfqQ==">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>2</span><span class='Separator'>,</span> <span class='Number'>3</span><span class='Bracket'>⟩</span> ⟨ 1 2 3 ⟩ @@ -14,7 +14,7 @@ ⟨ 2 3 4 ⟩ </pre> <p>There we go. Now in BQN arrays are not just lists, which are a 1-dimensional data structure, but can have any number of dimensions. In this tutorial we're going to discuss lists only, leaving the 5-dimensional stuff for later. So we're really only seeing the power of <a href="https://aplwiki.com/wiki/K">K</a>, an APL-family language that only uses lists (and dictionaries, which BQN doesn't have). K was powerful enough for Arthur Whitney to found <a href="https://en.wikipedia.org/wiki/Kx_Systems">two</a> <a href="https://shakti.com/">companies</a> and make millions and millions of dollars, and BQN's compiler also runs almost entirely on lists, so this is probably enough power for one webpage.</p> -<h2 id="list-notation">List notation</h2> +<h2 id="list-notation"><a class="header" href="#list-notation">List notation</a></h2> <p>There are three kinds of list notation in BQN. Each of them has a subject role overall, even if expressions used inside it might have other roles. First, a <em>string</em> is a list of characters, and is written by placing those characters in double quotes.</p> <pre><span class='String'>"Text!"</span> </pre> @@ -86,7 +86,7 @@ <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Paren'>(</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Paren'>)</span> ⟨ 0 ⟨ 1 2 ⟩ ⟩ </pre> -<h2 id="bqn-types">BQN types</h2> +<h2 id="bqn-types"><a class="header" href="#bqn-types">BQN types</a></h2> <p>Now that all six BQN types have been introduced, let's make a table:</p> <table> <thead> @@ -111,7 +111,7 @@ </tbody> </table> <p>Lists are just one-dimensional arrays. Types are divided into <em>data types</em>, which tend to have a subject role, and <em>operation types</em>, which tend to have a role matching their type. Also, any value that's not an array, such as everything we used in the last tutorial, is called an <em>atom</em>.</p> -<h2 id="arithmetic-on-lists">Arithmetic on lists</h2> +<h2 id="arithmetic-on-lists"><a class="header" href="#arithmetic-on-lists">Arithmetic on lists</a></h2> <p>Arithmetic functions automatically apply to each element of a list argument. If both arguments are lists, they have to have the same length, and they're matched up one element at a time.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=w7cg4p+oMiwzLDTin6kKCiJBUEwiICsgMQoKIjMxNDE1IiAtICcwJwoKNOKAvzPigL8y4oC/MSDii4YgMeKAvzLigL8z4oC/NA==">↗️</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='Bracket'>⟩</span> ⟨ 0.5 0.3333333333333333 0.25 ⟩ @@ -132,7 +132,7 @@ <span class='Bracket'>⟨</span> <span class='Number'>10</span><span class='Separator'>,</span> <span class='Number'>20</span><span class='Ligature'>‿</span><span class='Number'>30</span> <span class='Bracket'>⟩</span> <span class='Function'>+</span> <span class='Bracket'>⟨</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Separator'>,</span> <span class='Number'>3</span> <span class='Bracket'>⟩</span> ⟨ ⟨ 11 12 ⟩ ⟨ 23 33 ⟩ ⟩ </pre> -<h2 id="some-list-functions">Some list functions</h2> +<h2 id="some-list-functions"><a class="header" href="#some-list-functions">Some list functions</a></h2> <table class='primitives'> <tr> <td><span class='Function'>≍</span></td> @@ -183,7 +183,7 @@ <span class='Number'>¯1</span> <span class='Function'>⌽</span> <span class='String'>"bcdea"</span> "abcde" </pre> -<h3 id="and-modifiers">…and modifiers</h3> +<h3 id="and-modifiers"><a class="header" href="#and-modifiers">…and modifiers</a></h3> <table class='primitives'> <tr> <td><span class='Modifier'>¨</span></td> @@ -235,7 +235,7 @@ <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oi+IOKfqCAiY29uIiwgImNhdCIsICJlbmF0IiwgImUiIOKfqQ==">↗️</a><pre> <span class='Function'>∾</span> <span class='Bracket'>⟨</span> <span class='String'>"con"</span><span class='Separator'>,</span> <span class='String'>"cat"</span><span class='Separator'>,</span> <span class='String'>"enat"</span><span class='Separator'>,</span> <span class='String'>"e"</span> <span class='Bracket'>⟩</span> "concatenate" </pre> -<h2 id="example-base-decoding">Example: base decoding</h2> +<h2 id="example-base-decoding"><a class="header" href="#example-base-decoding">Example: base decoding</a></h2> <p>Some people like to imagine that robots or other techno-beings speak entirely in binary-encoded ASCII, like for instance "01001110 01100101 01110010 01100100 00100001". This is dumb for a lot of reasons, and the encoded text probably just says something inane, but you're a slave to curiosity and can't ignore it. Are one and a half tutorials of BQN enough to clear your conscience?</p> <table class='primitives'> <tr> @@ -359,7 +359,7 @@ ERROR <span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Function'>+</span><span class='Modifier'>˜</span><span class='Paren'>)</span><span class='Modifier'>´</span> <span class='Function'>⌽</span> <span class='String'>"1001"</span><span class='Function'>-</span><span class='String'>'0'</span> 9 </pre> -<h2 id="summary">Summary</h2> +<h2 id="summary"><a class="header" href="#summary">Summary</a></h2> <p>There are three types of syntax that create lists: the <code><span class='String'>"string literal"</span></code> for lists of characters and either enclosing angle brackets <code><span class='Bracket'>⟨⟩</span></code> with <code><span class='Separator'>,</span></code> or <code><span class='Separator'>⋄</span></code> or newline characters or connecting ligatures <code><span class='Ligature'>‿</span></code> for lists with arbitrary elements. The ligature has a higher precedence than functions or modifiers, so we should add it to our precedence table:</p> <table> <thead> diff --git a/docs/tutorial/variable.html b/docs/tutorial/variable.html index 33f1e48c..e8a1f06e 100644 --- a/docs/tutorial/variable.html +++ b/docs/tutorial/variable.html @@ -4,7 +4,7 @@ <title>BQN Tutorial: Variables</title> </head> <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">tutorial</a></div> -<h1 id="tutorial-variables">Tutorial: Variables</h1> +<h1 id="tutorial-variables"><a class="header" href="#tutorial-variables">Tutorial: Variables</a></h1> <p>To take a proud denizen of the eternal cosmos of values, held for a fleeting instant by the course of code, and bind it. Tie it down with a name, failing always to alter its inner nature but allowing context to reform its outer appearance. So labelled, perhaps through the progress of time it will know escape, or else find itself passed through one bond to another, ever tethered. It's a task to be approached only with respect.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=aGV5IOKGkCAiSGkgdGhlcmUiCgpoZXkg4oi+ICIsIFdvcmxkISI=">↗️</a><pre> <span class='Value'>hey</span> <span class='Gets'>←</span> <span class='String'>"Hi there"</span> @@ -12,7 +12,7 @@ "Hi there, World!" </pre> <p>Like that.</p> -<h2 id="defining-variables">Defining variables</h2> +<h2 id="defining-variables"><a class="header" href="#defining-variables">Defining variables</a></h2> <p>BQN uses the left-pointing arrow <code><span class='Gets'>←</span></code> to define variables, as shown above. Most of the time it's best to use it in a plain way, with just the name and its definition, but it's also possible to define multiple variables using list notation, or to define a variable as part of a larger expression that continues to the left (in terms of precedence, <code><span class='Gets'>←</span></code> behaves like a function, but it isn't one—it's a part of syntax).</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=cGnigL9l4oC/dGVuIOKGkCDin6ggz4AsIOKLhjEsIDEwIOKfqQoKdGVuIMOXIHBpCgp0aHJlZSDiiY0gdGVuIC0gdGhyZWUg4oaQIDM=">↗️</a><pre> <span class='Value'>pi</span><span class='Ligature'>‿</span><span class='Value'>e</span><span class='Ligature'>‿</span><span class='Value'>ten</span> <span class='Gets'>←</span> <span class='Bracket'>⟨</span> <span class='Number'>π</span><span class='Separator'>,</span> <span class='Function'>⋆</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>10</span> <span class='Bracket'>⟩</span> ⟨ 3.141592653589793 2.718281828459045 10 ⟩ @@ -40,7 +40,7 @@ ERROR </span>ERROR </pre> <p>It's an odd distinction to have when your program is just one long sequence of statements, because there's only ever one arrow you can use: it just changes annoyingly after you define the variable for the first time. With multiple scopes this isn't the case: if you start a new scope inside another, then you'll still be able to use variables from the outside scope. Then <code><span class='Gets'>↩</span></code> lets you change the value of one of these variables while <code><span class='Gets'>←</span></code> allows you to define your own. If you're coming from a typical curly-brace language, you'd say that <code><span class='Gets'>←</span></code> both declares and assigns a variable, while <code><span class='Gets'>↩</span></code> only assigns it.</p> -<h2 id="variable-roles">Variable roles</h2> +<h2 id="variable-roles"><a class="header" href="#variable-roles">Variable roles</a></h2> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=QlFOIOKGkCAiW21hbnkgcGFnZXMgb2Ygc3BlY2lmaWNhdGlvbl0i">↗️</a><pre> <span class='Function'>BQN</span> <span class='Gets'>←</span> <span class='String'>"[many pages of specification]"</span> ERROR </pre> @@ -104,7 +104,7 @@ ERROR <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MV8wMDBfMDAw">↗️</a><pre> <span class='Number'>1_000_000</span> 1000000 </pre> -<h2 id="function-assignment">Function assignment</h2> +<h2 id="function-assignment"><a class="header" href="#function-assignment">Function assignment</a></h2> <p>While you could build up a script by computing values and assigning them names, the main way to use assignment in tacit programming is to give names to functions, not data. For example, we might name the base-2 conversion function from our last tutorial:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=QmFzZTIg4oaQICvin5woMuKKuMOXKcK04oiY4oy9CgpCYXNlMiAx4oC/MOKAvzHigL8wCgpCYXNlMiAiMDEwMTAwMDEiLScwJwoKQCArIEJhc2UywqggJzAnIC3LnCAiMDEwMDAwMTAi4oC/IjAxMDEwMDAxIuKAvyIwMTAwMTExMCI=">↗️</a><pre> <span class='Function'>Base2</span> <span class='Gets'>←</span> <span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Paren'>)</span><span class='Modifier'>´</span><span class='Modifier2'>∘</span><span class='Function'>⌽</span> @@ -130,7 +130,7 @@ ERROR <span class='Function'>Base2</span> <span class='Number'>6</span> 16 </pre> -<h2 id="modifying-part-of-an-array">Modifying part of an array</h2> +<h2 id="modifying-part-of-an-array"><a class="header" href="#modifying-part-of-an-array">Modifying part of an array</a></h2> <p>You cannot modify part of an array. You can't modify an array: an array that differs a little bit from another array <em>is a different array</em>. And this isn't just a terminology choice: it has real effects on how BQN arrays behave and even which arrays are representable, as we'll discuss later.</p> <p>But say I have a list, and I want to subtract one from one of the elements. With the understanding that the resulting list is different from the first one, BQN allows this!</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=IkJRTiIgICAgICAgICAgICAjIEEgbGlzdCBvZiBjaGFyYWN0ZXJzCgot4p+cMeKMvigy4oq44oqRKSAiQlFOIiAgIyBXYWl0IHdoeSBkaWQgSSBkbyB0aGF0">↗️</a><pre> <span class='String'>"BQN"</span> <span class='Comment'># A list of characters @@ -252,7 +252,7 @@ ERROR "abcdEFgh" </pre> <p>(Here I've snuck in a train <code><span class='Number'>2</span> <span class='Function'>↑</span> <span class='Number'>4</span><span class='Modifier2'>⊸</span><span class='Function'>↓</span></code> to combine the two functions. As an exercise, you might try to write that function using combinators instead, and as an extra hard exercise you might then ponder why someone would want to add trains to a language).</p> -<h2 id="identity-functions">Identity functions</h2> +<h2 id="identity-functions"><a class="header" href="#identity-functions">Identity functions</a></h2> <table class='primitives'> <tr> <td><span class='Function'>⊣</span></td> @@ -282,7 +282,7 @@ ERROR "left" </pre> <p>They are not complicated functions: if you're confused it's because you don't understand why anyone would ever use them. Indeed, it's harder to see why these functions are useful than to see what they do. That is a fact.</p> -<h2 id="modified-assignment">Modified assignment</h2> +<h2 id="modified-assignment"><a class="header" href="#modified-assignment">Modified assignment</a></h2> <p>Let's revisit our question about modifying an array. As we said, the answer to "how do I modify part of an array?" is simply that you can't, and that the question doesn't make sense. But there's a seemingly similar question with a very different answer: "how do I modify part of a variable whose value is an array?" This is because unlike an array, a variable isn't defined by the value it has, but by the name used to refer to it (and the scope it resides in). Here's how we would modify the variable <code><span class='Value'>a</span></code>:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSDihpAgNCAgICAgICAgICAgICMgRmlyc3QgaXQncyBhIG51bWJlcgphCgphIOKGqSA04oC/NeKAvzYgICAgICAgICMgTm93IGl0J3MgYSBsaXN0IQph">↗️</a><pre> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Number'>4</span> <span class='Comment'># First it's a number </span> <span class='Value'>a</span> |