From c208d37754ae81d9e67c80affa58c5ca8da95ee5 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sun, 30 Jan 2022 21:41:33 -0500 Subject: Add partial documentation page on tacit programming (fixes #36) --- docs/doc/glossary.html | 2 +- docs/doc/identity.html | 2 +- docs/doc/index.html | 1 + docs/doc/tacit.html | 213 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 216 insertions(+), 2 deletions(-) create mode 100644 docs/doc/tacit.html (limited to 'docs/doc') diff --git a/docs/doc/glossary.html b/docs/doc/glossary.html index 75048532..36482766 100644 --- a/docs/doc/glossary.html +++ b/docs/doc/glossary.html @@ -142,5 +142,5 @@
  • Header: A preface to a body in a block function or modifier indicating possible inputs, which is followed by a colon :.
  • Label: A header consisting of a single name.
  • Body: One sequence of statements in a block. Bodies, possibly preceded by headers, are separated by semicolons ;.
    • -
  • Tacit: Code that defines functions or modifiers without using blocks.
    • +
  • Tacit: Code that defines functions without using blocks.
    • diff --git a/docs/doc/identity.html b/docs/doc/identity.html index 3f4f624f..140b79b7 100644 --- a/docs/doc/identity.html +++ b/docs/doc/identity.html @@ -61,7 +61,7 @@

    Here ⊒ ends up being used as π•Ž. A similar case might be a function or program with a caller-specified processing step. For example, a function to write some kind of file, with a parameter function to encrypt data before writing. To use no encryption, you'd pass a parameter ⊒. Or it might happen that you write a Choose (β—Ά) expression where one of the cases should do nothing ⊒, or return the left argument ⊣.

    In tacit functions

    -

    In a tacit context, ⊣ is roughly equivalent to 𝕨 and ⊒ to 𝕩. In some (not too common) cases, it's even possible to translate a block function to tacit code directly by replacing the variables in this way.

    +

    In a tacit context, ⊣ is roughly equivalent to 𝕨 and ⊒ to 𝕩. In some (not too common) cases, it's even possible to translate a block function to tacit code directly by replacing the variables in this way.

    ↗️
        3 {𝕩-𝕨÷1+𝕩} 5
 4.5
     3 (⊒-⊣÷1+⊒) 5
diff --git a/docs/doc/index.html b/docs/doc/index.html
index 98587366..b4110034 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -30,6 +30,7 @@
 
  • Array indices
    • 
 
  • Fill elements
    • 
 
  • The leading axis model
    • 
+
  • Tacit programming
    • 
 
  • Function trains
    • 
 
  • Blocks (including function and modifier definition)
    • 
 
  • Lexical scoping
    • 
diff --git a/docs/doc/tacit.html b/docs/doc/tacit.html
new file mode 100644
index 00000000..b65bac49
--- /dev/null
+++ b/docs/doc/tacit.html
@@ -0,0 +1,213 @@
+
+  
+  
+  BQN: Tacit (point-free) programming
+
+
    (github) / BQN / doc
    
+
    Tacit (point-free) programming
    
+
    Tacit programming (APL Wiki) is a general term used to refer to ways to define functions that don't refer to arguments directly (say, with identifiers). Instead, tacit programs are built up by combining smaller functions together; we'll discuss the ways BQN offers to combine functions on this page. Since primitive functions like those returning the left (⊣) and right (⊒) arguments, and selection functions (βŠβŠ‘), are available as building blocks, tacit programming doesn't keep the programmer from pinpointing a specific part of the input, as the description might lead you to believe. Nonetheless, it has its limitations. In larger tacit programs, moving values to the right place is tedious and error-prone because of the lack of a convenient labelling mechanism, and important context tends to disappear in a sea of symbols.
    
+
    In smaller amountsβ€”portions of a lineβ€”tacit programming can be the clearest way to express an idea, particularly when just one or two variables are used a few times. Consider the following three expressions to filter only the positive values from a list:
    
+↗️
        l ← 0β€Ώ5β€ΏΒ―2β€Ώ1β€ΏΒ―3β€ΏΒ―4
+
+    (0<l)/l
+⟨ 5 1 ⟩
+    {(0<𝕩)/𝕩} l
+⟨ 5 1 ⟩
+    0⊸<⊸/ l
+⟨ 5 1 ⟩
+
    
+
    The first of these expressions is the most direct, but with the variable name buried inside, it can't be used on an intermediate value and its input will have to be named. The other two forms stand alone as functions, so they can easily be placed anywhere in a program, even as an operand. But with even the small amount of structure added by a BQN anonymous function, the second method has more organization than action! The third, tacit, version strips away most of the organizing syntax to leave us with the essential pieces 0, <, and / joined by combinators. The explicit function uses 𝕩 as a sort of pronoun ("I want the elements of it where it's greater than zero"), while the tacit one elides it ("give me the elements greater than zero").
    
+
    The ability to easily combine tacit and "explicit" programming such as statements or anonymous functions, far from being only a way to mitigate the disadvantages of these two methods, brings new advantages that no single paradigm could accomplish. Purely tacit programming requires programs to use no local variable names, but partly tacit programming allows them to use fewer names. That means names can be used only for the parts of a program that represent clean, human-understandable concepts. Another possible stategic choice is to use the fact that variables in a tacit expression are expanded as it's formed but those inside a block aren't. So F←a⊸+ can be chosen to "freeze" the value of a in F without having to use an extra variable, while F←{a+𝕩} uses the current value of a each time F is called.
    
+
    The rest of this page describes BQN's tacit programming facilities. Deciding when to use them is a matter of taste, and experience.
    
+
    Trains
    
+
    In modern APL and its relatives, the backbone of tacit infrastructure is the function train. Trains can take some practice to understand and use well, so they're described in more depth on a dedicated page. The idea of trains is that you can "apply" a function to other functions, forming a composed function where it will actually apply to their results. So a typical use is to pair two functions as shown below: the pair Β»β€ΏΒ« is never formed, but the result of applying T is a pair.
    
+↗️
        T ← Β» β‹ˆ Β«    # Pair both shift functions
+    T            # Nothing happens yet...
+Β»β‹ˆΒ«
+
+    T "abc"      # Now it forms a pair
+⟨ " ab" "bc " ⟩
+
+    'X' T "abc"  # Each shift gets both arguments
+⟨ "Xab" "bcX" ⟩
+
    
+
    Identity functions
    
+
    If you use trains even a little you'll quickly find the need to get an argument without applying any function to it. Take the pattern {(𝕨F𝕩)G𝕨} for example. You might expect ⊸⟜ (discussed below) to handle this, but they don't: in those combinators, the first function to be applied always has one argument, but F here has two. Instead, a good way to fit this into a tacit form is to note that π•¨βŠ£π•© is defined to be 𝕨, and substitute backwards to give {(𝕨F𝕩)G(π•¨βŠ£π•©)}, which now has the form of a train F G ⊣.
    
+↗️
        "whatsin" {(π•¨βˆŠπ•©)/𝕨} "intersect"
+"tsin"
+
+    "whatsin" (∊/⊣) "intersect"
+"tsin"
+
    
+
    The functions ⊣⊒ are as simple as they come, but are discussed quite a bit on their own page. A definition is that ⊒ is {𝕩} and ⊣ is {𝕩;𝕨}, so that ⊒ returns its right argument, and ⊣ returns its left argument but will settle for the right one if there's just one.
    
+
    Combinators
    
+
+  
+    
+    Atop
+    
+      π”½βˆ˜π”Ύ 𝕩
+      
+      
+      
+      
+      
+      𝔽
+      𝔾
+      𝕩
+    
+    
+      𝕨 π”½βˆ˜π”Ύ 𝕩
+      
+      
+      
+      
+      
+      
+      
+      𝔽
+      𝔾
+      𝕨
+      𝕩
+    
+  
+  
+    
+    Over
+    
+      𝔽○𝔾 𝕩
+      
+      
+      
+      
+      
+      𝔽
+      𝔾
+      𝕩
+    
+    
+      𝕨 𝔽○𝔾 𝕩
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      𝔽
+      𝔾
+      𝔾
+      𝕨
+      𝕩
+    
+  
+  
+    
+    Constant
+    
+      𝕗˙ 𝕩
+      
+      
+      
+      𝕗
+      𝕩
+    
+    
+      𝕨 𝕗˙ 𝕩
+      
+      
+      
+      
+      𝕗
+      𝕨
+      𝕩
+    
+  
+  
+    
+    Before
+    
+      π”½βŠΈπ”Ύ 𝕩
+      
+      
+      
+      
+      
+      
+      𝔾
+      𝔽
+      𝕩
+    
+    
+      𝕨 π”½βŠΈπ”Ύ 𝕩
+      
+      
+      
+      
+      
+      
+      
+      𝔾
+      𝔽
+      𝕨
+      𝕩
+    
+  
+  
+    
+    After
+    
+      π”½βŸœπ”Ύ 𝕩
+      
+      
+      
+      
+      
+      
+      𝔽
+      𝔾
+      𝕩
+    
+    
+      𝕨 π”½βŸœπ”Ύ 𝕩
+      
+      
+      
+      
+      
+      
+      
+      𝔽
+      𝔾
+      𝕨
+      𝕩
+    
+  
+  
+    
+    Self/Swap
+    
+      π”½Λœ 𝕩
+      
+      
+      
+      
+      𝔽
+      𝕩
+    
+    
+      𝕨 π”½Λœ 𝕩
+      
+      
+      
+      
+      
+      𝔽
+      𝕨
+      𝕩
+    
+  
+
+
-- 
cgit v1.2.3