lambda expressions, specifiers and operator

Author: dr-orlovsky

content/design.md

@@ -439,6 +439,95 @@ Standard library offers many types composed of the built-ins, including (but not
 - Bytes, fixed and dynamic byte arrays: `Byte`, `Bytes16`, `Bytes32`, `Blob256`, `Blob64kB`, `Blob16MB` `Blob4GB` etc;
 - Commonly-used monads `Maybe`, `Either`, `Result`, `Ternary`.
 
+### Lambda expressions
+
+<aside>
+  One of Cation's main features is an ability to treat data, values and functions the same way, making all of them
+  first-class citizens.
+</aside>
+
+<dfn>Lambda expressions</dfn> allow a combination of statements, capturing locally-defined values,
+to be treated as a function. They simplify passing functions as arguments to other functions, saving
+from boilerplate code.
+
+Lambda expressions have several forms. The canonical one is a specifier form, which starts with a `lambda` keyword,
+followed by a value name, colon, argument and return type definition and body:
+
+```
+let local: U8 = random
+lambda sq: x U8 -> U32
+    pow 2 + local
+```
+
+As any other specifier it can be put into a single line:
+```
+let local: U8 = random
+lambda sq: x U8 -> U32 := pow 2 + local
+```
+
+<aside>
+  The <code>.\</code> operator is shaped after Greek letter $\lambda$.
+</aside>
+
+The second form is an operator form using `.\` or Greek `λ`; it allows anonymous lambda definitions which may span
+a single or multiple lines. The specific syntax of this form depends on whether the lambda is the last expression in
+the line:
+
+```
+-- for the last expression in the line
+.\pow 2
+-- or even shorter
+.\^2
+```
+
+If a lambda expression has to be followed by other expressions, one need to put the expression into a parenthesis:
+```
+.\(pow 2), _
+```
+
+Lambda expressions may have own explicit arguments, separated from the function body using double-column. The return
+type may be omitted, and in this case if is inferred by the compiler from the body of the expression:
+```
+.\x U8 -> U16: x pow 2
+
+-- With a type omission:
+.\x U8: x pow 2
+
+-- If the expression is not at the end of a line
+.\(x U8: x pow 2), _
+```
+
+Finally, there is the multiline forms of lambda expressions:
+```
+let lambdaFn := .\
+    statement1
+    statement2
+```
+
+In can be used the same way as single-line expressions, with the only difference – there is no colon between the lambda
+declaration and the body:
+```
+.\ x U8
+   x pow 2
+
+.\ x U8 -> U16
+   x pow 2
+
+-- Here we can use multiline in the middle of other expression
+someFn arg1, .\(x U8 -> U16
+   x pow 2
+), argLast
+```
+
+The type of the lambda expression is `.\ input -> output`, and this type may be used in type annotations:
+```
+let squared: .\U8 -> U16 := .\pow 2
+```
+
+<!-- TODO: add on currying:
+Functions with multiple arguments is the same as a function with single argument made of anonymous data type composing
+the list of the arguments. -->
+
 
 ### Generics
 

content/reference.md

@@ -42,18 +42,19 @@ identifier; `` `x` `` and `x` has the same meaning.
 ### Keywords
 
 The following keywords are reserved and can’t be used as identifiers, unless they’re escaped with backticks, as
-described above in [Identifiers](#identifiers). Keywords other than `let` can be used as field or variant names in
-data types, as parameter names in a function declaration or function call without being escaped with backticks.
+described above in [Identifiers](#identifiers). Keywords other than `let` and `lambda` can be used as field or variant
+names in data types, as parameter names in a function declaration or function call without being escaped with backticks.
 
 - `data`: defines new data type
+- `class`: defines a new data type class
 - `fx`: defines new function (prefix function)
 - `infx`: defines new infix function
+- `lambda`: defines a lambda function
 - `alias`: defines a new alias for a function
-- `let`: defines new value with some data type
-- `class`: defines a new type class
+- `let`: defines new value
 
-The following tokens are reserved as punctuation and can’t be used as custom operators: `(`, `)`, `{`, `}`, `[`, `]`,
-`.`, `,`, `|`, `:`, `;`, `#`, `=>`, `->`, `<-`, `<|`, `|>`, `>|`, `|?`, `|:`, `` ` ``, `~`.
+The following tokens are reserved as built-in operators and can’t be used in custom operators: `(`, `)`, `{`, `}`, 
+`[`, `]`, `.`, `,`, `:`, `;`, `#`, `=>`, `->`, `<-`, `<|`, `|>`, `>|`, `|?`, `|:`, `.\`, `` ` ``.
 
 ### Literals
 
@@ -228,6 +229,73 @@ or reverse the order of the expressions:
 
     mulTry 2 <| 0..<100
 
+#### Lambda operator
+
+<dfn>Lambda operator</dfn> `.\`, with alias `λ` (Greek letter lambda) is a shorthand for creating lambda expressions.
+It has four forms:
+- single-line, end of line (trailing lambda):
+  ```
+  .\args -> ret: expr
+  ```
+- single-line, alongside other expressions:
+  ```
+  .\(args -> ret: expr), _
+  ```
+- multi-line, end of line (trailing lambda block):
+  ```
+  .\args -> ret
+    expr1
+    expr2
+    -- ...
+  ```
+- multi-line, alongside other expressions:
+  ```
+  .\(args -> ret
+    expr1
+    expr2
+    -- ...
+  ), _
+  ```
+
+All forms may skip the return type `-> ret` part; in this case the return type is inferred by the compiler:
+```
+.\args: expr
+
+.\(args: expr), _
+
+.\args
+  expr1
+  expr2
+  -- ...
+
+.\(args
+  expr1
+  expr2
+  -- ...
+), _
+```
+
+If the lambda expression has no inputs, lambda operator must be simply followed by the expression itself with no
+colon used:
+```
+.\expr
+
+.\(expr), _
+
+.\
+  expr1
+  expr2
+  -- ...
+
+.\(
+  expr1
+  expr2
+  -- ...
+), _
+```
+
+See also [lambda specifier](#lambda-specifier).
+
 ### Standard library
 
 #### Monadic operators
@@ -368,6 +436,10 @@ instantiated using a shorthand [range expressions](#range-expressions).
 
 ### Expressions
 
+#### Lambda expressions
+
+Lambda expressions have two forms: [operator](#lambda-operator) and [specifier](#lambda-specifier).
+
 #### Collection comprehension
 
 Grouping operator is `(`..`)` constructs an anonymous data type.
@@ -406,7 +478,26 @@ iterations, like with `$-1`, accessing the previous iteration result, or
 
 #### Data class
 
-#### Value
+#### Value specifier
+
+#### Lambda specifier
+
+<dfn>Lambda specifier</dfn> starts with a `lambda` keyword, followed by a value name, colon, argument and return type
+definition and body:
+
+```
+let local: U8 = random
+lambda sq: x U8 -> U32
+    pow 2 + local
+```
+
+As any other specifier it can be put into a single line:
+```
+let local: U8 = random
+lambda sq: x U8 -> U32 := pow 2 + local
+```
+
+See also [lambda operator](#lambda-operator).
 
 ## Generics