Add syntax highlighting for inline code blocks using #!cpp shebangs

Note: I deliberately did not add shebangs for:
- `inline code` that wouldn't benefit from them (e.g., had nothing significant to highlight) so as to keep the Markdown more readable
- `inline code` that I didn't want to highlight, mainly Cpp2 code that used Cpp1 reserved keywords in a non-reserved way (mainly metafunctions like @enum and @union)

Author: hsutter

docs/cpp2/common.md

@@ -6,11 +6,14 @@ As always, `main` is the entry point of the program. For example:
 
 `main` can have either:
 
-- No parameters: `main: () /*etc.*/`
+- No parameters:   **`#!cpp main: () /*etc.*/`**
+
+- One parameter of implicit type named `args`:   **`#!cpp main: (args) /*etc.*/`**
+
+    - The type of `args` cannot be explicitly specified. It is always `cpp2::args_t`, which behaves similarly to a `#!cpp const std::array<std::string_view>`.
 
-- One parameter of implicit type named `args`: `main: (args) /*etc.*/`
-    - The type of `args` cannot be explicitly specified. It is always `cpp2::args_t`, which behaves similarly to a `const std::array<std::string_view>`.
     - Using `args` performs zero heap allocations. Every `string_view` is directly bound to the string storage provided by host environment.
+
     - `args.argc` and `args.argv` additionally provide access to the raw C/C++ `main` parameters.
 
 ``` cpp title="main with (args)" hl_lines="5 9"
@@ -29,16 +32,16 @@ main: (args) -> int
 
 `main` can return:
 
-- `void`, the default return value for functions. In this case, the compiled Cpp1 code returns an `int` (as required by the standard) with value `0`.
+- `#!cpp void`, the default return value for functions. No `#!cpp return` statement is allowed in the body. In this case, the compiled Cpp1 code behaves as if `main` returned `#!cpp int`.
 
-- `int`. If the body has no `return` statement, the default is to `return 0;` at the end of the function body.
+- `#!cpp int`. If the body has no `#!cpp return` statement, the default is to `#!cpp return 0;` at the end of the function body.
 
 - Some other type that your Cpp1 compiler(s) supports as a nonstandard extension.
 
 
 ## Comments
 
-The usual `// line comments` and `/* stream comments */` are supported. For example:
+The usual `#!cpp // line comments` and `#!cpp /* stream comments */` are supported. For example:
 
 ``` cpp title="Writing comments"
 //  A line comment: After //, the entire
@@ -82,21 +85,21 @@ Cpp2 supports the same fundamental types as today's Cpp1, but additionally provi
 
 | Variable-width types <br> (Cpp2-compatible single-word names) | Synonym for (these multi-word<br> names are not allowed in Cpp2) |
 |---|---|
-| `ushort`      | `unsigned short`       |
-| `uint`        | `unsigned int`         |
-| `ulong`       | `unsigned long`        |
-| `longlong`    | `long long`            |
-| `ulonglong`   | `unsigned long long`   |
-| `longdouble`  | `long double`          |
+| `ushort`      | `#!cpp unsigned short`       |
+| `uint`        | `#!cpp unsigned int`         |
+| `ulong`       | `#!cpp unsigned long`        |
+| `longlong`    | `#!cpp long long`            |
+| `ulonglong`   | `#!cpp unsigned long long`   |
+| `longdouble`  | `#!cpp long double`          |
 
 | For compatibility/interop only,<br> so deliberately ugly names | Synonym for | Notes |
 |---|---|---|
-| `_schar`     | `signed char`   | Normally, prefer `i8` instead |
-| `_uchar`     | `unsigned char` | Normally, prefer `u8` instead |
+| `_schar`     | `#!cpp signed char`   | Normally, prefer `i8` instead |
+| `_uchar`     | `#!cpp unsigned char` | Normally, prefer `u8` instead |
 
 ## Type qualifiers
 
