Add generality notes: Function defaults, and function <-> block/stmt unification

Author: hsutter

docs/cpp2/aliases.md

@@ -1,6 +1,6 @@
-# Declaration syntax
+# Declarations and aliases
 
-## Overview: Unified declaration syntax
+## Unified declarations
 
 All Cpp2 declarations are written as **"_name_ `:` _kind_ `=` _statement_"**.
 
@@ -20,10 +20,70 @@ Various parts of the syntax allow a `_` "don't care" wildcard or can be omitted
 >
 > - When the type is omitted, whitespace does not matter, and writing `#!cpp x: = 0;` or `#!cpp x : = 0;` or `#!cpp x := 0;` or other whitespace is just a stylistic choice. This documentation's style uses the last one, except when there are multiple adjacent declaration lines this style lines up their `:` and `=`.
 >
-> - `==` stresses that this name will always have the given value, to express [aliases](aliases.md) and side-effect-free 'constexpr' [function aliases](aliases.md/#function-aliases).
+> - `==` stresses that this name will always have the given value, to express [aliases](#aliases) and side-effect-free 'constexpr' [function aliases](#function-aliases).
 
 
-## <a id="template-parameters"></a> Template parameters
+### <a id="unnamed-declarations"></a> Unnamed declaration expressions
+
+In an expression, most declarations can be written without a name (just starting with `:`). Such unnamed declaration expressions are useful for single-use temporary variables or 'lambda' functions that don't need a name to be reused elsewhere. For example:
+
+- `#!cpp :widget = 42` is an unnamed expression-local (aka temporary) object of type `widget` defined as having the initial value `#!cpp 42`. It uses the same general syntax, just
+
+- `#!cpp :(x) = std::cout << x` is an unnamed expression-local generic function expression (aka lambda) defined as having the given one-statement body. The body can include [captures](expressions.md/#captures)
+
+Both just omit the name and make the final `;` optional. Otherwise, they have the identical syntax and meaning as if you declared the same thing with a name outside expression scope (e.g., `w: widget = 42;` or `f: (x) = std::cout << x;`) and then used the name in the expression.
+
+> Note: Throughout Cpp2, every declaration is written with `:`, and every use of `:` is a declaration.
+
+
+
+### <a id="function-scope-unification"></a> From functions to local scopes, and back again
+
+The function syntax is deliberately designed to be general, so you can omit parts. This means Cpp2 has no special "lambda function" syntax for unnamed functions; an unnamed function is really an unnamed function, written using the ordinary function just without a name. This scales all the way down to ordinary blocks and statements, which are written the same as functions that have no name or parameters.
+
+We can illustrate this in two directions. First, let's start with a full function, and successively omit optional parts that we aren't currently using:
+
+``` cpp title="Start with a full function, and successively omit optional parts if unused" hl_lines="1 5 9 13"
+// Full named function
+f:(x: int = init) = { /*...*/ }     // x is a parameter to the function
+f:(x: int = init) = statement;      // same, { } is implicit
+
+// Omit name => anonymous function (aka 'lamba')
+ :(x: int = init) = { /*...*/ }     // x is a parameter to the function
+ :(x: int = init) = statement;      // same, { } is implicit
+
+// Omit declaration => local and immediate (aka 'let' in other languages)
+  (x: int = init)   { /*...*/ }     // x is a parameter to this
+  (x: int = init)   statement;      //  compound or single-statement
+
+// Omit parameters => ordinary block or statement
+                    { /*...*/ }     // ordinary compound statement
+                    statement;      // ordinary statement
+```
+
+Conversely, we can start with an ordinary block or statement, and successively build it up to make it more powerful:
+
+``` cpp title="Start with an ordinary block or statement, and successively add parts" hl_lines="1 5 9 13"
+// Ordinary block or statement
+                    { /*...*/ }     // ordinary compound statement
+                    statement;      // ordinary statement
+
+// Add parameters => more RAII locally-scoped variables
+  (x: int = init)   { /*...*/ }     // x is destroyed after this
+  (x: int = init)   statement;      //  compound or single-statement
+
+// Add declaration => treat the code as a callable object
+ :(x: int = init) = { /*...*/ }     // x is a parameter to the function
+ :(x: int = init) = statement;      // same, { } is implicit
+
+// Add name => full named function
+f:(x: int = init) = { /*...*/ }     // x is a parameter to the function
+f:(x: int = init) = statement;      // same, { } is implicit
+
+```
+
+
+### <a id="template-parameters"></a> Template parameters
 
 A template parameter list is enclosed by `<` `>` angle brackets, and the parameters separated by commas. Each parameter is declared using the [same syntax as any type or object](declarations.md). If a parameter's **`:`** ***kind*** is not specified, the default is `: type`.
 
@@ -45,7 +105,7 @@ tuple: <Ts...: type> type
 ```
 
 
-## <a id="requires"></a> `#!cpp requires` constraints
+### <a id="requires"></a> `#!cpp requires` constraints
 
 A `#!cpp requires` ***condition*** constraint appears at the end of the ***kind*** of a templated declaration. If the condition evaluates to `#!cpp false`, that specialization of the template is ignored as if not declared.
 
@@ -61,7 +121,7 @@ print: <Args...: type>
 ```
 
 
-## Examples
+### Examples
 
 ``` cpp title="Consistent declarations — name : kind = statement" linenums="1" hl_lines="2 6 10 15 24 28 32 43 49 53"
 //  n is a namespace defined as the following scope
@@ -121,3 +181,102 @@ n: namespace
 ```
 
 > Note: `@enum` is a metafunction, which provides an easy way to opt into a group of defaults, constraints, and generated functions. For details, see [`@enum`](metafunctions.md#enum).
+
+
+## <a id="aliases"></a> Aliases
+
+Aliases are pronounced **"synonym for**, and written using the same **name `:` kind `=` value** [declaration syntax](../cpp2/declarations.md) as everything in Cpp2:
+
+- **name** is declared to be a synonym for **value**.
+
+- **kind** can be any of the kinds: `namespace`, `type`, a function signature, or a type.
+
+- **`==`**, pronounced **"defined as a synonym for"**, always precedes the value. The `==` syntax stresses that during compilation every use of the name could be equivalently replaced with the value.
+
+- **value** is the expression that the **name** is a synonym for.
+
+
+### <a id="namespace-aliases"></a> Namespace aliases
+
+A namespace alias is written the same way as a [namespace](namespaces.md), but using `==` and with the name of another namespace as its value. For example:
+
+``` cpp title="Namespace aliases" hl_lines="1 2 4 5 8 12 16"
+//  'chr' is a namespace defined as a synonym for 'std::chrono'
+chr    : namespace == std::chrono;
+
+//  'chrlit' is a namespace defined as a synonym for 'std::chrono_literals'
+chrlit : namespace == std::chrono_literals;
+
+main: () = {
+    using namespace chrlit;
+
+    //  The next two lines are equivalent
+    std::cout << "1s is (std::chrono::nanoseconds(1s).count())$ns\n";
+    std::cout << "1s is (chr::nanoseconds(1s).count())$ns\n";
+}
+//  Prints:
+//      1s is 1000000000ns
+//      1s is 1000000000ns
+```
+
+
+### <a id="type-aliases"></a> Type aliases
+
+A namespace alias is written the same way as a [type](types.md), but using `==` and with the name of another type as its value. For example:
+
+``` cpp title="Type aliases" hl_lines="1 2 7 10"
+//  'imap<T>' is a type defined as a synonym for 'std::map<i32, T>'
+imap : <T> type == std::map<i32, T>;
+
+main: () = {
+    //  The next two lines declare two objects with identical type
+    map1: std::map<i32, std::string> = ();
+    map2: imap<std::string> = ();
+
+    //  Assertion they are the same type, using the same_as concept
+    assert( std::same_as< decltype(map1), decltype(map2) > );
+}
+```
+
+
+### <a id="function-aliases"></a> Function aliases
+
+A function alias is written the same way as a [function](functions.md), but using `==` and with a side-effect-free body as its value; the body must always return the same value for the same input arguments. For example:
+
+``` cpp title="Function aliases" hl_lines="1 2 6 9 12 15"
+//  'square' is a function defined as a synonym for the value of 'i * i'
+square: (i: i32) -> _ == i * i;
+
+main: () = {
+    //  It can be used at compile time, with compile time values
+    ints: std::array<i32, square(4)> = ();
+
+    //  Assertion that the size is the square of 4
+    assert( ints.size() == 16 );
+
+    //  And if can be used at run time, with run time values
+    std::cout << "the square of 4 is (square(4))$\n";
+}
+//  Prints:
+//      the square of 4 is 16
+```
+
+> Note: A function alias is compiled to a Cpp1 `#!cpp constexpr` function.
+
+
+### <a id="object-aliases"></a> Object aliases
+
+An object alias is written the same way as an [object](objects.md), but using `==` and with a side-effect-free value. For example:
+
+``` cpp title="Function aliases" hl_lines="1 2 5 6"
+//  'BufferSize' is an object defined as a synonym for the value 1'000'000
+BufferSize: i32 == 1'000'000;
+
+main: () = {
+    buf: std::array<std::byte, BufferSize> = ();
+    assert( buf.size() == BufferSize );
+}
+```
+
+> Note: An object alias is compiled to a Cpp1 `#!cpp constexpr` object.
+