class Grammar in Tinman.Core.Parsing

Represents a grammar for structural parsing.

sealed class

Grammar

extends

Disposable

Remarks

The following code shows the grammar for defining grammars:

grammar       := (decl-skip | decl-rule)+ ;

decl-rule     := [!?] <! identifier ':=' rule ';' ;
decl-skip     := '#' ':=' rule ';' ;

rule          := rule-list ;
rule-ast      := '{' identifier ':' rule (('<!' | '!>') rule)? '}' ;
rule-brace    := '(' rule ')' ;
rule-choice   := rule-sequence !> ('|' rule-sequence)+ ;
rule-except   := rule-not !> '\\' rule-not ;
rule-list     := rule-choice !> '..' rule-choice ;
rule-not      := '~' <! rule-primary ;
rule-primary  := rule-char | rule-token | rule-name | rule-brace | rule-ast ;
rule-repeat   := rule-except !> '?' | '*' | '+' | '[' number ('..' number)? ']' ;
rule-sequence := rule-trim !> (rule-trim)+ ;
rule-trim     := '#' <! rule-repeat !> '#' ;

rule-char     := char-range | char-set | char-set-inv | char-eof ;

char-range    := char-one !> '..' char-one ;

char-one      := '\'' (char-esc | ]\\'[) '\'' ;
char-set      := '[' (char-esc | ]\]\\[)+ ']' ;
char-set-inv  := ']' (char-esc | ]\[\\[)+ '[' ;
rule-token    := '@' <! '\'' (char-esc | ]\\'[)* '\'' ;

char-esc      := '\\' ([t0\]nr\[\\'] | 'x' hexdigit[1..4]) ;
rule-name     := identifier ;

hexdigit      := digit | 'a'..'f' | 'A'..'F' ;
identifier    := letter (letter | digit)* ;
number        := digit+ ;

char-eof      := @'<eof>' ;
digit         := '0'..'9' ;
letter        := 'a'..'z' | 'A'..'Z' | [_-] ;

The above grammar describes itself in its very own grammar language, so it is by definition fully self-explanatory (but still non-comprehensible, so the documentation goes on).

A grammar contains one or more declarations, which can be one of the following:

• decl-rule
  Defines a new grammar rule: the left side defines the rule name, the right side rule content. The rule optionally be prefixed with either '!' or '?', which assigns an additional flag to the grammar rule: either ReportErrorRoot or ReportErrorTerminal, respectively.

  ! expression := 'A' ;
  ? identifier := 'B' ;
  some_rule   := 'C' ;

• decl-skip
  Defines the special grammar rule for rule-trim.

  # := ' ' ;

These are the grammar rules, listed from lowest precedence to highest:

• rule-list (lowest precedence)
  Matches the rules on the left one or more times, while matching the rule on the right as the separator. When the left-side rules are matched n times, the right-side rule will always be matched n-1 times.

  ('A' | 'B' .. # ',' #)

• rule-choice
  Matches one rule in the given list of possible rules:

  'A' | 'B' | 'C'

• rule-sequence
  Matches all given rules one after another:

  'A' 'B' 'C'

• rule-trim
  Trims leading ('#' is left of rule) and/or trailing ('#' is right of rule) whitespace characters (see IsWhitespace) from the input before matching the given rule:

  'A' # ',' # 'B' # ',' # 'C'

  A grammar may optionally define a special skip rule using the special name '#': the skip rule is applied at all potential trim locations. All input characters that are matched by the skip rule are silently dropped.
• rule-repeat
  Matches the given rule multiple times ('?' zero or one, '*' zero or more, '+' one or more). The minimum and maximum number of occurrences can be specified with 'min..max' where min and max specify the respective occurrence count.

  'A'?
  'A'*
  'A'+
  'A'[2..4]

• rule-except
  Matches the left rule only if the right rule does not match.

  'a' .. 'z' \ 'e'

• rule-not
  Matches the current input if the given rule fails:

  ~'A'

• rule-primary (highest precedence)
  

These are the primary rules (same precedence):

• rule-ast
  Matches the given rule(s) and creates an abstract syntax tree node on success (the node will span all input matched by rules inside of the curly braces). The '!>' and '<!' tokens are conditional operators: a syntax tree node is created only iff the rules to the right resp. to the left are also matched.

  { AST : 'A' }
  { AST : 'A' !> 'B' }
  { AST : 'A' <! 'B' }

• rule-brace
  Wraps another given rule, overriding the default rule precedence.
  Example:

  a (b | c) d
  (a | b) (c | d)

• rule-char
  Matches a single character in the given set.

  'A'
  'A'..'C'
  [ABC]
  ]ABC[
  <eof>

  Inverse brackets ']' and '[' indicate that all characters except the specified ones will be matched (inverse set). The <eof> token will match the end of input condition (see IsEof).
• rule-token
  Matches the given string token. Use the '@' prefix to match case-insensitively.
  Example:

  'keyword_case_sensitive'
  @'KeyWord_Case_InSensitive'

• rule-name
  Matches another grammar rule, specified by its name. Identifiers consist of letters, digits, dashes and underscores and must not start with a digit.
  Example:

  name-of-grammar-rule
  rule_123

Parsing is performed by the following steps.

1. Write a grammar script (see above).
2. Create a Grammar object from that script (see ParseGrammar).
3. Create an ICodeInput object (e.g. FromString).
4. Create or obtain some source code that follows the grammar.
5. Use a grammar rule (see GetRule) to parse the source code into an abstract syntax tree (AST).
6. Analyse the ParseResult object and do error handling if necessary.
7. Process the resulting AST (see Ast), for example by creating a program structure information (PSI) model from it (see below).
8. Create a program structure information (PSI) model from an AST node by calling the CreatePsi method.

The following method families provide shortcuts through the steps above:

• ParseInfo:
  Parses the given source code using the specified rule, yielding a ParseResult object that holds detailed information about the parsing process.
• ParseAst:
  Parses the given source code using the specified rule, yielding an AST node.
• ParsePsi:
  Parses the given source code using the specified rule, yielding a PSI object.

Public / Constants

AstRoot

Type for default root AST nodes.

public constant	AstRoot = "ROOT"
type	string

Remarks:

When the result of a parsing process yielded more than one root AST node, an artificial root node of this type is created that holds the yielded nodes.

Public / Attributes

GrammarCode

Returns the source code for grammars in the grammar language.

public static property	GrammarCode { get }
type	string
value	[not-null]	The grammar source code.

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

Rules

The grammar rules.

public property	Rules { get }
type	IMapConst<string, IGrammarRule>
value	[not-null]	Mapping from grammar rule name (see RuleName) to grammar rules.

Public / Constructors

ParseGrammar

Creates a new Grammar object.

[OwnerReturn]
public static method	ParseGrammar (string source)
type	GrammarBuilder
params	source	[not-empty]	The grammar source code.
returns		[not-null]	The GrammarBuilder object for building the grammar. Call Build to get the final Grammar object.

---

Creates a new Grammar object.

[OwnerReturn]
public static method	ParseGrammar (int32 lockedSource)
type	GrammarBuilder
params	lockedSource		The locked grammar source code.
returns		[not-null]	The GrammarBuilder object for building the grammar. Call Build to get the final Grammar object.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

GetRule

Returns a rule of this grammar by its name.

public method	GetRule (string name = null)
type	IGrammarRule
params	name		The rule name or null to return the default rule.
returns			The rule or null if no rule of the given name exists.

ParseAst

Parses the given source code using the specified grammar rule.

public method	ParseAst (string input, string rule = null)
type	AstNode
params	input	[not-null]	The source code to parse.
	rule		The rule name or null to use the default rule.
returns		[not-null]	The resulting AST.

See also:

AstNode.CreatePsi

---

Parses the given source code using the specified grammar rule.

public method	ParseAst (ICodeInput input, string rule = null)
type	AstNode
params	input	[not-null]	The source code to parse.
	rule		The rule name or null to use the default rule.
returns		[not-null]	The resulting AST.

See also:

AstNode.CreatePsi

ParseInfo

Parses the given input data using the specified rule.

public method	ParseInfo (string input, string rule = null)
type	ParseResult
params	input	[not-null]	The input data.
	rule		The rule name or null to use the default rule.
returns		[not-null]	The parser result object.

See also:

ParseResult.Ast
AstNode.CreatePsi

---

Parses the given input data using the specified rule, returning a status object that contains additional information about the parsing process.

public method	ParseInfo (ICodeInput input, string rule = null)
type	ParseResult
params	input	[not-null]	The input data.
	rule		The rule name or null to use the default rule.
returns		[not-null]	The parser result object.

See also:

ParseResult.Ast
AstNode.CreatePsi

ParsePsi

Parses the given source code using the specified grammar rule.

public method	ParsePsi (string input, string rule = null)
type	object
params	input	[not-null]	The source code to parse.
	rule		The rule name or null to use the default rule.
returns		[not-null]	The resulting AST.

---

Parses the given source code using the specified grammar rule.

public method	ParsePsi (ICodeInput input, string rule = null)
type	object
params	input	[not-null]	The source code to parse.
	rule		The rule name or null to use the default rule.
returns		[not-null]	The resulting AST.

ParseWith

Parses the given input, using the specified grammar.

public static method	ParseWith (string grammar, string input)
type	AstNode
params	grammar	[not-empty]	The grammar to use.
	input	[not-empty]	The input to parse.
returns		[not-null]	The parsed AST.

Exceptions:

• ValidatingException:
  If a parsing error has occurred.

ToSource

Returns the grammar source code.

public method	ToSource (RuleToSourceFlags flags = RuleToSourceFlags.None)
type	string
params	flags		The format flags to use.
returns		[not-null]	The grammar source code.