Adds default, renames comment to meta, removes fail (#352)

amazon-ion · Oct 15, 2024 · 1057286 · 1057286
1 parent 92c2862
commit 1057286
Show file tree

Hide file tree

Showing 3 changed files with 104 additions and 85 deletions.
diff --git a/_books/ion-1-1/src/macros/special_forms.md b/_books/ion-1-1/src/macros/special_forms.md
@@ -53,10 +53,14 @@ To refine things a bit further, trailing optional arguments can be omitted entir
 ```
 
 > [!TIP]
-> You can define a macro that wraps `if_none` to create a none-coalescing operator.
+> If you're using `if_none` to specify an expression to default to, you can use the [`default`](system_macros.md#default) system macro to be more concise.
 > ```ion
-> (macro coalesce (maybe_none* default_expr+) 
->        (.if_none (%maybe_none) (%default_expr) (%maybe_none)))
+> (macro temperature (degrees scale)
+>     {
+>       degrees: (%degrees),
+>       scale: (.default (%scale) K),
+>     }
+> )
 > ```
 
 ### `if_some`
@@ -184,10 +188,3 @@ a b c
 
 The `for` special form can only be invoked in the body of template macro. It is not valid to use as an E-Expression.
 
-### `fail`
-
-```ion
-(macro fail (message?) /* Not representable in TDL */)
-```
-
-Causes macro evaluation to immediately halt and causes the Ion reader to raise an error to the user. 
diff --git a/_books/ion-1-1/src/macros/system_macros.md b/_books/ion-1-1/src/macros/system_macros.md
@@ -29,6 +29,24 @@ This is, essentially, the identity function.
 It produces a stream from any number of arguments, concatenating the streams produced by the nested expressions.
 Used to aggregate multiple values or sub-streams to pass to a single argument, or to produce multiple results.
 
+#### `default`
+
+```ion
+(macro default (expr* default_expr*)
+    // If `expr` is empty...
+    (.if_none (%expr)
+        // then expand `default_expr` instead.
+        (%default_expr)
+        // If it wasn't empty, then expand `expr`.
+        (%expr)
+    )
+)
+```
+
+`default` tests `expr` to determine whether it expands to the empty stream.
+If it does not, `default` will produce the expansion of `expr`.
+If it does, `default` will produce the expansion of `default_expr` instead.
+
 #### `flatten`
 
 ```ion
@@ -297,19 +315,22 @@ Examples:
 (:sum (:)) => 0
 ```
 
-#### `comment`
+#### `meta`
 
 ```ion
-(macro comment (anything*) (.none))
+(macro meta (anything*) (.none))
 ```
 
-The `comment` macro accepts any values and emits nothing.
-It can be used for comments that must be syntactically valid Ion.
+The `meta` macro accepts any values and emits nothing.
+It allows writers to encode data that will be not be surfaced to most readers.
+Readers can be configured to intercept calls to `meta`, allowing them to read the otherwise invisible data.
+
+When transcribing from one format to another, writers should preserve invocations of `meta` when possible.
 
 Example:
 ```ion
 (:values
-    (:comment equivalent to {foo:1,foo:2})
+    (:meta {author: "Mike Smith", email: "[email protected]"})
     {foo:2,foo:1}
 )
 =>
@@ -408,7 +429,7 @@ Appends the content of the given module to the encoding context.
 ```ion
 (macro use (catalog_key version?)
        $ion_encoding::(
-         (import the_module catalog_key (.if_none (%version) 1 (%version)))
+         (import the_module catalog_key (.default (%version) 1))
          (symbol_table $ion_encoding the_module)
          (macro_table $ion_encoding the_module)
        ))

diff --git a/_books/ion-1-1/src/modules/system_module.md b/_books/ion-1-1/src/modules/system_module.md
@@ -32,74 +32,74 @@ The Ion 1.1 System Symbol table _replaces_ rather than extends the Ion 1.0 Syste
 <!-- make the tables align to the side of the page /-->
 <style>table { margin: 1em;}</style>
 
-| ID | Text                            |
-|---:|:--------------------------------|
-|  0 | _&lt;reserved&gt;_              |
-|  1 | `$ion`                          |
-|  2 | `$ion_1_0`                      |
-|  3 | `$ion_symbol_table`             |
-|  4 | `name`                          |
-|  5 | `version`                       |
-|  6 | `imports`                       |
-|  7 | `symbols`                       |
-|  8 | `max_id`                        |
-|  9 | `$ion_shared_symbol_table`      |
-| 10 | `$ion_encoding`                 |
-| 11 | `$ion_literal`                  |
-| 12 | `$ion_shared_module`            |
-| 13 | `macro`                         |
-| 14 | `macro_table`                   |
-| 15 | `symbol_table`                  |
-| 16 | `module`                        |
-| 17 | see [ion-docs#345][1]           |
-| 18 | `export`                        |
-| 19 | see [ion-docs#345][1]           |
-| 20 | `import`                        |
-| 21 | _zero-length text_ (i.e. `''`)  |
-| 22 | `literal`                       |
-| 23 | `if_none`                       |
-| 24 | `if_some`                       |
-| 25 | `if_single`                     |
-| 26 | `if_multi`                      |
-| 27 | `for`                           |
-| 28 | `fail`                          |
-| 29 | `values`                        |
-| 30 | `annotate`                      |
-| 31 | `make_string`                   |
-| 32 | `make_symbol`                   |
-| 33 | `make_blob`                     |
-| 34 | `make_decimal`                  |
-| 35 | `make_timestamp`                |
-| 36 | `make_list`                     |
-| 37 | `make_sexp`                     |
-| 38 | `make_struct`                   |
-| 39 | `parse_ion`                     |
-| 40 | `repeat`                        |
-| 41 | `delta`                         |
-| 42 | `flatten`                       |
-| 43 | `sum`                           |
-| 44 | `set_symbols`                   |
-| 45 | `add_symbols`                   |
-| 46 | `set_macros`                    |
-| 47 | `add_macros`                    |
-| 48 | `use`                           |
-| 49 | `comment`                       |
-| 50 | `flex_symbol`                   |
-| 51 | `flex_int`                      |
-| 52 | `flex_uint`                     |
-| 53 | `uint8`                         |
-| 54 | `uint16`                        |
-| 55 | `uint32`                        |
-| 56 | `uint64`                        |
-| 57 | `int8`                          |
-| 58 | `int16`                         |
-| 59 | `int32`                         |
-| 60 | `int64`                         |
-| 61 | `float16`                       |
-| 62 | `float32`                       |
-| 63 | `float64`                       |
-| 64 | `none`                          |
-| 65 | `make_field`                    |
+| ID | Text                           |
+|---:|:-------------------------------|
+|  0 | _&lt;reserved&gt;_             |
+|  1 | `$ion`                         |
+|  2 | `$ion_1_0`                     |
+|  3 | `$ion_symbol_table`            |
+|  4 | `name`                         |
+|  5 | `version`                      |
+|  6 | `imports`                      |
+|  7 | `symbols`                      |
+|  8 | `max_id`                       |
+|  9 | `$ion_shared_symbol_table`     |
+| 10 | `$ion_encoding`                |
+| 11 | `$ion_literal`                 |
+| 12 | `$ion_shared_module`           |
+| 13 | `macro`                        |
+| 14 | `macro_table`                  |
+| 15 | `symbol_table`                 |
+| 16 | `module`                       |
+| 17 | see [ion-docs#345][1]          |
+| 18 | `export`                       |
+| 19 | see [ion-docs#345][1]          |
+| 20 | `import`                       |
+| 21 | _zero-length text_ (i.e. `''`) |
+| 22 | `literal`                      |
+| 23 | `if_none`                      |
+| 24 | `if_some`                      |
+| 25 | `if_single`                    |
+| 26 | `if_multi`                     |
+| 27 | `for`                          |
+| 28 | `default`                      |
+| 29 | `values`                       |
+| 30 | `annotate`                     |
+| 31 | `make_string`                  |
+| 32 | `make_symbol`                  |
+| 33 | `make_blob`                    |
+| 34 | `make_decimal`                 |
+| 35 | `make_timestamp`               |
+| 36 | `make_list`                    |
+| 37 | `make_sexp`                    |
+| 38 | `make_struct`                  |
+| 39 | `parse_ion`                    |
+| 40 | `repeat`                       |
+| 41 | `delta`                        |
+| 42 | `flatten`                      |
+| 43 | `sum`                          |
+| 44 | `set_symbols`                  |
+| 45 | `add_symbols`                  |
+| 46 | `set_macros`                   |
+| 47 | `add_macros`                   |
+| 48 | `use`                          |
+| 49 | `meta`                         |
+| 50 | `flex_symbol`                  |
+| 51 | `flex_int`                     |
+| 52 | `flex_uint`                    |
+| 53 | `uint8`                        |
+| 54 | `uint16`                       |
+| 55 | `uint32`                       |
+| 56 | `uint64`                       |
+| 57 | `int8`                         |
+| 58 | `int16`                        |
+| 59 | `int32`                        |
+| 60 | `int64`                        |
+| 61 | `float16`                      |
+| 62 | `float32`                      |
+| 63 | `float64`                      |
+| 64 | `none`                         |
+| 65 | `make_field`                   |
 
 In Ion 1.1 Text, system symbols can never be referenced by symbol ID; `$1` always refers to the first symbol in the user symbol table.
 This allows the Ion 1.1 system symbol table to be relatively large without taking away SID space from the user symbol table.
@@ -129,8 +129,9 @@ This allows the Ion 1.1 system symbol table to be relatively large without takin
 | 18 | [`delta`](../macros/system_macros.md#delta)                   |
 | 19 | [`flatten`](../macros/system_macros.md#flatten)               |
 | 20 | [`sum`](../macros/system_macros.md#sum)                       |
-| 21 | [`comment`](../macros/system_macros.md#comment)               |
+| 21 | [`meta`](../macros/system_macros.md#meta)                     |
 | 22 | [`make_field`](../macros/system_macros.md#make_field)         |
+| 22 | [`default`](../macros/system_macros.md#default)               |
 
 
 ----