XPIDL:Syntax

From MDC

Contents 1 Status of this document 2 Purpose of this document 3 Simplifications, conventions and notation 4 Common BNF 5 XPIDL Syntax (BNF)

[edit] Status of this document

This is just a sketch of the final XPIDL Syntax Documentation. I'm working on gathering all of the BNF and organizing the TOC of this document.

[edit] Purpose of this document

This document is not an introduction to XPIDL or IDL in general. It is more focused on XPIDL syntax and grammar. See XPIDL Main Page for more links and introductory content.

[edit] Simplifications, conventions and notation

In order to simplify the BNF, I will not include XPIDL comments in every place where they can be found. I rather describe them separately and explain how they can be used elsewhere outside the BNF. Otherwise, the BNF itself would get very mangled.

When we use quotation marks to enclose literals that may appear in a XPIDL statement, the quotation marks itself do not belong to the literal by default.

[edit] Common BNF

any-char := any unicode char
any-char-but-LF := any unicode char excluding linefeed char code

any-char and any-char-but-LF are used in a context-dependant manner as will be explained where appropiate.

[edit] XPIDL Syntax (BNF)

XPIDL Comments

xpidl-comment := '/*' any-char* '*/'

Comments are blocks of text which are not parsed by XPIDL interpreters. They are used as a form of documentation. A comment begins with an "/*" and ends with a "*/". Valid XPIDL declarations inside comments are ignored.

In the context of a xpidl-comment, any-char actually means any char excluding "*/" if they happen to be together and in that order, which represents the end of the comment itself.

Identifiers

/* Valid char for identifiers */
xpidl-id-char := [a-zA-Z_0-9]

/* Valid char for the beginning of identifiers */
xpidl-id-char-valid-begin := [a-zA-Z]

xpidl-valid-id := xpidl-id-char-valid-begin xpidl-id-char*

xpidl-valid-id-list :=
       xpidl-valid-id |
       xpidl-valid-id ',' xpidl-valid-id-list

Inline C headers

inline-c-header := 
      '%{C++ ' any-char* '%}' |
      '%{C++ ' any-char* '%}C++' 

In the context of a inline-c-header, any-char actually means any char excluding "%}" if they happen to be together and in that order, which represent the end of the inline C headers section. The inline-c-header may optionally be followed by a repeat of the language name.

Including other XPIDL

 xpidl-include := '#include "' any-char-but-LF* '"\n'

In the context of xpidl-include, any-char-but-LF actually means any char but the linefeed and quotation mark (").

XPIDL Types

xpidl-type := 
       'boolean' |
       'void' |
       'string' |
       'octet' |
       'short' |
       'long' |
       'long long' |
       'unsigned short' |
       'unsigned long' |
       'unsigned long long' |
       'float' |
       'double' |
       'char' |
       'wchar' |
       'wstring' |
       xpidl-valid-id

See more on IDL Author's Guide: Built-in Types

XPIDL Native Types

xpidl-native-type := 
    [ xpidl-native-type-modifiers-decl ] native xpidl-valid-id(any-char-but-LF)

Not quite sure what the native type declaration is; examples in code include nsCOMArray<nsIDOMRange> and nsIntRect & (But doesn't seem to have anything that contains a closing parenthesis)

xpidl-native-type-modifiers-decl :=  '[' xpidl-native-type-modifiers-list ']'

xpidl-native-type-modifiers-list := 
      xpidl-native-type-modifiers |
      xpidl-native-type-modifiers ',' xpidl-native-type-modifiers-list

xpidl-native-type-modifiers :=
      'ref' | 'ptr' | 'nsid' | 'domstring' | 'utf8string' | 'cstring' | 'astring'

See more on IDL Author's Guide: Using native types

UUID

xpidl-HEX := [a-fA-F0-9]

xpidl-UUID := xpidl-HEX{8}'-'xpidl-HEX{4}'-'xpidl-HEX{4}'-'xpidl-HEX{4}'-'xpidl-HEX{12}

Parameters

xpidl-ARRAY-param-modifier := 'array'
xpidl-SIZE_IS-param-modifier := 'size_is('xpidl-valid-id')'
xpidl-RETVAL-param-modifier := 'retval'

xpidl-param-modifier :=
      xpidl-ARRAY-param-modifier |
      xpidl-SIZE_IS-param-modifier |
      xpidl-RETVAL-param-modifier |
      'const' |
      xpidl-IID_IS-param-modifier |
      'shared'

xpidl-param-modifier-list := 
       xpidl-param-modifier |
       xpidl-param-modifier ',' xpidl-param-modifier-list

xpidl-param-modifier-list-decl := '[' xpidl-param-modifier-list ']'

xpidl-param-type := 'in' | 'out' | 'inout'
xpidl-param-decl := [ xpidl-param-modifier-list-decl ] xpidl-param-type xpidl-type xpidl-valid-id

xpidl-param-list := 
       xpidl-param-decl |
       xpidl-param-decl ',' xpidl-param-list

Attributes and Methods

xpidl-method-modifier := 'noscript' | 'notxpcom'
xpidl-method-modifier-list := 
       xpidl-method-modifier |
       xpidl-method-modifier',' xpidl-method-modifier-list
xpidl-method-modifiers := '[' xpidl-method-modifier-list ']' 

xpidl-attribute := [ xpidl-method-modifiers ] 'attribute' xpidl-type xpidl-valid-id ';'

xpidl-method := [ xpidl-method-modifiers ] xpidl-type xpidl-valid-id '('[ xpidl-param-list ]');'

xpidl-attr-or-method :=
       xpidl-attribute |
       xpidl-method

Interfaces

xpidl-interface-body := xpidl-attr-or-method*

xpidl-scriptable-interface := 'scriptable'
xpidl-interface-uuid := 'uuid('xpidl-UUID')'

xpidl-interface-header := '[' [ xpidl-interface-modifier-list ',' ] xpidl-interface-uuid ']'

xpidl-interface-modifier-list :=
      xpidl-interface-header-modifier |
      xpidl-interface-header-modifier ',' xpidl-interface-header-modifier-list
 
xpidl-interface-modifier :=
      xpidl-scriptable-interface |
      'function' |
      'object' |
      'notxpcom' |
      'noscript'

xpidl-interface := 
       xpidl-interface-header
       'interface ' xpidl-valid-id [ ':' xpidl-valid-id-list ]
       '{'
           xpidl-interface-body
       '}'