Specify syntax of Text E-expressions, and align with template invocations. #308
Conversation
src/eexprs.adoc
Outdated
| In other words, an E-expression must contain one element for each required | ||
| parameter, followed by optional elements for the remaining optional parameters. |
There was a problem hiding this comment.
This wording is confusing because it's not clear if "required parameter" in this context means "a parameter with ! cardinality" or "an argument that must be provided at the call site" (and similarly for "optional parameter"). Some readers may understand it to imply that ? parameters must come after ! parameters in the signature.
I think some examples would go a long way here.
There was a problem hiding this comment.
"required parameter" should be a formally-defined term: a parameter is required if its not optional. Specifically, every ! / + / ...+ parameter is required, as are any preceding parameters.
I thought that was in the glossary but apparently it's not, so I'll add.
There was a problem hiding this comment.
Also, there are examples in 3.12 in the "macros by example" section that include required ? and * parameters. I'll add a link.
| The parameter type constrains the syntax of an individual argument as follows: | ||
|
|
||
| * For tagged types, an individual argument must be a single E-expression or any | ||
| datum (which may contain nested E-expressions). |
There was a problem hiding this comment.
Are we defining "datum" somewhere? Is it distinct from "value" in some way?
There was a problem hiding this comment.
We've not defined 'datum', and it might not be the best term. (Other than this line it's only used in the grammar: (**literal** _datum_).
I'm using it here to mean "syntax tree" as the semantic model defines it, but that term hasn't been incorporated into this document.
"Value" is not correct; since these are syntax trees and we use "value" to denote the results of expanding syntax trees.
Another way to write this might be:
For tagged types, an individual argument must be a single syntax tree, which may be an E-expression and/or contain nested E-expressions.
But ATM that doesn't seem better since we don't currently talk in detail about the expansion process. (Another gap in the document!)
| * the macros exported from modules ``load``ed by the enclosing module | ||
| * the macros exported from modules ``load``ed by the enclosing `$ion_encoding` directive | ||
|
|
||
| The syntax for macro invocation in a template is similar to that of <<sec:eexprs,E-expressions>>. |
There was a problem hiding this comment.
There is a lot in this section that is repeated. Could we explain macro invocations in a way that DRYs this?
There was a problem hiding this comment.
Perhaps, but there are also differences that make it hard to slot a unified description into either chapter.
I'm inclined to leave that for later cleanup.
Co-authored-by: Matthew Pope <[email protected]>
Co-authored-by: Zack Slayton <[email protected]>
Resolves #303
Description of changes:
I've once again tried a new narrative flow for explaining the effects of parameter type and cardinality on argument syntax. Here I've introduced a new term individual argument to mean an ungrouped subexpression, and in contrasted with grouped argument (which collects individual arguments). I think this is more clear that earlier iterations, but feedback is welcomed.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.