-Types can be qualified with `const` and `*`. Types are written left-to-right, so a qualifier always applies to what immediately follows it. For example, to declare a `const` pointer to a non-`const` pointer to a `const i32` object, write:
+Types can be qualified with `#!cpp const` and `#!cpp *`. Types are written left-to-right, so a qualifier always applies to what immediately follows it. For example, to declare a `#!cpp const` pointer to a non-`#!cpp const` pointer to a `#!cpp const i32` object, write:
 
 ``` cpp title="Using type qualifiers"
 //  A const pointer to a non-const pointer to a const i32 object
@@ -105,13 +108,13 @@ p: const * * const i32;
 
 ## Literals
 
-Cpp2 supports the same `'c'`haracter, `"string"`, binary, integer, and floating point literals as Cpp1, including most Unicode encoding prefixes and raw string literals.
+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:
 
 - You can create a `u8` value by writing either `u8(123)` or **`123.u8()`**. [^u8using]
 
-- You can write a 'constexpr' function like `nm: (value: i64) -> my_nanometer_type == { /*...*/ }` that takes an integer and returns a value of a strongly typed "nanometer" type, and then create a `nm` value by writing either `nm(123)` or **`123.nm()`**.
+- You can write a 'constexpr' function like `#!cpp nm: (value: i64) -> my_nanometer_type == { /*...*/ }` that takes an integer and returns a value of a strongly typed "nanometer" type, and then create a `nm` value by writing either `nm(123)` or **`123.nm()`**.
 
 Both **`123.nm()`** and **`123.u8()`** are very similar to user-defined literal syntax, and more general.
 
