[Qt-qml] documenting the Qml grammar

[Christian Kamm]

Hi,

I think it'd be good to have an annotated grammar of the Qml language in the 
documentation. The current way of teaching by example is great for new users. 
It isn't very good as a quick reference, a reliable way to resolve corner 
cases or to figure out whether something is valid Qml.

To help with that, I've extracted the grammar from qdeclarativejs.g and 
rewritten it to be easier on the eyes. While doing so, I came across a few 
issues that I've commented on inline:


QmlProgram:
    QmlImport* QmlObjectDefinition

QmlImport:
    'import' QmlImportId QmlImportVersion ('as' QmlIdentifier)?
    'import' StringLiteral QmlImportVersion? ('as' QmlIdentifier)?

QmlImportId:
    IdentifierName ('.' IdentifierName)*

The implemented grammar just says "QmlImportId: MemberExpression" and has an 
extra check to verify it's either a string literal or a series of 
FieldMemberExpressions in the parsing code. I think this should be explicit in 
the documentation. It may also be worthwhile to change the grammar like this 
to allow using reserved words for qualified imports.


QmlImportVersion:
    DecimalIntegerLiteral '.' DecimalDigits

The implemented grammar uses NumericLiteral here. Being more explicit shows 
that 1.5e9 is not a valid import version more clearly.


QmlQualifiedId:
    QmlIdentifier ('.' QmlIdentifier)*

This also used to be a MemberExpression.


QmlObjectDefinition:
    QmlQualifiedId '{' QmlObjectMember* '}'

This isn't related to the grammar, but I think reusing an object definition to 
group property bindings isn't great. It can easily confuse new users and 
complicates documenting the Qml syntax. A QmlObjectDefinition defines a new 
object - except when it groups property bindings instead!


QmlObjectMember:
    QmlPropertyDeclaration
    QmlPropertyBinding
    QmlObjectDefinition
    QmlSignalDeclaration
    FunctionDeclaration

Omitted VarDeclaration.


QmlPropertyDeclaration:
    'property' QmlPropertyType QmlIdentifier (':' QmlPropertyRhs)?
    'property' 'list' '<' QmlQualifiedId '>' (':' '[' QmlArrayMemberList? ']')?
    'default' 'property' 'alias' QmlIdentifier ':' QmlPropertyRhs

This is different from the implemented grammar in several ways. 

1. It allows any right-hand side that's valid in a property binding as the 
initializer of a declaration. While separating the two may make sense to 
programmers, what's the harm in making

  property int foo : 3*width

be equivalent to the following:

  property int foo
  foo: 3*width

2. I changed the list type from list<QmlIdentifier> to list<QmlQualifiedId> to 
allow lists of types that have been imported into a namespace. This seems to 
be an oversight in the current implementation.

3. is there any use for 'default' properties that don't have 'alias' type? I 
couldn't think of any and altered the grammar accordingly.

I also omitted 'readonly' properties, they're not implemented. This could be 
simplified further if list types became regular QmlPropertyTypes (i.e. also 
usable in a SignalParameterList and 'default' properties).


QmlPropertyType:
    QmlIdentifier

I dropped ReservedWord and 'var'. The latter is deprecated and no Qml types 
seem to be reserved words.


QmlPropertyBinding:
    QmlQualifiedId ':' QmlPropertyRhs
    QmlQualifiedId ':' '[' QmlArrayMemberList ']'
    QmlQualifiedId 'on' QmlObjectDefinition

QmlPropertyRhs:
    IfStatement
    ExpressionStatement
    EmptyStatement
    Block
    QmlObjectDefinition

QmlArrayMemberList:
    QmlObjectDefinition (';' QmlArrayMemberList)?

QmlSignalDeclaration:
    'signal' QmlIdentifier ('(' QmlSignalParameterList? ')')?

QmlSignalParameterList:
    QmlPropertyType IdentifierName (',' QmlSignalParameterList)? 

QmlIdentifier:
    Identifier except for 'import' 'as' 'on' 'signal' 'property'

'import' is redundant as it is reserved word anyway. There's currently no need 
to reserve 'list'.


I'll open tickets for these bugs/suggestions in a few days, depending on the 
feedback.

Cheers,
Christian