-
Notifications
You must be signed in to change notification settings - Fork 22
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Specify syntax of Text E-expressions, and align with template invocations. #308
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are we defining "datum" somewhere? Is it distinct from "value" in some way?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 <81593196+popematt@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a few comments, but none are blockers.
Co-authored-by: Zack Slayton <zack.slayton@gmail.com>
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.