From f2cd25f1ab2b04007c1f112dfffd3590e60f2d3b Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sat, 9 Oct 2021 21:12:05 -0400 Subject: Documentation for Nothing --- docs/doc/arrayrepr.html | 2 +- docs/doc/block.html | 4 ++-- docs/doc/expression.html | 10 ++++++++++ docs/doc/glossary.html | 2 +- docs/doc/train.html | 2 +- 5 files changed, 15 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/doc/arrayrepr.html b/docs/doc/arrayrepr.html index 7c27fa07..a6da93aa 100644 --- a/docs/doc/arrayrepr.html +++ b/docs/doc/arrayrepr.html @@ -171,7 +171,7 @@

Even special characters like a newline can appear in a string literal, so that string literals are automatically multi-line.

Brackets

-

List notation uses angle brackets ⟨⟩. The contents are structurally identical to those of a block, that is, a list of expressions separated by , or ⋄ or newlines. Unlike a block, a list doesn't need to have any expressions: ⟨⟩ or ⟨⋄⟩ or ⟨,,⋄,⟩ will create an empty list. Other differences are that a list doesn't introduce a new scope and all of the expressions have to result in a value, not Nothing (·).

+

List notation uses angle brackets ⟨⟩. The contents are structurally identical to those of a block, that is, a list of expressions separated by , or ⋄ or newlines. Unlike a block, a list doesn't need to have any expressions: ⟨⟩ or ⟨⋄⟩ or ⟨,,⋄,⟩ will create an empty list. Other differences are that a list doesn't introduce a new scope and all of the expressions have to result in a value, not Nothing (·).

Entries in a list are evaluated in source order, and the value will be the list of those results. The list has a subject role, even if it contains expressions with other roles. Any value can be an element.

↗️
    ⟨@, ⍉˘, ≍"abc"⟩
 ┌─              
diff --git a/docs/doc/block.html b/docs/doc/block.html
index fa5174c4..d3eb2bb8 100644
--- a/docs/doc/block.html
+++ b/docs/doc/block.html
@@ -41,7 +41,7 @@
 
 𝕨
 𝕎
-Left argument, or Nothing (·)
+Left argument, or Nothing (·)
 
 
 𝕤
@@ -75,7 +75,7 @@
     4 { ⟨𝕩⋄-𝕨⟩ } 5
 ⟨ 5 ¯4 ⟩
-

A function with 𝕨 in its definition doesn't have to be called with two arguments. If it has only one, then 𝕨 is given the special value Nothing ·. This is the only time a variable can ever be Nothing, as an assignment such as v←· is not allowed.

+

A function with 𝕨 in its definition doesn't have to be called with two arguments. If it has only one, then 𝕨 is given the special value Nothing, or ·. This is the only time a variable can ever be Nothing, as an assignment such as v←· is not allowed.

↗️
    3 { (2×𝕨)-𝕩 } 1
 5
       { (2×𝕨)-𝕩 } 1
diff --git a/docs/doc/expression.html b/docs/doc/expression.html
index 90375248..9e386079 100644
--- a/docs/doc/expression.html
+++ b/docs/doc/expression.html
@@ -56,6 +56,7 @@
 
 
 
The four roles (subject, function, two kinds of modifier) describe expressions, not values. When an expression is evaluated, the value's type doesn't have to correspond to its role, and can even change from one evaluation to another. An expression's role is determined entirely by its source code, so it's fixed.

+
In the table, ? marks an optional left argument. If there isn't a value in that position, or it's Nothing (·), the middle function will be called with only one argument.

 
If you're comfortable reading BNF and want to understand things in more detail than described below, you might check the grammar specification as well.

 
Syntactic role

 
This issue is approached from a different angle in Context free grammar.

@@ -98,6 +99,15 @@
 
Variable names can be written in any case and with underscores added, and these changes don't affect what identifier the name refers to. ab, aB, AB, and _a_B_ are all the same variable. However, the spelling—specifically the first and last characters—determine the variable's role. A lowercase first letter indicates a subject, and an uppercase first letter makes it a function. A leading underscore (regardless of the following character) indicates a 1-modifier, and both leading and trailing underscores makes a 2-modifier.

 
Besides these, character, string, and list literals always have a subject role, and the role of a block is determined by its type, which depends either on the header it has or which special variables it uses.

 
The role of a compound expression, formed by applying an operation to some inputs, depends on the operation applied. This system is discussed in the remaining sections below.

+
Nothing

+
The character · is called Nothing. While it can be easier to think of it as a value, it can't be passed around in variables, and so can also be interpreted as an element of syntax. The special name 𝕨 also functions as Nothing if the block that contains it is called with one argument (the uppercase spelling 𝕎 doesn't, but instead immediately causes an error). Both · and 𝕨 have a subject role.

+
The following rules apply to Nothing:

+
+
For example, the expression (F 2 G ·) H I j is equivalent to H I j. But functions and arguments that would be discarded by the second rule are still evaluated, so that for example (a+↩1) F · increments a when run.

+
Nothing can only be used as an argument to a function, or the left argument in a train (it can't be the right argument in a train because a train ends with a function by definition). In another position where a subject could appear, like as an operand or in a list, it causes an error: either at compile time, for ·, or when the function is called with no left argument, for 𝕨.

 
Kinds of application

 
Here is a table of the modifier and function application rules:

 
diff --git a/docs/doc/glossary.html b/docs/doc/glossary.html
index 8aeb819a..1220fa6c 100644
--- a/docs/doc/glossary.html
+++ b/docs/doc/glossary.html
@@ -116,7 +116,7 @@