"Comma (multi-statement)" documentation

[JBensimon]

The following two aspects of the "Comma" may be implicit in it being listed in the documentation within the list of expression operators, but they're not obvious and maybe should be explicitly stated:

1/ the fact that the value (result) of a comma expression is the result of its leftmost expression. This is intuitively clear when the leftmost expression is an assignment as in

Code: Select all

a := 1, b := 2, c := 3, d := 4

even though it's (I assume) parsed as

Code: Select all

a := (1, (b := (2, (c := (3, (d := 4))))))

but not so intuitive otherwise, as in

Code: Select all

Return (False, a := 2, b := 3)  ; a and b are ByRef parameters

or in

Code: Select all

MsgBox, % (Func(a, b), ++a, ++b)

2/ the fact that a comma expression is a single expression and can therefore be used without braces following an If or Else, as in

Code: Select all

If !a
  b := 2, c := 3, d := 4
Else
  b := 3, c := 4, d := 5

In this regard, I believe this operator should be described in the documentation as "Comma (multi-expression)" rather than "... (multi-statement)" since the latter suggests that braces should be used in the above situation.

JB

[20170201225639]

The v2 page for expression should contain a mention somewhere of the fact in a multi-statement expression the first sub-expression is used as the result. Currently it doesn't seem to:

https://lexikos.github.io/v2/docs/Language.htm#expressions
https://lexikos.github.io/v2/docs/Variables.htm#comma

To be sure, this is stated early on in the Changes from v1 to v2 page

The result of a multi-statement expression such as x(), y() is the last (right-most) sub-expression instead of the first (left-most) sub-expression. In both v1 and v2, the sub-expressions are evaluated in left to right order.

But my understanding is that the the v2 doc itself (i.e. minus Changes, which is more of a meta-document) is supposed to provide a complete documentation of v2's behavior. If so, that information should be included for completeness.

[safetycar]

It looks like this posit is about v1?
In case of confusion for some other people... In v1 MsgBox % (1,2,3) outputs 1, while in v2 MsgBox( (1,2,3) ) outputs 3.

[lexikos]

The following two aspects of the "Comma" may be implicit in it being listed in the documentation within the list of expression operators

Maybe #2. Definitely not #1. Merely being an operator implies nothing about what its result will be.

1/ the fact that the value (result) of a comma expression is the result of its leftmost expression.

It should perhaps also be explicitly stated that this behaviour is specific to v1.

even though it's (I assume) parsed as a := (1, (b := (2, (c := (3, (d := 4))))))

Note:

Expression Operators (in descending precedence order)
...
:= Assign
...
, Comma (multi-statement)

Assignment has higher precedence, therefore the grouping is (a := 1), (b := 2), etc.

Also,

For example: x:=1, y+=2, ++index, MyFunc(). Such statements are executed in order from left to right.

With the grouping you show, the assignments would be evaluated right to left.

This also aligns with function calls, where evaluating Fn(a := 1, b := 2) as Fn(a := (1, b := 2)) wouldn't make sense.

Do you still think that it is "intuitively clear"?

the fact that a comma expression is a single expression ... should be described in the documentation as "Comma (multi-expression)"

Do you see the irony?

I think the sub-expressions of x:=1, y+=2, ++index, MyFunc() might be referred to as statements rather than expressions because:

• Any value that they might produce is not being used.
• They are executed for their side-effects, not evaluated for their overall value.
• They could be used alone on a line, as a statement.
  (That isn't true for all sub-expressions that multi-statement comma accepts, but is true for most that make sense to use.)

The current name is well established, and I think there isn't a better, more accurate one.

I think raising user awareness of when they can omit braces is not a priority.