diff options
Diffstat (limited to 'tutorial')
| -rw-r--r-- | tutorial/expression.md | 23 | ||||
| -rw-r--r-- | tutorial/list.md | 16 |
2 files changed, 39 insertions, 0 deletions
diff --git a/tutorial/expression.md b/tutorial/expression.md index 09dc757a..fcc158d1 100644 --- a/tutorial/expression.md +++ b/tutorial/expression.md @@ -12,6 +12,9 @@ In the code blocks shown here, input is highlighted and indented, while output i 6- 5 - 1.5 +<!--SVG prim.bqn +Primitives ⟨"+%%%Add", "-%%Negate%Subtract"⟩ +--> Shown above are a few arithmetic operations. BQN manages to pass as a normal programming language for three lines so far. That's a big accomplishment for BQN! Earth's a confusing place! The number of spaces between *primitive functions* like `+` and `-` and their *arguments* doesn't matter: you can use as much or as little as you like. No spaces inside numbers, of course. @@ -20,6 +23,14 @@ The number of spaces between *primitive functions* like `+` and `-` and their *a 9 ÷ 2 ÷ ∞ +<!--SVG +Primitives ⟨ + "×%=%%Multiply" + "÷%-%Reciprocal%Divide" + "π%p%Pi" + "∞%8%Infinity" +⟩ +--> Okay, now BQN looks like normal (grade-school) mathematics, which is sort of like looking normal. Pi (`π`) represents [that real famous number](https://en.wikipedia.org/wiki/Pi) and Infinity (`∞`) is also part of the number system (the BQN spec allows an implementation to choose its number system, and all existing implementations use double-precision floats, like Javascript or Lua). In analogy with the one-argument form of Minus (`-`) giving the negation of a number, Divide (`÷`) with only one argument gives its reciprocal. A number can be raised to the power of another with Power, written `⋆`. That's a star rather than an asterisk; BQN doesn't use the asterisk symbol. If it's called without a left argument, then `⋆` uses a base of [Euler's number](https://en.wikipedia.org/wiki/E_(mathematical_constant)) *e* and is called Exponential. @@ -29,6 +40,9 @@ A number can be raised to the power of another with Power, written `⋆`. That's ⋆ 1 # There's no constant for e but you can get it this way ⋆ 2.3 +<!--SVG +Primitives ⟨"⋆%+%Exponential%Power", "√%_%Square Root%Root"⟩ +--> You could use Power to take square roots and *n*-th roots, but BQN also provides the primitive `√` for this purpose. If no left argument is provided, then it is the Square Root function; with a left argument it is called Root and raises the right argument to the power of one divided by the left argument. √ 2 @@ -124,6 +138,9 @@ The one thing affine characters won't let you do is find some special "starting '*' - @ @ + 97 +<!--SVG +Primitives ⟨"'%%Character", "@%%Null character"⟩ +--> It's a convenient way to write non-printing characters without having to include them in your source code: for example `@+10` is the newline character. 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 be valid, if one of the values produced in the middle isn't legal. @@ -142,6 +159,9 @@ This gives us two nice ways to square a value: What's wrong with `4⋆2`? Depends on the context. Because of the way evaluation flows from right to left, it's usually best if the right argument to a function is the one that's being manipulated directly while the left argument is sort of a "control value" that describes how to manipulate it. That way several manipulations can be done in a row without any parentheses required. `⋆` can go either way, but if "squaring" is the operation being done then the *left* argument is one being squared, so it's the active value. The Swap modifier allows us to put it on the right instead. +<!--SVG +Primitives ⟨"˜%`%Swap%Self", "⁼%3%Undo", "˙%""%Constant"⟩ +--> Another 1-modifier is Undo (`⁼`). BQN has just enough computer algebra facilities to look like a tool for Neanderthals next to a real computer algebra system, and among them is the ability to invert some primitives. In general you can't be sure when Undo will work (it might even be undecidable), but the examples I'll give here are guaranteed by [the spec](../spec/inferred.md#undo) to always work in the same way. Starting with a *third* way to square a number: √⁼ 4 @@ -168,6 +188,9 @@ Made it to the last role, the 2-modifier (if you think something's been skipped, 3 ט∘+ 4 # Square of 3 plus 4 -∘(ט) 5 # Negative square of 5 +<!--SVG +Primitives ⟨"∘%j%Atop"⟩ +--> It's past time we covered how the syntax for modifiers works. Remember how I told you you hated learning the order of operations? No? Good. Modifiers bind more tightly than functions, so they are called on their operands before their operands can be used. As the parentheses above suggest, modifiers also associate from left to right, the opposite order as functions. For example, the first expression above is evaluated in the order shown below. First we construct the square function `ט`, then compose it with `+`, and finally apply the result to some arguments. = ט diff --git a/tutorial/list.md b/tutorial/list.md index 015c2326..0a99ce42 100644 --- a/tutorial/list.md +++ b/tutorial/list.md @@ -18,6 +18,9 @@ There are three kinds of list notation in BQN. Every one has a subject role, eve "Text!" +<!--SVG prim.bqn +Primitives ⟨"""%%String", "⟨%(%Start list", "⟩%)%End list", "⋄%;%Separator", ",%%Separator"⟩ +--> Only one character needs to be escaped to place it in a string: the double quote, which is escaped by writing it twice. Any other character, including a newline, can be placed directly in a string. Second, *list notation* uses angle brackets `⟨⟩`. The *elements* in the list are kept apart with one of the three *separator* characters: `,`, `⋄`, and newline. Anything can be used as an element, even a function, or a modifier like `∘`. Here's a list containing a number, a 2-modifier, a string, and a non-string list: @@ -35,6 +38,9 @@ The two characters `,` and `⋄` are completely interchangeable, and newline is "lines" ⟩ +<!--SVG +Primitives ⟨"#%%Comment", "‿% %Strand"⟩ +--> Finally, *strand notation* is a shortcut for simple lists like a few numbers. It's written with the *ligature* `‿`, which has a higher precedence than either functions or operators. A sequence of values joined with ligatures becomes a list, so that for example the following two expressions are equivalent: ⟨2,+,-⟩ @@ -80,6 +86,9 @@ This list application works recursively, so that lists of lists (and so on) are ## Some list functions +<!--SVG +Primitives ⟨"≍%.%Solo%Couple", "∾%,%%Join To", "⌽%q%Reverse%Rotate"⟩ +--> Let's introduce a few primitives to work with lists. Make one or two atom arguments into a list with `≍`, pronounced Solo in the one-argument case and Couple in the two-argument case. This might not seem to merit a symbol but there's more to come. Don't call it on lists and ponder the results, igniting a hunger for ever more dimensions. @@ -109,6 +118,9 @@ With a left argument `⌽` means Rotate instead, and shifts values over by the s ### …and modifiers +<!--SVG +Primitives ⟨"¨%1%Each", "´%5%Fold", "∾%,%Join%Join To"⟩ +--> The 1-modifier Each (`¨`) applies its operand to every element of a list argument: it's the same as `map` in a functional programming language. With two list arguments (which have to have the same length), Each pairs the corresponding elements from each, a bit like a `zip` function. If one argument is a list and one's an atom, the atom is reused every time instead. ⌽¨ "abcd"‿"ABCDEF"‿"01" @@ -143,6 +155,9 @@ But you shouldn't! Just `∾` will do the job for you—with no left argument it 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? +<!--SVG +Primitives ⟨"↕%d%Range%", "⊸%h%Bind?%"⟩ +--> Almost. It's really close. There are just two things missing, so I'll cover those and can we agree one and three-quarters is pretty good? First is Range (`↕`), which is called on a number to give all the natural numbers less than it: ↕ 8 @@ -220,6 +235,7 @@ Glyph | 1 arg | 2 args `∾` | [Join](../doc/join.md) | Join To `≍` | [Solo](../doc/couple.md) | [Couple](../doc/couple.md) `⌽` | Reverse | Rotate +`↕` | | Range `¨` | Each | Each `´` | Fold |