Update grammar and docs for optional trailing commas in lists

Author: hsutter

docs/cpp2/common.md

@@ -55,6 +55,56 @@ The usual `#!cpp // line comments` and `#!cpp /* stream comments */` are support
 ```
 
 
+## <a id="lists"></a> Lists and commas
+
+All lists use `,` commas between list items, and may be enclosed by
+
+- `(` `)` parentheses, for most lists
+
+- `[` `]` brackets, for calling the subscript operator
+
+- `<` `>` angle brackets, for template parameter/argument lists
+
+For example:
+
+``` cpp title="Lists, using optional trailing commas just because we can" hl_lines="1 4 6 7"
+print: <T,U> (t: T, u: U) = std::cout << t << u << "\n";
+
+main: () = {
+    array: std::array = ('A', 'B', 'C');
+
+    for (0, 1, 2) do (e) {
+        print( e, array[e] );
+    }
+    //  Prints:
+    //      0A
+    //      1B
+    //      2C
+}
+```
+
+
+An extra comma at the end of the list, before the closing `)` or `>`, is always allowed but ignored if present (for details, see [Design note: Commas](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Commas)).
+
+For example:
+
+``` cpp title="Lists, using optional trailing commas just because we can" hl_lines="1 4 6 7"
+print: <T,U,> (t: T, u: U,) = std::cout << t << u << "\n";
+
+main: () = {
+    array: std::array = ('A', 'B', 'C',);
+
+    for (0, 1, 2,) do (e) {
+        print( e, array[e,], );
+    }
+    //  Prints:
+    //      0A
+    //      1B
+    //      2C
+}
+```
+
+
 ## <a id="keywords"></a> Reserved keywords
 
 Cpp2 has very few globally reserved keywords; nearly all keywords are contextual, where they have their special meaning when they appear in a particular place in the grammar. For example:
@@ -110,7 +160,7 @@ p: const * * const i32;
 
 Cpp2 supports the same `#!cpp 'c'`haracter, `#!cpp "string"`, binary, integer, and floating point literals as Cpp1, including most Unicode encoding prefixes and raw string literals.
 
-Cpp2 supports using Cpp1 user-defined literals for compatibility, to support seamlessly using existing libraries. However, because Cpp2 has unified function call syntax (UFCS), the preferred way to author the equivalent in Cpp2 is to just write a function or type name as a `.` call suffix. For example:
+Cpp2 supports using Cpp1 user-defined literals for compatibility, to support seamlessly using existing libraries. However, because Cpp2 has [unified function call syntax (UFCS)](expressions.md#ufcs), the preferred way to author the equivalent in Cpp2 is to just write a function or type name as a `.` call suffix. For example:
 
 - You can create a `u8` value by writing either `u8(123)` or **`123.u8()`**. [^u8using]
 

docs/cpp2/declarations.md

@@ -85,7 +85,7 @@ 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`.
+A template parameter list is a [list](common.md#lists) 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`.
 
 For example:
 

docs/cpp2/expressions.md

@@ -3,6 +3,8 @@
 
 ## <a id="ufcs"></a> Calling functions: `f(x)` syntax, and `x.f()` UFCS syntax
 
+A function argument list is a [list](common.md#lists) of arguments enclosed by `(` `)` parentheses.
+
 A function call like `f(x)` is a normal function call that will call non-member functions only, as usual in C++.
 
 A function call like `x.f()` is a unified function call syntax (aka UFCS) call. It will call a member function if one is available, and otherwise will call `f(x)`. Having UFCS is important for generic code that may want to call a member or a non-member function, whichever is available. It's also important to enable fluid programming styles and natural IDE autocompletion support.

docs/cpp2/functions.md

@@ -14,7 +14,7 @@ func: ( /* no parameters */ ) = { /* empty body */ }
 
 ## <a id="parameters"></a> Parameters
 
-The parameter list is enclosed by `(` `)` parentheses and the parameters are separated by commas. Each parameter is declared using the [same unified syntax](declarations.md) as used for all declarations. For example:
+The parameter list is a [list](common.md#lists) enclosed by `(` `)` parentheses. Each parameter is declared using the [same unified syntax](declarations.md) as used for all declarations. For example:
 
 ``` cpp title="Declaring parameters" hl_lines="2-4"
 func: (

include/cpp2util.h

@@ -1782,8 +1782,6 @@ constexpr auto unsafe_narrow( X&& x ) noexcept -> decltype(auto)
 }
 
 
-namespace impl {
-
 //-----------------------------------------------------------------------
 //
 //  args: see main() arguments as a container of string_views
@@ -1845,8 +1843,6 @@ inline auto make_args(int argc, char** argv) -> args_t
     return args_t{argc, argv};
 }
 
-} // impl
-
 
 //-----------------------------------------------------------------------
 //

regression-tests/pure2-trailing-commas.cpp2

@@ -8,7 +8,7 @@ doubler: (a: int,) -> (i : int,) = {
 
 vals: @struct type = { i: int; }
 
-main: () -> int = {
+main: () = {
     (copy a := 42,) while false { a++; }
     _ = g(1, 2,);
 

regression-tests/test-results/mixed-fixed-type-aliases.cpp

@@ -48,7 +48,7 @@ auto test(auto const& x) -> void{
 
 #line 19 "mixed-fixed-type-aliases.cpp2"
 [[nodiscard]] auto main(int const argc_, char** argv_) -> int{
-    auto const args = cpp2::impl::make_args(argc_, argv_); 
+    auto const args = cpp2::make_args(argc_, argv_); 
 #line 20 "mixed-fixed-type-aliases.cpp2"
     my::u16 y {42}; 
     test(std::move(y));

regression-tests/test-results/pure2-bugfix-for-discard-precedence.cpp

@@ -45,7 +45,7 @@ auto main(int const argc_, char** argv_) -> int;
 
 #line 7 "pure2-bugfix-for-discard-precedence.cpp2"
 auto main(int const argc_, char** argv_) -> int{
-  auto const args = cpp2::impl::make_args(argc_, argv_); 
+  auto const args = cpp2::make_args(argc_, argv_); 
 #line 8 "pure2-bugfix-for-discard-precedence.cpp2"
   quantity x {1729}; 
   static_cast<void>(x + x);// Not `(void) x + x`; would attempt to add a `void` to `x`.

regression-tests/test-results/pure2-for-loop-range-with-lambda.cpp

@@ -24,7 +24,7 @@ auto main(int const argc_, char** argv_) -> int;
 
 #line 3 "pure2-for-loop-range-with-lambda.cpp2"
 auto main(int const argc_, char** argv_) -> int{
-   auto const args = cpp2::impl::make_args(argc_, argv_); 
+   auto const args = cpp2::make_args(argc_, argv_); 
 #line 4 "pure2-for-loop-range-with-lambda.cpp2"
    std::array const ints {1, 2, 3, 4, 5}; 
    // OK

regression-tests/test-results/pure2-initialization-safety-with-else-if.cpp

@@ -18,7 +18,7 @@ auto main(int const argc_, char** argv_) -> int;
 
 #line 1 "pure2-initialization-safety-with-else-if.cpp2"
 auto main(int const argc_, char** argv_) -> int{
-    auto const args = cpp2::impl::make_args(argc_, argv_); 
+    auto const args = cpp2::make_args(argc_, argv_); 
 #line 2 "pure2-initialization-safety-with-else-if.cpp2"
     cpp2::impl::deferred_init<int*> p;