Catch up feature documentation and C++26 new headers

Add documentation for:

- tersest syntax (e.g., `:(a,b) a+b;`)

- `unevaluated` contract group

- for `operator++` and `operator--`, that writing the single operator in Cpp2 generates both forms when lowering to Cpp1

- `-cwd` and `-quiet` command line options

Remove documentation for:

- `-add-source-info` switch which was removed

Add support for new C++26 headers approved in St Louis:

- `inplace_vector`

Author: hsutter

docs/cpp2/common.md

@@ -220,7 +220,7 @@ Postfix notation lets the code read fluidly left-to-right, in the same order in
 
 > Note: The `...` pack expansion syntax is also supported. The above `...` and `..=` are the Cpp2 range operators, which overlap in syntax.
 
-> Note: Because `++` and `--` always have in-place update semantics, we never need to remember "use prefix `++`/`--` unless you need a copy of the old value." If you do need a copy of the old value, just take the copy before calling `++`/`--`.
+> Note: Because `++` and `--` always have in-place update semantics, we never need to remember "use prefix `++`/`--` unless you need a copy of the old value." If you do need a copy of the old value, just take the copy before calling `++`/`--`. When you write a type that overloads `operator++` or `operator--`, cppfront generates both Cpp1 overloads (in-place-update and copy-old-value) for that function to support natural use of the type from Cpp1 code.
 
 
 ### <a id="binary-operators"></a> Binary operators

docs/cpp2/contracts.md

@@ -15,11 +15,13 @@ Notes:
 
 - Optionally, `condition` may be followed by `, "message"`, a message to include if a violation occurs. For example, `pre(condition, "message")`.
 
