From 74da83ca988395593fbed6faec3733aa5625421d Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Thu, 22 Oct 2020 14:36:43 -0400 Subject: Add infoboxes to introduce glyphs in tutorials --- docs/tutorial/expression.html | 95 +++++++++++++++++++++++++++++++++++++++ docs/tutorial/list.html | 101 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 196 insertions(+) (limited to 'docs/tutorial') diff --git a/docs/tutorial/expression.html b/docs/tutorial/expression.html index 7669df1a..bb5fc9d6 100644 --- a/docs/tutorial/expression.html +++ b/docs/tutorial/expression.html @@ -15,6 +15,21 @@ - 1.5 ¯1.5 + + + + + + + + + + + + + +
+Add
-NegateSubtract
+

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.

↗️
    2 × π
@@ -24,6 +39,31 @@
     ÷ ∞
 0
+ + + + + + + + + + + + + + + + + + + + + + + +
×\=Multiply
÷\-ReciprocalDivide
π\pPi
∞\8Infinity
+

Okay, now BQN looks like normal (grade-school) mathematics, which is sort of like looking normal. Pi (π) represents that real famous number 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 e and is called Exponential.

↗️
    2 ⋆ 3
@@ -35,6 +75,21 @@
     ⋆ 2.3
 9.97418245481472
+ + + + + + + + + + + + + +
⋆\+ExponentialPower
√\_Square RootRoot
+

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
 1.4142135623731
@@ -208,6 +263,19 @@
     @ + 97
 'a'
+ + + + + + + + + + + +
'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.

Modifiers

@@ -224,6 +292,25 @@ 16

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.

+ + + + + + + + + + + + + + + + + +
˜\`SwapSelf
⁼\3Undo
˙\"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 to always work in the same way. Starting with a third way to square a number:

↗️
    √⁼ 4
 16
@@ -251,6 +338,14 @@
     -∘(ט) 5  # Negative square of 5
 ¯25
+ + + + + + +
∘\jAtop
+

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/docs/tutorial/list.html b/docs/tutorial/list.html
index 3a389d42..deae0f11 100644
--- a/docs/tutorial/list.html
+++ b/docs/tutorial/list.html
@@ -18,6 +18,34 @@
 
There are three kinds of list notation in BQN. Every one has a subject role, even though expressions used inside it might have other roles. First, a string is a list of characters, and is written by placing those characters in double quotes.

 
"Text!"
 

+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
"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:

 
⟨ π, ∘, "element" ⋄ ⟨'l',1,5,'t'⟩ ⟩
@@ -32,6 +60,19 @@
   "lines"
 ⟩
 

+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
#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,+,-⟩
 2‿+‿-
@@ -92,6 +133,27 @@
 ⟨ ⟨ 11 12 ⟩ ⟨ 23 33 ⟩ ⟩
 

 
Some list functions

+
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+
≍\.SoloCouple
∾\,Join To
⌽\qReverseRotate

+
 
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.

 ↗️
    ≍ 4
@@ -122,6 +184,25 @@
 "abcde"
 

 
…and modifiers

+
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+
¨\1Each
´\5Fold
∾\,JoinJoin 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"
 ⟨ "dcba" "FEDCBA" "10" ⟩
@@ -156,6 +237,21 @@
 

 
Example: base decoding

 
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?

+
+  
+    
+    
+    
+    
+  
+  
+    
+    
+    
+    
+  
+
↕\dRange
⊸\hBind?

+
 
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
 ⟨ 0 1 2 3 4 5 6 7 ⟩
@@ -275,6 +371,11 @@ ERROR

 Rotate
 
 
+↕
+
+Range
+
+
 ¨
 Each
 Each
-- 
cgit v1.2.3