Skip to content

Clarify declaration immutability #511

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.

Sign up for GitHub

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

Merged
merged 8 commits into from
Nov 6, 2023
Merged

Clarify declaration immutability #511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e854365
Clarify declaration immutability
aphillips Nov 1, 2023
0c1b8bb
Update formatting.md
aphillips Nov 1, 2023
a67a185
Consistency of referring to an error
aphillips Nov 1, 2023
5d37907
Moved the examples to formatting
aphillips Nov 1, 2023
e9908c8
Address @catamorphism's comments
aphillips Nov 1, 2023
4bb512e
Update syntax.md
aphillips Nov 1, 2023
ebd31e1
Update spec/formatting.md
aphillips Nov 6, 2023
a2305b1
Update spec/formatting.md
aphillips Nov 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 34 additions & 3 deletions spec/formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -758,7 +758,7 @@ These are divided into the following categories:
contains a _selector_ that does not have an _annotation_,
or contains a _variable_ that does not directly or indirectly reference a _declaration_ with an _annotation_.

> Example invalid messages resulting in a _Missing Selector Annotation error_:
> Examples of invalid messages resulting in a _Missing Selector Annotation error_:
>
> ```
> {{
Expand Down Expand Up @@ -786,11 +786,42 @@ These are divided into the following categories:
> }}
> ```

- **Duplicate Option Name errors** occur when the same _name_
- A **Duplicate Declaration error** occurs when a _variable_ appears in two _declarations_.
This includes when an _input-declaration_ binds a _variable_ that appears in a previous _declaration_,
when a _local-declaration_ binds a _variable_ that appears in a previous _declaration_,
or when a _local-declaration_ refers to its bound _variable_ in its _expression_.

> Examples of invalid messages resulting in a Duplicate Declaration error:
>
> ```
> {{
> input {$var :number maxFractionDigits=0}
> input {$var :number minFractionDigits=0}
> {{Redeclaration of the same variable}}
> }}
> {{
> local $var = {$ext :number maxFractionDigits=0}
> input {$var :number minFractionDigits=0}
> {{Redeclaration of a local variable}}
> }}
> {{
> input {$var :number minFractionDigits=0}
> local $var = {$ext :number maxFractionDigits=0}
> {{Redeclaration of an input variable}}
> }}
> {{
> local $var = {$ext :someFunction}
> local $var = {$error}
> local $var2 = {$var2 :error}
> {{{$var} cannot be redefined. {$var2} cannot refer to itself}}
> }}
> ```

- A **Duplicate Option Name error** occurs when the same _name_
appears on the left-hand side
of more than one _option_ in the same _expression_.

> Example invalid messages resulting in a Duplicate Option Name error:
> Examples of invalid messages resulting in a Duplicate Option Name error:
>
> ```
> Value is {42 :number style=percent style=decimal}
Expand Down
34 changes: 27 additions & 7 deletions spec/syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,19 +148,39 @@ MAY include an _annotation_ that is applied to the external value.

A **_<dfn>local-declaration</dfn>_** binds a _variable_ to the resolved value of an _expression_.

Declared _variables_ MUST NOT be used before their _declaration_,
and their values MUST NOT be self-referential;
otherwise, a _message_ is not considered _valid_.

Multiple _declarations_ MUST NOT bind a value to the same _variable_;
otherwise, a _message_ is not considered _valid_.

```abnf
declaration = input-declaration / local-declaration
input-declaration = input [s] variable-expression
local-declaration = local s variable [s] "=" [s] expression
```

_Variables_, once declared, MUST NOT be redeclared.
A _message_ that does any of the following is not _valid_ and will produce a
Duplicate Declaration error during formatting:
- An _input-declaration_ MUST NOT bind a _variable_ that appears as a _variable_ in a previous
_declaration_.
- A _local-declaration_ MUST NOT bind a _variable_ that appears as a _variable_ in a previous
_declaration_.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought local declarations were allowed to override external variables? Or was that a rejected proposal?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a little complicated and I should probably add text about the corner case here.

Currently you can annotate an external value using input:

#input {$var :function opt=val}

... and you can assign it to a local variable:

#local $foo = {$var :function opt=val}

... and you can overwrite an external variable so long as it is not declared:

#local $var = {$foo :function opt=val}  // overwrites any `$var` passed in

But not this:

#input {$var :function opt=val}
#local $var = {$foo :something opt=val}

- A _local-declaration_ MUST NOT bind a _variable_ that appears in its _expression_.

A _local-declaration_ MAY overwrite an external input value as long as the
external input value does not appear in a _declaration_.

> [!Note]
> These restrictions only apply to _declarations_.
> A _placeholder_ or _selector_ can apply a different annotation to a _variable_
> than one applied to the same _variable_ name in a _declaration_.
> For example, this message is _valid_:
> ```
> {{
> input {$var :number maxFractionDigits=0}
> match {$var :plural maxFractionDigits=2}
> when 0 {{The selector can apply a different annotation to {$var} for the purposes of selection}}
> when * {{A placeholder in a pattern can apply a different annotation to {$var :number maxFractionDigits=3}}}
> }}
> ```
> (See [Error Handling](./formatting.md#error-handling) for examples of invalid messages)

### Body

The **_<dfn>body</dfn>_** of a _complex message_ is the part that will be formatted.
Expand Down