Split Expression into OperandExpr and FunctionExpr

[stasm]

The data model proposed in #393 defines Expression as follows:

interface Expression {
  type: 'expression';
  body: Literal | VariableRef | FunctionRef | Reserved;
}

A FunctionRef can also have a Literal or a VariableRef as an argument, and in fact, due to how our syntax is designed, I'd argue that the function's argument is more important than the function. (E.g. it comes first in the syntax.)

I'd like to suggest an alternative way to structure our expressions, to more closely map to our syntax:

expression = "{" [s] ((operand [s annotation]) / annotation) [s] "}"

Let's special-case argument-less functions rather than function-less operands.

Instead of Literal | VariableRef | FunctionRef here and operand?: Literal | VariableRef inside FunctionRef, we can do:

type Expression = OperandExpr | FunctionExpr;
interface OperandExpr {
    operand: Literal | VariableRef;
    annotation?: FunctionExpr;
}
interface FunctionExpr {
    name: string;
    options: Map<string, Literal | VariableRef>;
}

FWIW, this is how I implemented expressions in stasm/message2:
https://github.com/stasm/message2/blob/4abf43f2023b6e20d8ee1d462684d0741ece791b/syntax/ast.ts#L44-L70

Originally posted by @stasm in #393 (comment)

[catamorphism]

I like the change, but find the names a little confusing, since if you mentally expand "OperandExpr" you get "operand expression", which is weird because it suggests that this is an expression that is an operand, rather than having an operand.

How about:

type Expression = AnnotatedExpr | AnnotationExpr;
interface AnnotationExpr {
    operand: Literal | VariableRef;
    annotation?: AnnotationExpr;
}
interface AnnotationExpr {
    name: string;
    options: Map<string, Literal | VariableRef>;
}

(I also thought about "UnaryExpr / NullaryExpr" instead of "AnnotatedExpr / AnnotationExpr", but then the annotation in a UnaryExpr would be a NullaryExpr, which doesn't seem quite right.)

[eemeli]

So if I understand right, with this proposal a variable reference expression {$foo} that's currently

{
  type: 'expression',
  body: { type: 'variable', name: 'foo' }
}

would be represented instead as:

{
  operand: { type: 'variable', name: 'foo' }
}

While this may match our syntax constructs better, why is that a good thing?

Specifically, why should we expect someone reading {$foo} to consider the variable reference that it contains to be an operand? In the syntax and in our internal discussions there are good reasons for this, but I'm not convinced that it's useful to force that mental model onto others.

We should also keep in mind that we may expect the data model to be used with messages originating in other syntaxes, which may not share the same structure as MF2. The current structure of a wrapper expression object with a body with variable shapes is intentionally aligned with such approaches.

I also note that you've left out the reserved + private-use expressions from the proposal. Those will also need to be accounted for in the data model.

[eemeli]

@stasm I think this is out of date following #554?

[aphillips]

@stasm Can I close?