diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/arrayrepr.md | 22 | ||||
| -rw-r--r-- | doc/expression.md | 10 | ||||
| -rw-r--r-- | doc/syntax.md | 15 |
3 files changed, 27 insertions, 20 deletions
diff --git a/doc/arrayrepr.md b/doc/arrayrepr.md index e4f93948..ca2f3f86 100644 --- a/doc/arrayrepr.md +++ b/doc/arrayrepr.md @@ -84,11 +84,11 @@ The second is for lists with simple enough elements, which are displayed on one This case also covers empty lists, which are shown as `⟨⟩`. This includes an empty string, as the only difference between an empty string and any other empty list is its fill element and array displays don't depend on the fill. -## List literals +## Array literals *The tutorial section [here](../tutorial/list.md#list-notation) also covers this topic.* -There are three kinds literal notation for lists: strings, list notation, and stranding. Strings indicate character lists (with space for the [fill](fill.md)) and the other two can combine any sequence of elements. +There are three kinds literal notation for lists: strings, list notation, and stranding. Strings indicate character lists (with space for the [fill](fill.md)) and the other two can combine any sequence of elements. Additionally, there's a square bracket notation that can form higher-rank arrays. ### Strings @@ -121,6 +121,14 @@ BQN's separator rules give list notation a very flexible structure. You can put "e6" ⟩ +#### High-rank arrays + +Higher-rank arrays can be written with `[]`, an **array notation** that indicates each element is to be used as a [cell](array.md#cells) of its result. It's identical to forming a list and applying [Merge](couple.md#merge-and-array-theory) (`[…]` is the same as `>⟨…⟩`). + + [2‿3, 4‿1, 0‿5] + +This syntax doesn't work for creating rank 0 arrays—use [Enclose](enclose.md) `<` for these—or empty arrays. The notation `[]` would be ambiguous, so it's not allowed (although it can be used for destructuring, which works with an existing array). To create a specific empty array, [Reshape](reshape.md) (`⥊`) is probably the best approach. + ### Strands **Strand notation** is another way to write lists of length two or more. The elements are connected with the ligature character `‿`. It has a precedence lower than the [namespace](namespace.md) dot but higher than anything else other than paired brackets `()`, `{}`, and `⟨⟩`, so compound elements generally need to be placed in parentheses. Expressions joined by ligatures behave exactly the same as those in list notation: they are evaluated in order and placed in a list. @@ -146,13 +154,3 @@ Explicit stranding is also more general, because it applies equally to elements Why couldn't the more explicit list notation `⟨a,b,c⟩` drop the separators? This is also largely for reasons of generality—even more important here since `⟨⟩` is the more general-purpose list notation. Writing `⟨÷,-,4⟩` without the `,` won't go well. For something like `⟨2×c,b-1⟩`, maybe the interpreter could sort it out but it would be pretty confusing. Pretty soon you're going through the list character by character trying to figure out which space is actually a separator. And cursing, probably. Fortunately, I find that after a reasonable period of adjustment typing ligatures instead of spaces doesn't feel strange, and reading code is improved overall by the more explicit notation. A minor note is that lists of literal numbers, where APL-style stranding is best, tend to show up more in the snippets that beginners write to test out the language than in programs even in the tens of lines. So this issue sticks out in first experiences with BQN, but will come up less later on. - -### Array notation? - -BQN has literal notation for lists only right now. To get an array with rank other than 1, either [reshape](reshape.md) a list, or [merge](couple.md#merge-and-array-theory) a list of arrays: - - ∘‿2 ⥊ ⟨2,3, 4,1, 0,5⟩ - - [2‿3, 4‿1, 0‿5] - -The characters `[]` are reserved to potentially combine list notation with merging, allowing the above to be written `[2‿3, 4‿1, 0‿5]`. This would allow non-empty arrays with rank one or more to be written without a primitive, but not rank 0 or empty arrays. Since creating arrays in general would still require primitives like `<` or `⥊`, it's not clear whether this notation is worth it. General array notation is a surprisingly complicated topic; see the article about it [on the APL Wiki](https://aplwiki.com/wiki/Array_notation). diff --git a/doc/expression.md b/doc/expression.md index 754775ea..d5ca2035 100644 --- a/doc/expression.md +++ b/doc/expression.md @@ -2,7 +2,7 @@ # Expression syntax -BQN expressions are the part of [syntax](syntax.md) that describes computations to perform. Programs are mainly made up of expressions with a little organizing material like [blocks](block.md) and [namespaces](namespace.md) around them. This page explains how functions, modifiers, and assignment combine with their inputs. It doesn't describe [constant](syntax.md#constants) and [array](arrayrepr.md#list-literals) literals, which each form a single subject for grammatical purposes. +BQN expressions are the part of [syntax](syntax.md) that describes computations to perform. Programs are mainly made up of expressions with a little organizing material like [blocks](block.md) and [namespaces](namespace.md) around them. This page explains how functions, modifiers, and assignment combine with their inputs. It doesn't describe [constant](syntax.md#constants) and [array](arrayrepr.md#array-literals) literals, which each form a single subject for grammatical purposes. The [first tutorial](../tutorial/expression.md) also covers how to build and read BQN expressions. @@ -54,7 +54,7 @@ Primitive tokens, since they have a fixed value, always have a role that matches Variable names can be written in any case and with underscores added, and these changes don't affect what [identifier](lexical.md) 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](arrayrepr.md#list-literals) always have a subject role, and the role of a [block](block.md) is determined by its type, which depends either on the header it has or which special variables it uses. +Besides these, character, string, and [array literals](arrayrepr.md#array-literals) always have a subject role, and the role of a [block](block.md) 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. @@ -114,6 +114,12 @@ The left hand side of assignment in a subject expression can be *compound*, so t s +Array destructuring using `[]` is also possible: it's equivalent to splitting the right-hand side with `<˘` and then applying list destructuring. + + [t,u] ← ↕2‿3 + + u + Namespace destructuring uses an overlapping syntax, fully described in [its own section](namespace.md#imports). The left hand side is a list of names or aliases `to⇐from`. q‿r ↩ {q⇐2+r⇐0.5} ⋄ q diff --git a/doc/syntax.md b/doc/syntax.md index 7464d533..bbde476e 100644 --- a/doc/syntax.md +++ b/doc/syntax.md @@ -20,8 +20,9 @@ Glyph(s) | Meaning `⇐` | [Export](expression.md#exports) `↩` | [Change](expression.md#assignment) `⋄,` or newline | Statement or element [separator](#separators) -`⟨⟩` | [List](#list-notation) (rank-1 array) -`‿` | [Strand](#list-notation) (lightweight list syntax) +`⟨⟩` | [List](#list-and-array-notation) +`[]` | [Array](#list-and-array-notation) +`‿` | [Strand](#list-and-array-notation) (lightweight list syntax) `{}` | [Block](#blocks) such as a function definition `:` | [Block header](block.md#block-headers) `;` | [Block body separator](block.md#multiple-bodies) @@ -74,20 +75,22 @@ The four [roles](expression.md#syntactic-role) (subject, function, two kinds of The double arrow `⇐` is used for functionality relating to [namespaces](namespace.md). It has a few purposes: exporting assignment `name⇐value`, plain export `name⇐`, and aliasing `⟨alias⇐field⟩←namespace`. A block that uses it for export returns a namespace rather than the result of its last statement. The other namespace-related bit of syntax is field access `ns.field`. -## Lists and blocks +## Arrays and blocks -Lists and code blocks can both be represented as sequences of expressions in source code. They both have paired bracket representations, using `⟨⟩` for lists and `{}` for blocks, as well as a shortcut "stranding" notation using `‿` for lists. +Arrays and code blocks can both be represented as sequences of expressions in source code. There are paired bracket representations, using `⟨⟩` for lists, `[]` for arrays, and `{}` for blocks, as well as a shortcut "stranding" notation using `‿` for lists. ### Separators The characters `⋄` and `,` and newline are completely interchangeable and are used to separate expressions. An expression might be an element in a list or a line in a block. Empty sections—those that consist only of whitespace—are ignored. This means that any number of separators can be used between expressions, and that leading and trailing separators are also allowed. The expressions are evaluated in text order: left to right and top to bottom. -### List notation +### List and array notation -*[Full documentation](arrayrepr.md#list-literals)* +*[Full documentation](arrayrepr.md#array-literals)* Lists (1-dimensional arrays) are enclosed in angle brackets `⟨⟩`, with the results of the expressions in between being the list's elements. Lists of two elements or more can also be written with the ligature character `‿`. This character has higher binding strength than any part of an expression except `.` for namespace field access. If one of the elements is a compound expression, then it will need to be enclosed in parentheses. +Arrays, or at least non-empty ones with rank 1 or more, can be written with square brackets `[]`. These work just like angle brackets but [merge](couple.md#merge-and-array-theory) the elements so that they form cells of the result. + ### Blocks *[Full documentation](block.md)* |