diff options
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/identity.md | 69 | ||||
| -rw-r--r-- | doc/primitive.md | 4 | ||||
| -rw-r--r-- | docs/doc/identity.html | 86 | ||||
| -rw-r--r-- | docs/doc/index.html | 1 | ||||
| -rw-r--r-- | docs/doc/primitive.html | 8 |
6 files changed, 163 insertions, 6 deletions
diff --git a/doc/README.md b/doc/README.md index b4d28b13..f1311104 100644 --- a/doc/README.md +++ b/doc/README.md @@ -35,6 +35,7 @@ Primitives: - [Deshape and Reshape](reshape.md) (`⥊`) - [Fold and Insert](fold.md) (`´˝`) - [Group](group.md) (`⊔`) +- [Identity functions](identity.md) (`⊢⊣`) - [Join and Join To](join.md) (`∾`) - [Logical functions](logic.md) (`∧∨¬`) - [Match](match.md) (`≡≢`) diff --git a/doc/identity.md b/doc/identity.md new file mode 100644 index 00000000..b9cfd395 --- /dev/null +++ b/doc/identity.md @@ -0,0 +1,69 @@ +*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/identity.html).* + +# Identity functions + +Here are the simplest functions in BQN: Right (`⊢`) always returns its right argument, and Left (`⊣`) returns its left argument if called with two arguments, and the right argument otherwise. + + ⊢ "only" + + ⊣ "only" + + "left" ⊢ "right" + + "left" ⊣ "right" + +Depending on your past experiences, this could cause some confusion: built-in support for functions that do nothing? Documentation should say why a feature's there and how to use it, not just what it does, so we'll try to address this below. The most important single use is for tacit programming, but there are a variety of other uses as well. + +Of course, it's easy to write block functions `{𝕩}` and `{𝕨}` that return particular arguments. While I would already make `⊣` and `⊢` primitives just because they are common and important, there are also specific disadvantages to using blocks. They fail to indicate that there are no side effects, as primitives would, and they also need special casing for the interpreter to manipulate them when applying Undo (`⁼`) or making other inferences. + +## Filling arrays + +What's the easiest way to create a matrix with 0 on the first row, 1 on the second, and so on? Probably this one, with [table](map.md): + + (↕4) ⊣⌜ ↕5 + +The right argument `↕5` could be any length-5 list, as its values aren't used. With `5⥊0`, we could use `+⌜` instead, but requiring a specific argument seems artificial. A similar pattern applies with Each: + + (⌽↕4) ⊣¨ ↕4‿5 + +A more powerful pattern is with dyadic Under (`⌾`): unselected parts of the result will use values from `𝕩`. If `𝔽` is `⊣`, then the selected ones will use values from `𝕨`, merging these arrays together. + + "ABCDE" ⊣⌾(0‿1‿1‿0‿0⊸/) "abcde" + + ⟨"wxy"‿"z",@⟩ ⊣⌾(1⊑⊑∘⊑) ⟨⟨↕3,↕2⟩,4‿5⟩ + +This method can replace even values nested deeply in arrays, as long as you can write the function to get at them. The parts that aren't accessed don't even need to have matching shapes! + +## As a variable + +Suppose you want a list of a matrix, its transpose, and its negation. One way to do this is to put together a list of functions for each of these values: the first one is an identity. + + ⊢‿⍉‿- {𝕎𝕩}¨< 0‿¯1≍1‿0 + +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. + + 3 {𝕩-𝕨÷1+𝕩} 5 + 3 (⊢-⊣÷1+⊢) 5 + +A larger class of block functions can be translated just by adding parentheses and `˙` (there's a discussion of this technique in APL [here](https://dfns.dyalog.com/n_tacit.htm)). It's helpful when writing tacit code to know that `Fn∘⊣` applies `Fn` to the left argument only and `Fn∘⊢` applies it to the right argument—these can be read "Fn of left" and "Fn of right". + +## Syntax tricks + +You've probably seen `⊢` used in documentation to display the value of a variable being assigned. This is a hack, and in most contexts `•Show` should be used to display values. + + ⊢ a ← "show this" + +More importantly, `∘⊣` can be used to ignore a right argument for modified assignment, to apply a function "in place" to a variable without writing the variable name twice. + + a ⌽∘⊣↩ @ + +In APL a tack can be used to avoid stranding numbers together. In BQN, stranding is explicit, and there's no need! + + ÷⟜2⍟3⊢ 24 + ÷⟜2⍟3 24 + +(Wow, what a useless section.) diff --git a/doc/primitive.md b/doc/primitive.md index b47b885a..d32460c5 100644 --- a/doc/primitive.md +++ b/doc/primitive.md @@ -34,8 +34,8 @@ Functions that have significant differences from APL functions are marked with a | `≠` | [Length](shape.md) | [Not Equals](https://aplwiki.com/wiki/Not_Equal_to) | `≡` | [Depth](depth.md)* | [Match](match.md) | `≢` | [Shape](shape.md) | [Not Match](match.md) -| `⊣` | [Identity](https://aplwiki.com/wiki/Identity) | [Left](https://aplwiki.com/wiki/Identity) -| `⊢` | [Identity](https://aplwiki.com/wiki/Identity) | [Right](https://aplwiki.com/wiki/Identity) +| `⊣` | [Identity](identity.md) | [Left](identity.md) +| `⊢` | [Identity](identity.md) | [Right](identity.md) | `⥊` | [Deshape](reshape.md) | [Reshape](reshape.md)* | `∾` | [Join](join.md)* | [Join to](join.md) | `≍` | [Solo](couple.md)* | [Couple](couple.md)* diff --git a/docs/doc/identity.html b/docs/doc/identity.html new file mode 100644 index 00000000..f865e960 --- /dev/null +++ b/docs/doc/identity.html @@ -0,0 +1,86 @@ +<head> + <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/> + <link href="../style.css" rel="stylesheet"/> + <title>BQN: Identity functions</title> +</head> +<div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">doc</a></div> +<h1 id="identity-functions">Identity functions</h1> +<p>Here are the simplest functions in BQN: Right (<code><span class='Function'>⊢</span></code>) always returns its right argument, and Left (<code><span class='Function'>⊣</span></code>) returns its left argument if called with two arguments, and the right argument otherwise.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiICJvbmx5IgoK4oqjICJvbmx5IgoKImxlZnQiIOKKoiAicmlnaHQiCgoibGVmdCIg4oqjICJyaWdodCI=">↗️</a><pre> <span class='Function'>⊢</span> <span class='String'>"only"</span> +"only" + + <span class='Function'>⊣</span> <span class='String'>"only"</span> +"only" + + <span class='String'>"left"</span> <span class='Function'>⊢</span> <span class='String'>"right"</span> +"right" + + <span class='String'>"left"</span> <span class='Function'>⊣</span> <span class='String'>"right"</span> +"left" +</pre> +<p>Depending on your past experiences, this could cause some confusion: built-in support for functions that do nothing? Documentation should say why a feature's there and how to use it, not just what it does, so we'll try to address this below. The most important single use is for tacit programming, but there are a variety of other uses as well.</p> +<p>Of course, it's easy to write block functions <code><span class='Brace'>{</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code> and <code><span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Brace'>}</span></code> that return particular arguments. While I would already make <code><span class='Function'>⊣</span></code> and <code><span class='Function'>⊢</span></code> primitives just because they are common and important, there are also specific disadvantages to using blocks. They fail to indicate that there are no side effects, as primitives would, and they also need special casing for the interpreter to manipulate them when applying Undo (<code><span class='Modifier'>⁼</span></code>) or making other inferences.</p> +<h2 id="filling-arrays">Filling arrays</h2> +<p>What's the easiest way to create a matrix with 0 on the first row, 1 on the second, and so on? Probably this one, with <a href="map.html">table</a>:</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKGlTQpIOKKo+KMnCDihpU1">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>↕</span><span class='Number'>4</span><span class='Paren'>)</span> <span class='Function'>⊣</span><span class='Modifier'>⌜</span> <span class='Function'>↕</span><span class='Number'>5</span> +┌─ +╵ 0 0 0 0 0 + 1 1 1 1 1 + 2 2 2 2 2 + 3 3 3 3 3 + ┘ +</pre> +<p>The right argument <code><span class='Function'>↕</span><span class='Number'>5</span></code> could be any length-5 list, as its values aren't used. With <code><span class='Number'>5</span><span class='Function'>⥊</span><span class='Number'>0</span></code>, we could use <code><span class='Function'>+</span><span class='Modifier'>⌜</span></code> instead, but requiring a specific argument seems artificial. A similar pattern applies with Each:</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKMveKGlTQpIOKKo8KoIOKGlTTigL81">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>⌽↕</span><span class='Number'>4</span><span class='Paren'>)</span> <span class='Function'>⊣</span><span class='Modifier'>¨</span> <span class='Function'>↕</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span> +┌─ +╵ 3 3 3 3 3 + 2 2 2 2 2 + 1 1 1 1 1 + 0 0 0 0 0 + ┘ +</pre> +<p>A more powerful pattern is with dyadic Under (<code><span class='Modifier2'>⌾</span></code>): unselected parts of the result will use values from <code><span class='Value'>𝕩</span></code>. If <code><span class='Function'>𝔽</span></code> is <code><span class='Function'>⊣</span></code>, then the selected ones will use values from <code><span class='Value'>𝕨</span></code>, merging these arrays together.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=IkFCQ0RFIiDiiqPijL4oMOKAvzHigL8x4oC/MOKAvzDiirgvKSAiYWJjZGUiCgrin6gid3h5IuKAvyJ6IixA4p+pIOKKo+KMvigx4oqR4oqR4oiY4oqRKSDin6jin6jihpUzLOKGlTLin6ksNOKAvzXin6k=">↗️</a><pre> <span class='String'>"ABCDE"</span> <span class='Function'>⊣</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Modifier2'>⊸</span><span class='Function'>/</span><span class='Paren'>)</span> <span class='String'>"abcde"</span> +"aBCde" + + <span class='Bracket'>⟨</span><span class='String'>"wxy"</span><span class='Ligature'>‿</span><span class='String'>"z"</span><span class='Separator'>,</span><span class='String'>@</span><span class='Bracket'>⟩</span> <span class='Function'>⊣</span><span class='Modifier2'>⌾</span><span class='Paren'>(</span><span class='Number'>1</span><span class='Function'>⊑⊑</span><span class='Modifier2'>∘</span><span class='Function'>⊑</span><span class='Paren'>)</span> <span class='Bracket'>⟨⟨</span><span class='Function'>↕</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Function'>↕</span><span class='Number'>2</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span><span class='Bracket'>⟩</span> +┌─ +· ⟨ ⟨ 0 'x' 2 ⟩ ⟨ 0 1 ⟩ ⟩ ⟨ 4 5 ⟩ + ┘ +</pre> +<p>This method can replace even values nested deeply in arrays, as long as you can write the function to get at them. The parts that aren't accessed don't even need to have matching shapes!</p> +<h2 id="as-a-variable">As a variable</h2> +<p>Suppose you want a list of a matrix, its transpose, and its negation. One way to do this is to put together a list of functions for each of these values: the first one is an identity.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqi4oC/4o2J4oC/LSB78J2VjvCdlal9wqg8IDDigL/CrzHiiY0x4oC/MA==">↗️</a><pre> <span class='Function'>⊢</span><span class='Ligature'>‿</span><span class='Function'>⍉</span><span class='Ligature'>‿</span><span class='Function'>-</span> <span class='Brace'>{</span><span class='Function'>𝕎</span><span class='Value'>𝕩</span><span class='Brace'>}</span><span class='Modifier'>¨</span><span class='Function'><</span> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Function'>≍</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span> +┌─ +· ┌─ ┌─ ┌─ + ╵ 0 ¯1 ╵ 0 1 ╵ ¯0 1 + 1 0 ¯1 0 ¯1 ¯0 + ┘ ┘ ┘ + ┘ +</pre> +<p>Here <code><span class='Function'>⊢</span></code> ends up being used as <code><span class='Function'>𝕎</span></code>. 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 <code><span class='Function'>⊢</span></code>. Or it might happen that you write a Choose (<code><span class='Modifier2'>◶</span></code>) expression where one of the cases should do nothing <code><span class='Function'>⊢</span></code>, or return the left argument <code><span class='Function'>⊣</span></code>.</p> +<h2 id="in-tacit-functions">In tacit functions</h2> +<p>In a tacit context, <code><span class='Function'>⊣</span></code> is roughly equivalent to <code><span class='Value'>𝕨</span></code> and <code><span class='Function'>⊢</span></code> to <code><span class='Value'>𝕩</span></code>. 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.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MyB78J2VqS3wnZWow7cxK/Cdlal9IDUKMyAo4oqiLeKKo8O3MSviiqIpIDU=">↗️</a><pre> <span class='Number'>3</span> <span class='Brace'>{</span><span class='Value'>𝕩</span><span class='Function'>-</span><span class='Value'>𝕨</span><span class='Function'>÷</span><span class='Number'>1</span><span class='Function'>+</span><span class='Value'>𝕩</span><span class='Brace'>}</span> <span class='Number'>5</span> +4.5 + <span class='Number'>3</span> <span class='Paren'>(</span><span class='Function'>⊢-⊣÷</span><span class='Number'>1</span><span class='Function'>+⊢</span><span class='Paren'>)</span> <span class='Number'>5</span> +4.5 +</pre> +<p>A larger class of block functions can be translated just by adding parentheses and <code><span class='Modifier'>˙</span></code> (there's a discussion of this technique in APL <a href="https://dfns.dyalog.com/n_tacit.htm">here</a>). It's helpful when writing tacit code to know that <code><span class='Function'>Fn</span><span class='Modifier2'>∘</span><span class='Function'>⊣</span></code> applies <code><span class='Function'>Fn</span></code> to the left argument only and <code><span class='Function'>Fn</span><span class='Modifier2'>∘</span><span class='Function'>⊢</span></code> applies it to the right argument—these can be read "Fn of left" and "Fn of right".</p> +<h2 id="syntax-tricks">Syntax tricks</h2> +<p>You've probably seen <code><span class='Function'>⊢</span></code> used in documentation to display the value of a variable being assigned. This is a hack, and in most contexts <code><span class='Function'>•Show</span></code> should be used to display values.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICJzaG93IHRoaXMi">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='String'>"show this"</span> +"show this" +</pre> +<p>More importantly, <code><span class='Modifier2'>∘</span><span class='Function'>⊣</span></code> can be used to ignore a right argument for modified assignment, to apply a function "in place" to a variable without writing the variable name twice.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSDijL3iiJjiiqPihqkgQA==">↗️</a><pre> <span class='Value'>a</span> <span class='Function'>⌽</span><span class='Modifier2'>∘</span><span class='Function'>⊣</span><span class='Gets'>↩</span> <span class='String'>@</span> +"siht wohs" +</pre> +<p>In APL a tack can be used to avoid stranding numbers together. In BQN, stranding is explicit, and there's no need!</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=w7fin5wy4o2fM+KKoiAyNArDt+KfnDLijZ8zIDI0">↗️</a><pre> <span class='Function'>÷</span><span class='Modifier2'>⟜</span><span class='Number'>2</span><span class='Modifier2'>⍟</span><span class='Number'>3</span><span class='Function'>⊢</span> <span class='Number'>24</span> +3 + <span class='Function'>÷</span><span class='Modifier2'>⟜</span><span class='Number'>2</span><span class='Modifier2'>⍟</span><span class='Number'>3</span> <span class='Number'>24</span> +3 +</pre> +<p>(Wow, what a useless section.)</p> diff --git a/docs/doc/index.html b/docs/doc/index.html index 8d08b068..d962f10e 100644 --- a/docs/doc/index.html +++ b/docs/doc/index.html @@ -41,6 +41,7 @@ <li><a href="reshape.html">Deshape and Reshape</a> (<code><span class='Function'>⥊</span></code>)</li> <li><a href="fold.html">Fold and Insert</a> (<code><span class='Modifier'>´˝</span></code>)</li> <li><a href="group.html">Group</a> (<code><span class='Function'>⊔</span></code>)</li> +<li><a href="identity.html">Identity functions</a> (<code><span class='Function'>⊢⊣</span></code>)</li> <li><a href="join.html">Join and Join To</a> (<code><span class='Function'>∾</span></code>)</li> <li><a href="logic.html">Logical functions</a> (<code><span class='Function'>∧∨¬</span></code>)</li> <li><a href="match.html">Match</a> (<code><span class='Function'>≡≢</span></code>)</li> diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html index 19c30c47..c0afd5a9 100644 --- a/docs/doc/primitive.html +++ b/docs/doc/primitive.html @@ -121,13 +121,13 @@ </tr> <tr> <td><code><span class='Function'>⊣</span></code></td> -<td><a href="https://aplwiki.com/wiki/Identity">Identity</a></td> -<td><a href="https://aplwiki.com/wiki/Identity">Left</a></td> +<td><a href="identity.html">Identity</a></td> +<td><a href="identity.html">Left</a></td> </tr> <tr> <td><code><span class='Function'>⊢</span></code></td> -<td><a href="https://aplwiki.com/wiki/Identity">Identity</a></td> -<td><a href="https://aplwiki.com/wiki/Identity">Right</a></td> +<td><a href="identity.html">Identity</a></td> +<td><a href="identity.html">Right</a></td> </tr> <tr> <td><code><span class='Function'>⥊</span></code></td> |