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; 
 

regression-tests/test-results/pure2-last-use.cpp

@@ -1562,7 +1562,7 @@ auto x{cpp2_new<int>(0)};
 
 #line 1043 "pure2-last-use.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 1044 "pure2-last-use.cpp2"
   issue_683(args);
   issue_847_2(std::vector<std::unique_ptr<int>>());

regression-tests/test-results/pure2-main-args.cpp

@@ -18,7 +18,7 @@ auto main(int const argc_, char** argv_) -> int;
 
 #line 1 "pure2-main-args.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_); 
     // Explicit call to string is necessary
     // std::filesystem::path is base on and implicitly convertible to
     // - std::string (on POSIX systems)

regression-tests/test-results/pure2-statement-scope-parameters.cpp

@@ -22,7 +22,7 @@ auto main(int const argc_, char** argv_) -> int;
 
 #line 2 "pure2-statement-scope-parameters.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 3 "pure2-statement-scope-parameters.cpp2"
     auto local_int {42}; 
 {

regression-tests/test-results/pure2-trailing-commas.cpp

@@ -28,7 +28,7 @@ using doubler_ret = int;
 #line 9 "pure2-trailing-commas.cpp2"
 class vals {public: int i; };
 
-[[nodiscard]] auto main() -> int;
+auto main() -> int;
 
 //=== Cpp2 function definitions =================================================
 
@@ -46,7 +46,7 @@ template<typename T, typename U> [[nodiscard]] auto g(T const& a, U const& b) ->
 return std::move(i.value()); }
 
 #line 11 "pure2-trailing-commas.cpp2"
-[[nodiscard]] auto main() -> int{
+auto main() -> int{
 {
 auto a{42};
 #line 12 "pure2-trailing-commas.cpp2"

regression-tests/test-results/version

@@ -1,5 +1,5 @@
 
-cppfront compiler v0.3.0   Build 9314:1742
+cppfront compiler v0.3.0   Build 9316:1733
 Copyright(c) Herb Sutter   All rights reserved
 
 SPDX-License-Identifier: CC-BY-NC-ND-4.0

source/build.info

@@ -1 +1 @@
-"9314:1742"
+"9316:1739"

source/parse.h

@@ -5630,8 +5630,7 @@ class parser
     //G     inspect-expression
     //G     id-expression
     //G     literal
-    //G     '(' expression-list ')'
-    //GT     '{' expression-list '}'
+    //G     '(' expression-list ','? ')'
     //G     unnamed-declaration
     //G
     auto primary_expression()
@@ -5667,7 +5666,7 @@ class parser
             auto close = close_paren_type(open_paren->type());
             auto close_text = [&] () -> std::string { if (close == lexeme::RightParen) { return ")"; } return "}"; }();
             next();
-            auto expr_list = expression_list(open_paren, inside_initializer);
+            auto expr_list = expression_list(open_paren, lexeme::RightParen, inside_initializer);
             if (!expr_list) {
                 error("unexpected text - ( is not followed by an expression-list");
                 next();
@@ -5760,8 +5759,8 @@ class parser
     //G postfix-expression:
     //G     primary-expression
     //G     postfix-expression postfix-operator     [Note: without whitespace before the operator]
-    //G     postfix-expression '[' expression-list? ']'
-    //G     postfix-expression '(' expression-list? ')'
+    //G     postfix-expression '[' expression-list? ','? ']'
+    //G     postfix-expression '(' expression-list? ','? ')'
     //G     postfix-expression '.' id-expression
     //G
     auto postfix_expression()
@@ -5839,7 +5838,7 @@ class parser
 
             if (term.op->type() == lexeme::LeftBracket)
             {
-                term.expr_list = expression_list(term.op);
+                term.expr_list = expression_list(term.op, lexeme::RightBracket);
                 if (!term.expr_list)
                 {
                     error("[ is not followed by a valid expression list");
@@ -5860,7 +5859,7 @@ class parser
                 //  If not, then this wasn't a call expression so backtrack to
                 //  the '(' which will be part of the next grammar production
 
-                term.expr_list = expression_list(term.op);
+                term.expr_list = expression_list(term.op, lexeme::RightParen);
                 if (
                     term.expr_list
                     && curr().type() == lexeme::RightParen
@@ -6326,7 +6325,8 @@ class parser
     //G
     auto expression_list(
         token const* open_paren,
-        bool inside_initializer = false
+        lexeme       closer,
+        bool         inside_initializer = false
     )
         -> std::unique_ptr<expression_list_node>
     {
@@ -6362,7 +6362,7 @@ class parser
             next();
 
             //  Allow a trailing comma in the list
-            if (curr().type() == lexeme::RightParen) {
+            if (curr().type() == closer) {
                 break;
             }
 
@@ -7778,7 +7778,7 @@ class parser
 
 
     //G parameter-declaration-list:
-    //G     '(' parameter-declaration-seq? ')'
+    //G     '(' parameter-declaration-seq? ','? ')'
     //G
     //G parameter-declaration-seq:
     //G     parameter-declaration

source/to_cpp1.h

@@ -4813,7 +4813,7 @@ class cppfront
                 n.parameters->position()
             );
             current_functions.back().prolog.statements.push_back(
-                "auto const args = cpp2::impl::make_args(argc_, argv_); "
+                "auto const args = cpp2::make_args(argc_, argv_); "
             );
         }
         else {