@@ -132,8 +135,8 @@ if !vec.empty() {
 | Unary operator | Cpp2 example | Cpp1 equivalent |
 |---|---|---|
 | `!` | `!vec.empty()` | `!vec.empty()` |
-| `+` | `+100` | `+100` |
-| `-` | `-100` | `-100` |
+| `+` | `#!cpp +100` | `#!cpp +100` |
+| `-` | `#!cpp -100` | `#!cpp -100` |
 
 The operators `.`, `*`, `&`, `~`, `++`, `--`, `()`, `[]`, and `$` are postfix. For example:
 
@@ -152,25 +155,25 @@ Postfix notation lets the code read fluidly left-to-right, in the same order in
 
 | Unary operator | Cpp2 example | Cpp1 equivalent |
 |---|---|---|
-| `.` | `obj.f()` | `obj.f()` |
-| `*` | `pobj*.f()` | `(*pobj).f()` or `pobj->f()` |
-| `&` | `obj&` | `&obj` |
-| `~` | `val~` | `~val` |
-| `++` | `iter++` | `++iter` |
-| `--` | `iter--` | `--iter` |
-| `(` `)` | `f( 1, 2, 3)` | `f( 1, 2, 3)` |
-| `[` `]` | `vec[123]` | `vec[123]` |
-| `$` | `val$` | (reflection — no C++23 equivalent) |
+| `#!cpp .` | `#!cpp obj.f()` | `#!cpp obj.f()` |
+| `#!cpp *` | `#!cpp pobj*.f()` | `#!cpp (*pobj).f()` or `#!cpp pobj->f()` |
+| `#!cpp &` | `#!cpp obj&` | `#!cpp &obj` |
+| `#!cpp ~` | `#!cpp val~` | `#!cpp ~val` |
+| `#!cpp ++` | `#!cpp iter++` | `#!cpp ++iter` |
+| `#!cpp --` | `#!cpp iter--` | `#!cpp --iter` |
+| `(` `)` | `#!cpp f( 1, 2, 3)` | `#!cpp f( 1, 2, 3)` |
+| `[` `]` | `#!cpp vec[123]` | `#!cpp vec[123]` |
+| `$` | `val$` | _reflection — no Cpp1 equivalent yet_ |
 
 > 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 `++`/`--`.
 
 Unary suffix operators must not be preceded by whitespace. When `*`, `&`, and `~` are used as binary operators they must be preceded by whitespace. For example:
 
 | Unary postfix operators that<br>are also binary operators | Cpp2 example | Cpp1 equivalent |
 |---|---|---|
-| `*` | `pobj* * 42` | `(*pobj)*42` |
-| `&` | `obj& & mask` <p> (note: allowed in unsafe code only) | `&obj & mask` |
-| `~` | `~val ~ bitcomplement` | `val~ ~ bitcomplement` |
+| `#!cpp *` | `#!cpp pobj* * 42` | `#!cpp (*pobj)*42` |
+| `#!cpp &` | `#!cpp obj& & mask` <p> (note: allowed in unsafe code only) | `#!cpp &obj & mask` |
+| `#!cpp ~` | `#!cpp ~val ~ bitcomplement` | `#!cpp val~ ~ bitcomplement` |
 
 For more details, see [Design note: Postfix unary operators vs binary operators](https://github.com/hsutter/cppfront/wiki/Design-note%3A-Postfix-unary-operators-vs-binary-operators).
 

docs/cpp2/declarations.md

@@ -8,9 +8,11 @@ All Cpp2 declarations are written as **"_name_ `:` _kind_ `=` _statement_"**.
 
 - The `=` is pronounced **"defined as."**
 
-- The _statement_ is typically an expression statement (e.g., `a + b();`) or a compound statement (e.g., `{ /*...*/ return c(d) / e; }`).
+- The _statement_ is typically an expression statement (e.g., `#!cpp a + b();`) or a compound statement (e.g., `#!cpp { /*...*/ return c(d) / e; }`).
 
-- Various parts of the syntax allow a `_` "don't care" wildcard or can be omitted entirely to accept a default (e.g., `x: int = 0;` can be equivalently written `x: _ = 0;` or `x := 0;` both of which deduce the type).
+- Various parts of the syntax allow a `_` "don't care" wildcard or can be omitted entirely to accept a default (e.g., `#!cpp x: int = 0;` can be equivalently written `#!cpp x: _ = 0;` or `#!cpp x := 0;` both of which deduce the type).
+
+> Note: 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 `=`.
 
 
 ## Examples

docs/cpp2/expressions.md

@@ -40,7 +40,7 @@ For details, see [Design note: Explicit discard](https://github.com/hsutter/cppf
 
 ## `is` — safe type/value queries
 
-An `x is C` expression allows safe type and value queries, and evaluates to `true` if `x` matches constraint `C`. It supports both static and dynamic queries, including customization, with support for standard library dynamic types like `std::variant`, `std::optional`, `std::expected`, and `std::any` provided out of the box.
+An `x is C` expression allows safe type and value queries, and evaluates to `#!cpp true` if `x` matches constraint `C`. It supports both static and dynamic queries, including customization, with support for standard library dynamic types like `std::variant`, `std::optional`, `std::expected`, and `std::any` provided out of the box.
 
 There are two kinds of `is`:
 
@@ -57,8 +57,8 @@ There are two kinds of `is`:
 
 | Value constraint kind | Example |
 |---|---|
-| Value | `x is 0` |
-| Value predicate | `x is (in(10, 20))` |
+| Value | `#!cpp x is 0` |
+| Value predicate | `#!cpp x is (in(10, 20))` |
 
 `is` is useful throughout the language, including in `inspect` pattern matching alternatives. `is` is extensible, and works out of the box with `std::variant`, `std::optional`, `std::expected`, and `std::any`. For examples, see:
 
@@ -78,11 +78,13 @@ Here are some `is` queries with their Cpp1 equivalents. In this table, uppercase
 |---|---|
 | `X is Y && Y is X` | `std::is_same_v<X,Y>` |
 | `D is B` | `std::is_base_of<B,D>` |
-| `pb is *D` | `dynamic_cast<D*>(pb) != nullptr` |
+| `#!cpp pb is *D` | `#!cpp dynamic_cast<D*>(pb) != nullptr` |
 | `v is T`  | `std::holds_alternative<T>(v)` |
-| `a is T`  | `a.type() == typeid(T)` |
+| `a is T`  | `#!cpp a.type() == typeid(T)` |
 | `o is T`  | `o.has_value()` |
 
+> Note: `is` unifies a variety of differently-named Cpp1 language and library queries under one syntax, and supports only the type-safe ones.
+
 
 ## `as` — safe casts and conversions
 
@@ -113,19 +115,24 @@ Here are some `as` casts with their Cpp1 equivalents. In this table, uppercase n
 | Some sample `as` casts | Cpp1 equivalent
 |---|---|
 | `x as Y` | `Y{x}` |
-| `pb as *D` | `dynamic_cast<D*>(pb)` |
+| `#!cpp pb as *D` | `#!cpp dynamic_cast<D*>(pb)` |
 | `v as T`  | `std::get<T>(v)` |
 | `a as T`  | `std::any_cast<T>(a)` |
 | `o as T`  | `o.value()` |
 
+> Note: `as` unifies a variety of differently-named Cpp1 language and library casts and conversions under one syntax, and supports only the type-safe ones.
+
 
 ## `inspect` — pattern matching
 
 An `inspect expr -> Type` expression allows pattern matching using `is`.
 
 - `expr` is evaluated once.
+
 - Each alternative spelled `is C` is evaluated in order as if called with `expr is C`.
-- If an alternative evaluates to `true`, then its `= alternative;` body is used as the value of the entire `inspect` expression, and the meaning is the same as if the entire `inspect` expression had been written as just `:Type = alternative;` — i.e., an unnamed object expression (aka 'temporary object') of type `Type` initialized with `alternative`.
+
+- If an alternative evaluates to `#!cpp true`, then its `#!cpp = alternative;` body is used as the value of the entire `inspect` expression, and the meaning is the same as if the entire `inspect` expression had been written as just `#!cpp :Type = alternative;` — i.e., an unnamed object expression (aka 'temporary object') of type `Type` initialized with `alternative`.
+
 - A catchall `is _` is required.
 
 For example:

docs/cpp2/functions.md

@@ -11,7 +11,7 @@ A function call like `f(x)` is a normal function call that will call non-member
 
 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.
 
-An operator notation call like `a + b` will call an overloaded operator function if one is available, as usual in C++.
+An operator notation call like `#!cpp a + b` will call an overloaded operator function if one is available, as usual in C++.
 
 For example:
 
@@ -56,7 +56,7 @@ There are six ways to pass parameters that cover all use cases:
 
 | Parameter kind | "Pass me an `x` I can ______" | Accepts arguments that are | Special semantics |
 |---|---|---|---|
-| `in` (default) | read from | anything | always `const`<p>automatically passes by value if cheaply copyable |
+| `in` (default) | read from | anything | always `#!cpp const`<p>automatically passes by value if cheaply copyable |
 | `copy` | take a copy of | anything | acts like a normal local variable initialized with the argument |
 | `inout` | read from and write to | lvalues | |
 | `out` | write to (including construct) | lvalues, including uninitialized lvalues | must `=` assign/construct before other uses |
@@ -65,7 +65,7 @@ There are six ways to pass parameters that cover all use cases:
 
 
 
-> Note: All parameters and other objects in Cpp2 are `const` by default, except for local variables. For details, see [Design note: `const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
+> Note: All parameters and other objects in Cpp2 are `#!cpp const` by default, except for local variables. For details, see [Design note: `#!cpp const` objects by default](https://github.com/hsutter/cppfront/wiki/Design-note%3A-const-objects-by-default).
 
 
 ## Return values
@@ -114,22 +114,22 @@ main: ()
 
 > Cpp2 imbues Cpp1 code with nondiscardable semantics, while staying fully compatible as usual:
 >
-> - A function written in Cpp2 syntax that returns something other than `void` is always compiled to Cpp1 with `[[nodiscard]]`.
+> - A function written in Cpp2 syntax that returns something other than `#!cpp void` is always compiled to Cpp1 with `[[nodiscard]]`.
 >
-> - A function call written in Cpp2 `x.f()` member call syntax always treats a non-`void` return type as not discardable, even if the function was written in Cpp1 syntax that did not write `[[nodiscard]]`.
+> - A function call written in Cpp2 `x.f()` member call syntax always treats a non-`#!cpp void` return type as not discardable, even if the function was written in Cpp1 syntax that did not write `[[nodiscard]]`.
 
 
 ## Control flow
 
-## `if`, `else` — Branches
+## `#!cpp if`, `#!cpp else` — Branches
 
 TODO
 
-## `for`, `while`, `do` — Loops
+## `#!cpp for`, `#!cpp while`, `#!cpp do` — Loops
 
 TODO
 
-Loops can be named using the usual **name `:`** name introduction syntax, and `break` and `continue` can refer to those names. For example:
+Loops can be named using the usual **name `:`** syntax that introduces all names, and `#!cpp break` and `#!cpp continue` can refer to those names. For example:
 
 ``` cpp title="Using named break and continue" hl_lines="6 10"
 outer: while i<M next i++ {      // loop named "outer"

docs/cpp2/metafunctions.md

@@ -95,9 +95,9 @@ skat_game: @enum<i16> type = {
 
 Consider `hearts`: It's a member object declaration, but it doesn't have a type (or a default value) which is normally illegal, but here it's okay because the `@enum<i16>` metafunction fills them in: It iterates over all the data members and gives each one the underlying type (here explicitly specified as `i16`, otherwise it would be computed as the smallest signed type that's big enough), and an initializer (by default one higher than the previous enumerator).
 
-Unlike C `enum`, this `@enum` is scoped and strongly typed (does not implicitly convert to the underlying type).
+Unlike C `#!cpp enum`, this `@enum` is scoped and strongly typed (does not implicitly convert to the underlying type).
 
-Unlike C++11 `enum class`, it's "just a `type`" which means it can naturally also have member functions and other things that a type can have:
+Unlike C++11 `#!cpp enum class`, it's "just a `type`" which means it can naturally also have member functions and other things that a type can have:
 
 ``` cpp title="An @enum type with a member function" hl_lines="1"
 janus: @enum type = {
@@ -167,7 +167,7 @@ main: () = {
 }
 ```
 
-Unlike C `union`, this `@union` is safe to use because it always ensures only the active type is accessed.
+Unlike C `#!cpp union`, this `@union` is safe to use because it always ensures only the active type is accessed.
 
 Unlike C++11 `std::variant`, this `@union` is easier to use because its alternatives are anonymous, and safer to use because each union type is a distinct type. [^variant]
 

docs/cpp2/objects.md

@@ -55,7 +55,7 @@ Additionally, at function local scope an object `obj` can be initialized separat
 
 - Declare `obj` without an initializer, such as `obj: some_type;`. This allocates stack space for the object, but does not construct it.
 
-- `obj` must have a definite first use on every `if`/`else` branch path, and
+- `obj` must have a definite first use on every `#!cpp if`/`#!cpp else` branch path, and
 
 - that definite first use must be of the form `obj = value;` which is a constructor call, or else pass `obj` as an `out` argument to an `out` parameter (which is also effectively a constructor call, and performs the construction in the callee).
 
@@ -92,18 +92,18 @@ load_from_disk: (out buffer) = {
 }                                       // constructs it; otherwise, assigns
 ```
 
-In the above example, note the simple rule for branches: The local variable must be initialized on both the `if` and `else` branches, or neither branch.
+In the above example, note the simple rule for branches: The local variable must be initialized on both the `#!cpp if` and `#!cpp else` branches, or neither branch.
 
 
 ## Heap objects
 
-Objects can also be allocated on the heap using `arena.new <T> (/*initializer, arguments)` where `arena` is any object that acts as a memory arena and provides a `.new` function template. Two memory arena objects are provided in namespace `cpp2`:
+Objects can also be allocated on the heap using `#!cpp arena.new <T> (/*initializer, arguments*/)` where `arena` is any object that acts as a memory arena and provides a `#!cpp .new` function template. Two memory arena objects are provided in namespace `cpp2`:
 
-- `unique.new<T>` calls `std::make_unique` and returns a `std::unique_ptr`.
+- `#!cpp unique.new<T>` calls `std::make_unique<T>` and returns a `std::unique_ptr<T>`.
 
-- `shared.new<T>` calls `std::make_shared` and returns a `std::shared_ptr`.
+- `#!cpp shared.new<T>` calls `std::make_shared<T>` and returns a `std::shared_ptr<T>`.
 
-The default is `unique.new` if you don't specify an arena object.
+The default is `#!cpp unique.new` if you don't specify an arena object.
 
 For example (see [types](types.md) for more details about writing types):