-- Optionally, a `<group, pred1, pred2>` can be written inside `<` `>` angle brackets immediately before the `(`, to designate that this test is part of the [contract group](#groups) named `group` and (also optionally) [contract predicates](#predicates) `pred1` and `pred2`. If a violation occurs, `Group.report_violation()` will be called. For example, `pre<group>(condition)`. If no contract group is specified, the contract defaults to being part of the `cpp2_default` group.
+- Optionally, a `<group, pred1, pred2>` can be written inside `<` `>` angle brackets immediately before the `(`, to designate that this test is part of the [contract group](#groups) named `group` and (also optionally) [contract predicates](#predicates) `pred1` and `pred2`. If a violation occurs, `Group.report_violation()` will be called. For example, `pre<group>(condition)`. If no contract group is specified, the contract defaults to being part of the `default` group (spelled `cpp2_default` when used from Cpp1 code).
 
 The order of evaluation is:
 
-- First, predicates are evaluated in order. If any predicte evaluates to `#!cpp false`, stop.
+- First, if the contract group is `unevaluated` then the contract is ignored; `condition` is never evaluated. This special group is designates conditions intended for use by static analyzers only, and the only requirement is that the condition be grammatically valid.
+
+- Next, predicates are evaluated in order. If any predicate evaluates to `#!cpp false`, stop.
 
 - Next, `group.is_active()` is evaluated. If that evaluates to `#!cpp false`, stop.
 

docs/cpp2/functions.md

@@ -78,9 +78,13 @@ wrap_f: (
 
 A function can return either of the following. The default is `#!cpp -> void`.
 
-(1) **`#!cpp -> X`** to return a single unnamed value of type `X`, which can be  `#!cpp void` to signify the function has no return value. If `X` is not `#!cpp void`, the function body must have a `#!cpp return /*value*/;` statement that returns a value of type `X` on every path that exits the function. For example:
+(1) **`#!cpp -> X`** to return a single unnamed value of type `X`, which can be  `#!cpp void` to signify the function has no return value. If `X` is not `#!cpp void`, the function body must have a `#!cpp return /*value*/;` statement that returns a value of type `X` on every path that exits the function.
 
-``` cpp title="Functions with an unnamed return value" hl_lines="2 4 7 9 12 14"
+To deduce the return type, write `-> _`. A function whose body returns a single expression `expr` can deduce the return type and omit writing `-> _ = { return /*expr*/ ; }`.
+
+For example:
+
+``` cpp title="Functions with an unnamed return value" hl_lines="2 4 7 9 12 14 15 18 20 22"
 //  A function returning no value (void)
 increment_in_place: (inout a: i32) -> void = { a++; }
 //  Or, using syntactic defaults, the following has identical meaning:
@@ -93,8 +97,16 @@ add_one: (a: i32) -> i32 = a+1;
 
 //  A generic function returning a single value of deduced type
 add: <T: type, U: type> (a:T, b:U) -> decltype(a+b) = { return a+b; }
-//  Or, using syntactic defaults, the following has identical meaning:
+//  Or, using syntactic defaults, the following have identical meaning:
 add: (a, b) -> _ = a+b;
+add: (a, b) a+b;
+
+//  A generic function expression returning a single value of deduced type
+vec.std::ranges::sort( :(x:_, y:_) -> _ = { return y<x; } );
+//  Or, using syntactic defaults, the following has identical meaning:
+vec.std::ranges::sort( :(x,y) y<x );
+//  Both are identical to this, which uses the most verbose possible syntax:
+vec.std::ranges::sort( :<T:type, U:type> (x:T, y:U) -> _ = { return y<x; } );
 ```
 
 (2) **`#!cpp -> ( /* parameter list */ )`** to return a list of named return parameters using the same [parameters](#parameters) syntax, but where the only passing styles are `out` (the default, which moves where possible) or `forward`. The function body must [initialize](objects.md#init) the value of each return-parameter `ret` in its body the same way as any other local variable. An explicit return statement is written just `#!cpp return;` and returns the named values; the function has an implicit `#!cpp return;` at the end. If only a single return parameter is in the list, it is emitted in the lowered Cpp1 code the same way as (1) above, so its name is only available inside the function body.

docs/cppfront/options.md

@@ -18,13 +18,13 @@ For convenience, you can shorten the name to any unique prefix not shared with a
 - `-import-std` and `-include-std` can be shortened to `-im` and `-in` respectively, but not `-i` which would be ambiguous with each other.
 
 
-# Basic command line options
+## Basic command line options
 
-## `-help`, `-h`, `-?`
+### `-help`, `-h`, `-?`
 
 Prints an abbreviated version of this documentation page.
 
-## `-import-std`, `-im`
+### `-import-std`, `-im`
 
 Makes the entire C++ standard library (namespace `std::`) available via a module `import std.compat;` (which implies `import std;`).
 
@@ -34,89 +34,89 @@ This option is implicitly set if `-pure-cpp2` is selected.
 
 This option is ignored if `-include-std` is selected. If your Cpp1 compiler does not yet support standard library modules `std` and `std.compat`, this option automatically uses  `-include-std` instead as a fallback.
 
-## `-include-std`, `-in`
+### `-include-std`, `-in`
 
 Makes the entire C++ standard library (namespace `std::`) available via an '#include" of every standard header.
 
 This option should always work with all standard headers, including draft-standard C++26 headers that are not yet in a published standard, because it tracks new headers as they are added and uses feature tests to not include headers that are not yet available on your Cpp1 implementation.
 
-## `-pure-cpp2`, `-p`
+### `-pure-cpp2`, `-p`
 
 Allow Cpp2 syntax only.
 
 This option also sets `-import-std`.
 
-## `-version`, `-vers`
+### `-version`, `-vers`
 
 Print version, build, copyright, and license information.
 
 
-# Additional dynamic safety checks and contract information
+## Additional dynamic safety checks and contract information
 
-## `-add-source-info`, `-a`
-
-Enable `source_location` information for contract checks. If this is supported by your Cpp1 compiler, the default contract failure messages will include exact file/line/function information. For example, if the default `Bounds` violation handler would print this without `-a`:
-
-    Bounds safety violation: out of bounds access attempt detected - attempted access at index 2, [min,max] range is [0,1]
-
-then it would print something like this with `-a` (the exact text will vary with the Cpp1 standard library vendor's `source_location` implementation):
-
-    demo.cpp2(4) int __cdecl main(void): Bounds safety violation: out of bounds access attempt detected - attempted access at index 2, [min,max] range is [0,1]
-
-## `-no-comparison-checks`, `-no-c`
+### `-no-comparison-checks`, `-no-c`
 
 Disable mixed-sign comparison safety checks. If not disabled, mixed-sign comparisons are diagnosed by default.
 
-## `-no-null-checks`, `-no-n`
+### `-no-null-checks`, `-no-n`
 
 Disable null safety checks. If not disabled, null dereference checks are performed by default.
 
-## `-no-subscript-checks`, `-no-s`
+### `-no-subscript-checks`, `-no-s`
 
 Disable subscript bounds safety checks. If not disabled, subscript bounds safety checks are performed by default.
 
 
-# Support for constrained target environments
+## Support for constrained target environments
 
-## `-fno-exceptions`, `-fno-e`
+### `-fno-exceptions`, `-fno-e`
 
 Disable C++ exception handling. This should be used only if you must run in an environment that bans C++ exception handling, and so you are already using a similar command line option for your Cpp1 compiler.
 
 If this option is selected, a failed `as` for `std::variant` will assert.
 
-## `-fno-rtti`, `-fno-r`
+### `-fno-rtti`, `-fno-r`
 
 Disable C++ run-time type information (RTTI). This should be used only if you must run in an environment that bans C++ RTTI, and so you are already using a similar command line option for your Cpp1 compiler.
 
 If this option is selected, trying to using `as` for `*` (raw pointers) or `std::any` will assert.
 
 
-# Other options
+## Cpp1 file content options
 
-## `-clean-cpp1`, `-c`
+### `-clean-cpp1`, `-cl`
 
 Emit clean `.cpp` files without `#line` directives and other extra information that cppfront normally emits in the `.cpp` to light up C++ tools (e.g., to let IDEs integrate cppfront error message output, debuggers step to the right lines in Cpp2 source code, and so forth). In normal use, you won't need `-c`.
 
-## `-debug`, `-d`
+### `-emit-cppfront-info`, `-e`
 
-Emit compiler debug output. This is only useful when debugging cppfront itself.
+Emit cppfront version and build in the `.cpp` file.
 
-## `-emit-cppfront-info`, `-e`
+### `-line-paths`, `-l`
 
-Emit cppfront version and build in the `.cpp` file.
+Emit absolute paths in `#line` directives.
 
-## `-format-colon-errors`, `-fo`
+## Cppfront output options
 
-Emit cppfront diagnostics using `:line:col:` format for line and column numbers, if that is the format better recognized by your IDE, so that it will pick up cppfront messages and integrate them in its normal error message output location. If not set, by default cppfront diagnostics use `(line,col)` format.
+### `-cwd` _path_, `-cw` _path_
 
-## `-line-paths`, `-l`
+Changes the current working directory to 'path'. Can be useful in build scripts to control where generated Cpp1 files are places; see also `-output`.
 
-Emit absolute paths in `#line` directives.
+### `-debug`, `-d`
 
-## `-output` _filename_, `-o` _filename_
+Emit compiler debug output. This is only useful when debugging cppfront itself.
+
+### `-format-colon-errors`, `-fo`
+
+Emit cppfront diagnostics using `:line:col:` format for line and column numbers, if that is the format better recognized by your IDE, so that it will pick up cppfront messages and integrate them in its normal error message output location. If not set, by default cppfront diagnostics use `(line,col)` format.
+
+### `-output` _filename_, `-o` _filename_
 
 Output to 'filename' (can be 'stdout'). If not set, the default output filename for is the same as the input filename without the `2` (e.g., compiling `hello.cpp2` by default writes its output to `hello.cpp`, and `header.h2` to `header.h`).
 
-## `-verbose`, `-verb`
+### `-quiet`, `-q`
+
+Print no console output unless there are errors to report.
+
+### `-verbose`, `-verb`
 
 Print verbose statistics and `-debug` output.

include/cpp2util.h

@@ -153,6 +153,9 @@
             #include <hazard_pointer>
         #endif
         #include <initializer_list>
+        #ifdef __cpp_lib_inplace_vector
+            #include <inplace_vector>
+        #endif
         #include <iomanip>
         #include <ios>
         #include <iosfwd>

source/common.h

@@ -655,7 +655,7 @@ class cmdline_processor
     std::unordered_map<int, std::string> labels = {
         { 2, "Additional dynamic safety checks and contract information" },
         { 4, "Support for constrained target environments" },
-        { 8, "Cpp1 file emission options" },
+        { 8, "Cpp1 file content options" },
         { 9, "Cppfront output options" }
     };
 

source/to_cpp1.h

@@ -149,7 +149,7 @@ static cmdline_processor::register_flag cmd_safe_comparisons(
 
 static auto flag_cpp1_filename = std::string{};
 static cmdline_processor::register_flag cmd_cpp1_filename(
-    8,
+    9,
     "output filename",
     "Output to 'filename' (can be 'stdout') - default is *.cpp/*.h",
     nullptr,