Even though it's explained in the formatting doc, is it worth explaining here as well that in the third example, either there must be a previous in-scope definition of foo, or this declaration is syntactically correct but semantically invalid?

A better example would make the second $foo into $bar or perhaps $someNumber, since the point of examples is to demonstrate the syntax.

@aphillips Fair point. However, I'd like it if there was some place to put an example like this:

let $foo = {|5|}
let $foo = {$foo :number minimumFractionDigits=2}
{{$foo}}

It would be useful for explaining the meaning of variable resolution if the example said: "If this message resolves to a string, the string is '5.00'." That would show that the $foo on the RHS on the second declaration is not the same as the $foo on the LHS.

Probably the syntax.md document isn't the place for that, since it doesn't show the resolved value of any of the examples.

Anyway, for illustrating the syntax, I'm OK with either or both.

Should we also state that selectors and other post-declaration expressions can't modify a value (no non-declaration side-effects)?

I would suggest a slight wording change to make it easier (for me) to parse:

I think the function purity / lack of side effects ought to be addressed with respect to function resolution, rather than here.

The proposed "is processed sequentially" statement is a bit problematic, as it may be interpreted to require and enforce an eager processing model. Consider this message:

let $foo = {:really-heavy-operation}
match {$bar}
when 0 {Nothing here}
when * {Have a {$foo}}

In this case, we should make sure that in the bar == 0 case an implementation is not required to determine and then throw away the value of $foo.

Note that there is already an open issue about whether to require eager or lazy evaluation of local variables: #299

That said, I don't think either version of the wording commits to either eager or lazy evaluation. It depends on the interpretation of the word "processed". "Processing" could mean evaluating (resolving?) the right-hand side of the declaration and binding the left-hand side to the resulting value, or it could mean binding the left-hand side to a thunk representing the right-hand side.

In an ideal world, this would say something like "variables are lexically scoped". That would obviate the need to talk about the "most recent declaration". However, explaining what "lexical scope" means for messages would mean explaining that:

let $v1 = $e1
let $v2 = $e2
match ...

desugars to:

let $v1 = $e1 in
  let $v2 = $e2 in
     match ...

and that external definitions of variables desugar to lets that enclose the message. I think that should be left for future work. I'm OK with merging the PR as-is; I think it's probably as precise as it's possible to get without mentioning lexical scope.

@eemeli I don't think we have to say anything about early or late binding of variables: we should not require early binding but we should not require late binding either. It's an implementation detail. What is important is that declarations behave as if they were evaluated in order.

I think we can let the text go in as-is and revisit.

In an ideal world, this would say something like "variables are lexically scoped". That would obviate the need to talk about the "most recent declaration". However, explaining what "lexical scope" means for messages would mean explaining that:

let $v1 = $e1
let $v2 = $e2
match ...

desugars to:

let $v1 = $e1 in
  let $v2 = $e2 in
     match ...

and that external definitions of variables desugar to lets that enclose the message. I think that should be left for future work. I'm OK with merging the PR as-is; I think it's probably as precise as it's possible to get without mentioning lexical scope.

@aphillips Fair point. However, I'd like it if there was some place to put an example like this:

let $foo = {|5|}
let $foo = {$foo :number minimumFractionDigits=2}
{{$foo}}

It would be useful for explaining the meaning of variable resolution if the example said: "If this message resolves to a string, the string is '5.00'." That would show that the $foo on the RHS on the second declaration is not the same as the $foo on the LHS.

Probably the syntax.md document isn't the place for that, since it doesn't show the resolved value of any of the examples.

Anyway, for illustrating the syntax, I'm OK with either or both.

I think that last time we proposed to not allow overriding.
Compared to programming, these messages are a relatively short "code block"
There should be no problem to just use a different name.
It just introduces complexity without any benefit that I can imagine.