From 25311370e215cd12018dde8bd162583dbe36d473 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Mon, 15 Nov 2021 22:16:46 -0500 Subject: Compress expression section in syntax summary, moving details to expression page --- docs/doc/syntax.html | 96 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 56 insertions(+), 40 deletions(-) (limited to 'docs/doc/syntax.html') diff --git a/docs/doc/syntax.html b/docs/doc/syntax.html index 25f4ea23..673a5c29 100644 --- a/docs/doc/syntax.html +++ b/docs/doc/syntax.html @@ -123,46 +123,62 @@

The null character (code point 0) has a dedicated literal representation @. This character can be used to directly convert between characters and numeric code points, which among many other uses allows tricky characters to be entered by code point: for example, a non-breaking space is @+160. The character can also be entered as a character literal, but this will display differently in various editors and some tools may have trouble with a file directly containing a null, so it is best to use @ instead.

Expressions

-

More discussion

-

Like APL, BQN uses four syntactic roles for values in expressions:

- -

These roles work exactly like they do in APL, with functions applying to one or two subject arguments, 1-modifiers taking a single function or subject on the left, and 2-modifiers taking a function or subject on each side.

-

Unlike APL, in BQN the syntactic role of an identifier is determined purely by the way it's spelled: a lowercase first letter (name) makes it a subject, an uppercase first letter (Name) makes it a function, and underscores are used for 1-modifiers (_name) and 2-modifiers (_name_). Below, the function {π•Žπ•©} treats its left argument π•Ž as a function and its right argument 𝕩 as a subject. With a list of functions, we can make a table of the square and square root of a few numbers:

-↗️
    βŸ¨Γ—Λœ,√⟩ {π•Žπ•©}⌜ 1β€Ώ4β€Ώ9
-β”Œβ”€         
-β•΅ 1 16 81  
-  1  2  3  
-          β”˜
-
-

BQN's built-in operations also have patterns to indicate the syntactic role: 1-modifiers (˜¨˘⁼⌜´`) are all superscript characters, and 2-modifiers (βˆ˜β—‹βŠΈβŸœβŒΎβŠ˜β—Άβš‡βŽ‰βŸ) all have an unbroken circle (two functions βŒ½β‰ have broken circles with lines through them). Every other built-in constant is a function, although the special symbols Β―, ∞, and Ο€ are used as part of numeric literal notation.

-

Assignment

-

Another element that can be included in expressions is assignment, which is written with ← to define (also called "declare" in many other languages) a variable and ↩ to change its definition. A variable can only be defined once within a scope, and can only be changed if it has already been defined. However, it can be shadowed, meaning that it is defined again in an inner scope even though it has a definition in an outer scope already.

-↗️
    x←1 β‹„ {x←2 β‹„ x↩3 β‹„ x}
-3
-    x
-1
-
-

Assignment can be used inline in an expression, and its result is always the value being assigned. The role of the identifier used must match the value being assigned.

-↗️
    2Γ—a←(Neg←-)3
-Β―6
-    a
-Β―3
-
-

Exports

-

The double arrow ⇐ is used to export variables from a block or program, causing the result to be a namespace. There are two ways to export variables. First, ← in the variable definition can be replaced with ⇐ to export the variable as it's defined. Second, an export statement consisting of an assignment target followed by ⇐ with nothing to the right exports the variables in the assignment target and does nothing else. Export statements can be placed anywhere in the relevant program or body, including before declaration or on the last line, and a given variable can be exported any number of times.

-
⟨alias⇐a, b, c0β€Ώc1⇐c, b2⇐bβŸ©β†{
-  bβ€Ώc⇐   # Non-definition exports can go anywhere
-  a⇐2    # Define and export
-  b←1+a
-  c←bβ€Ώ"str"
-}
-
-

Fields of the resulting namespace can be accessed either directly using namespace.field syntax, or with a destructuring assignment as shown above. This assignment's target is a list where each element specifies one of the names exported by the block and what it should be assigned to. The element can be either a single name (such as b above), which gives both, or a combination of the assignment target, then ⇐, then a name. If ⇐ is never used, the names can be given as a strand with β€Ώ. To use ⇐ for aliases, bracket syntax ⟨⟩ is needed. Imported names can be repeated and can be spelled with any role (the role is ignored).

+

Full documentation

+

BQN expressions are composed of subjects, functions, and modifiers, with parentheses to group parts into subexpressions. Functions can be applied to subjects or grouped into trains, while modifiers can be applied to subjects or functions. The most important kinds of application are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
exampleleftmainrightoutputnamebinding
↕ 10w?FxSubjectFunctionRtL, looser
+ β‹ˆ -F?GHFunctionTrain
Γ—Β΄F_mFunction1-ModifierLtR, tighter
2⊸|F_c_GFunction2-Modifier
+

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.

+

Assignment arrows ←, ↩, and ⇐ store expression results in variables: ← and ⇐ create new variables while ↩ modifies existing ones. The general format is Name ← Value, where the two sides have the same role. Additionally, lhs F↩ rhs is a shortened form of lhs ↩ lhs F rhs and lhs F↩ expands to lhs ↩ F lhs.

+

The double arrow ⇐ is used for functionality relating to namespaces. 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.

Lists and blocks

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

-- cgit v1.2.3