#include <mw/cbnfparser.h>
| class CBNFParser : public CBase |
| Protected Member Type Definitions | |
|---|---|
| typedef | CStack< CBNFNode, EFalse > CRuleStack |
| typedef | void( TRuleCallback |
| Protected Attributes | |
|---|---|
| CBNFNode * | iCurrentRule |
| CAttributeLookupTable & | iLUT |
| CFragmentedString::TStringMatch | iMatched |
| const TDesC * | iMoreCount |
| const TDesC * | iMoreMaximum |
| const TDesC * | iMoreMinimum |
| TBool | iOptionalMatched |
| TParseState | iParsing |
| const TDesC * | iPostRuleCallback |
| const TDesC * | iPreRuleCallback |
| const TDesC * | iRangeEnd |
| const TDesC * | iRangeStart |
| const TDesC * | iReferenceString |
| CRuleStack | iRuleStack |
| CFragmentedString | iString |
| TBool | iStringComplete |
| CBNFNode * | iSubRule |
| TBool | iSubRuleMatched |
| CBNFNode * | iTree |
Base class for parsers that use a BNF tree to parse an input stream.
The BNF tree form used is a variation on Extended BNF described in the XML1.0 specification. The general form of the tree is as follows:
Each node in the tree defines a rule that the input stream must meet to satisfy the grammar.
1. a node type is set to the rule type, as defined in TParserNodeTypes
2. node data stores any string required by the rule: e.g. for a comparison rule, the string to match against
3. the parser allows callback functions to be called either before or after the rule is processed. If these are present, they are stored as attributes of the node.
4. some rules allow sub-rules: for example, the AND rule expects a number of sub-rules, all of which must be successful if the AND rule itself is to succeed. Each sub-rule is represented as a child node of the parent rule. Sub-rules in turn can have sub-rules.
5. reference rule nodes are also allowed: these do not define themselves rules, but direct the parser to another rule. They can link rules to each other and so build rule sequences more complex than a simple tree.
All the top-level rules are stored as attributes of the root node. The attribute type is a string that names the rule; the attribute value is a pointer to the node that implements the rule.
The class supplies functions that encapsulate adding rules appropriately to the tree. The parser provider creates a derived class that implements the virtual method TreeL() that uses these functions to create a BNF rule tree.
The user of the parser initialises the parser with ResetL(), and then passes input data to the parser using ProcessData(). The parser supports partial parsing: the input stream does not have to completed before parsing can begin. As soon as data is added, the parser attempts to parse it.
| typedef void( | TRuleCallback | [protected] |
Type definition for a callback function pointer Callback functions need to get a reference to the parser as parameter and they need to be static.
| CAttributeLookupTable & | iLUT | [protected] |
Storage object for all the attributes and identifiers in a tree
| const TDesC * | iMoreCount | [protected] |
Stores attribute identifier for nmore count attributes.
| const TDesC * | iMoreMaximum | [protected] |
Stores attribute identifier for nmore maximum attributes.
| const TDesC * | iMoreMinimum | [protected] |
Stores attribute identifier for nmore minimum attributes.
| TBool | iOptionalMatched | [protected] |
Flag that indicates when returning to a rule in the rulestack if an optional rule matched correctly.
| const TDesC * | iPostRuleCallback | [protected] |
Stores attribute identifier for post-rule callback attributes.
| const TDesC * | iPreRuleCallback | [protected] |
Stores attribute identifier for pre-rule callback attributes.
| const TDesC * | iRangeStart | [protected] |
Stores attribute identifier for range start attributes.
| const TDesC * | iReferenceString | [protected] |
Stores attribute identifier for reference string attributes.
| CRuleStack | iRuleStack | [protected] |
A stack of rules from iTree which are waiting to be completed. The stack basically holds the path along the rule tree.
| CFragmentedString | iString | [protected] |
An utility object which stores all the buffers passed into the parser and represents them as if they would form a single, continuous string. This class also performs the actual physical matching/selection of the strings and holds the marks set onto the string.
| TBool | iStringComplete | [protected] |
Flag indicating if the input stream has been completely processed.
| CBNFNode * | iSubRule | [protected] |
The child rule we are returning from (if any). If this is NULL we are new to this BNF rule.
| TBool | iSubRuleMatched | [protected] |
Flag that indicates when returning to a rule in the rulestack if the child rule matched correctly.
| IMPORT_C | CBNFParser | ( | CAttributeLookupTable & | aLUT | ) | [protected] |
Constructor.
| Parameter | Description |
|---|---|
| aLUT | Attribute lookup table |
| IMPORT_C void | AddComponentAttributeL | ( | CBNFNode & | aRule, |
| CBNFNodeAttributeType | aAttribute, | |||
| TInt | aInt | |||
| ) | ||||
Adds an additional attribute to an existing rule node.
For example, this is used with range rules, which specify the range boundaries using start and end attributes.
| Parameter | Description |
|---|---|
| aRule | Rule node on which to set the attribute |
| aAttribute | Attribute type |
| aInt | Attribute value |
| IMPORT_C void | AddRuleCallbackL | ( | CBNFNode & | aRule, |
| const TDesC * | aCallbackID, | |||
| TRuleCallback * | aCallback | |||
| ) | [protected, virtual] | |||
Adds a callback to a rule.
| Parameter | Description |
|---|---|
| aRule | The rule to which the callback is to be added |
| aCallbackID | Callback type: either CBNFNode::KPreRuleCallback() or CBNFNode::KPostRuleCallback() |
| aCallback | Callback function |
| IMPORT_C TBool | AndL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an EAnd rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C CAttributeLookupTable & | AttributeLUT | ( | ) | const [protected] |
Gets the attribute look-up table used by this parser.
Returns: Attribute look-up table
| IMPORT_C void | CommitL | ( | ) |
Notifies the parser that all the data has been passed in.
It causes the parser to parse any of the input stream not already parsed.
| CBNFNode * | CurrentRule | ( | ) | [inline] |
Gets a pointer to the rule node currently being processed.
Returns: Rule node
| void | DeleteMark | ( | ) | [inline] |
Removes the latest mark. All the marks are stored in a stack and this removes the topmost mark.
| IMPORT_C void | EndConditional | ( | TParserNodeTypes | aRuleType, |
| TBool | aSuccess | |||
| ) | [protected, virtual] | |||
| IMPORT_C TBool | ExactL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an EExact rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C void | ExecutePostRuleCallbackL | ( | CBNFNode & | aRule | ) | [protected, virtual] |
Executes a post-rule callback function.
| Parameter | Description |
|---|---|
| aRule | Node specifying the callback |
| IMPORT_C void | ExecutePreRuleCallbackL | ( | CBNFNode & | aRule | ) | [protected, virtual] |
Executes a pre-rule callback function.
| Parameter | Description |
|---|---|
| aRule | Node specifying the callback |
| void | Mark | ( | ) | [inline] |
Set a mark to the current position of the input stream.
The mark acts as a tag in the stream currently being processed. As we process further along the stream after adding the mark, we can perform a rollback to the most previously set mark and start processing again (e.g. OR rule works this way). The string fragments won't be consumed (deleted) until all the marks on a fragment (and fragments before that) are deleted.
| IMPORT_C void | MarkCallback | ( | CBNFParser & | aParser | ) | [protected, static] |
Inserts a mark to the current position of the stream being processed.
Adding a mark is a very common callback operation before starting to process a rule, so the method is provided by the parser.
| Parameter | Description |
|---|---|
| aParser | Parser processing the stream |
| HBufC * | MarkedL | ( | ) | [inline] |
Get string between the "cursor position" and the latest mark on the stream.
Returns: Pointer to the string from the previous mark on to the current position of processed string. OWNERSHIP OF THE STRING GIVEN TO THE CALLER.
| IMPORT_C TBool | NMoreL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an ENMore rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C CBNFNode * | NewBNFL | ( | ) |
Creates a new rule tree root node.
It creates a new single instance of CBNFNode as the root node of the rule tree. All the top-level rules are attached as attributes to this node. The root node should have single child node, which should be a reference to the logical root of the rule tree. This can be done be attaching the logical root rule as a component to the root rule.
Returns: New rule tree root node
| IMPORT_C CBNFNode * | NewComponentL | ( | TParserNodeTypes | aRuleType, |
| const TDesC & | aData | |||
| ) | ||||
Creates a new rule node, but does not add it to the tree.
This overload sets no rule callbacks.
| Parameter | Description |
|---|---|
| aRuleType | Rule type |
| aData | Rule data reference. This is used with EExact and ESelect type rules to match actual text strings. |
Returns: The new rule node
| IMPORT_C CBNFNode * | NewComponentL | ( | TParserNodeTypes | aRuleType, |
| HBufC * | aData = NULL, | |||
| TRuleCallback * | aPreRule = NULL, | |||
| TRuleCallback * | aPostRule = NULL | |||
| ) | ||||
Creates a new rule node, but does not add it to the tree.
This overload allows rule callbacks to be set.
| Parameter | Description |
|---|---|
| aRuleType | Rule type |
| aData | Rule data pointer. This is used with EExact and ESelect type rules to match actual text strings. |
| aPreRule | Function pointer to a pre-rule function that gets called before the parser starts processing this rule and its subtree. |
| aPostRule | The new rule node |
Returns: The new rule node
| IMPORT_C CBNFNode & | NewComponentL | ( | CBNFNode & | aParentRule, |
| TParserNodeTypes | aRuleType, | |||
| const TDesC & | aData | |||
| ) | ||||
Creates a new sub-rule, and makes it a child of a specified parent rule.
This overload sets no rule callbacks.
| Parameter | Description |
|---|---|
| aParentRule | The rule to the new sub-rule shall be added as a child |
| aRuleType | Rule type |
| aData | Rule data reference. This is used with EExact and ESelect type rules to match actual text strings. |
Returns: The new sub-rule node
| IMPORT_C CBNFNode & | NewComponentL | ( | CBNFNode & | aParentRule, |
| TParserNodeTypes | aRuleType, | |||
| HBufC * | aData = NULL, | |||
| TRuleCallback * | aPreRule = NULL, | |||
| TRuleCallback * | aPostRule = NULL | |||
| ) | ||||
Creates a new sub-rule, and makes it a child of a specified parent rule.
This overload sets rule callbacks.
| Parameter | Description |
|---|---|
| aParentRule | The rule to the new sub-rule shall be added as a child |
| aRuleType | Rule type |
| aData | Rule data pointer. This is used with EExact and ESelect type rules to match actual text strings. |
| aPreRule | Function pointer to a pre-rule function that gets called before the parser starts processing this rule and its subtree. |
| aPostRule | Function pointer to a post-rule function that gets called after the parser has processed this rule and its subtree. |
Returns: The new sub-rule node
| IMPORT_C CBNFNode & | NewComponentL | ( | CBNFNode * | aRootRule, |
| CBNFNode & | aParentRule, | |||
| const TDesC & | aRuleName | |||
| ) | ||||
Creates a new reference rule node, and adds it as a child of the specified parent.
Note that the function succeeds even if the target rule aRuleName does not yet exist.
| Parameter | Description |
|---|---|
| aRootRule | Root node: the function needs this to find the target rule identified by aRuleName |
| aParentRule | Parent rule to which to attach the new rule as a child |
| aRuleName | The name of the rule that the new node refers to |
Returns: The new reference rule node
| IMPORT_C CBNFParser * | NewL | ( | CAttributeLookupTable & | aLUT | ) | [static] |
Allocates and constructs a new BNF parser.
| Parameter | Description |
|---|---|
| aLUT | Attribute lookup table in which to store attributes for the rule tree |
Returns: New parser
| IMPORT_C CBNFNode & | NewRuleL | ( | CBNFNode * | aRootRule, |
| const TDesC & | aRuleName, | |||
| TParserNodeTypes | aRuleType, | |||
| HBufC * | aData, | |||
| TRuleCallback * | aPreRule, | |||
| TRuleCallback * | aPostRule | |||
| ) | ||||
Creates a new rule node and adds it to the root of the rule tree.
This overload takes ownership of the node data.
| Parameter | Description |
|---|---|
| aRootRule | Pointer to the root BNF node, created with NewBNFL() |
| aRuleName | Reference to a string identifying this rule. The string is used to make references to this rule from other rule's subtrees. |
| aRuleType | Rule type |
| aData | Rule data pointer. This is used with EExact and ESelect type rules to match actual text strings. |
| aPreRule | Function pointer to a pre-rule function that gets called before the parser starts processing this rule and its children (i.e. the rule subtree). |
| aPostRule | Function pointer to a post-rule function that gets called after the parser has processed this rule and its subtree. |
Returns: The newly created rule node in the rule tree
| IMPORT_C CBNFNode & | NewRuleL | ( | CBNFNode * | aRootRule, |
| const TDesC & | aRuleName, | |||
| TParserNodeTypes | aRuleType, | |||
| const TDesC & | aData, | |||
| TRuleCallback * | aPreRule, | |||
| TRuleCallback * | aPostRule | |||
| ) | ||||
Creates a new rule node and adds it to the root of the rule tree.
This overload takes a reference to the node data instead of owning it.
| Parameter | Description |
|---|---|
| aRootRule | Pointer to the root BNF node, created with NewBNFL() |
| aRuleName | Reference to a string identifying this rule. The string is used to make references to this rule from other rule's subtrees. |
| aRuleType | Rule type |
| aData | Rule data pointer. This is used with EExact and ESelect type rules to match actual text strings. |
| aPreRule | Function pointer to a pre-rule function that gets called before the parser starts processing this rule and its children (i.e. the rule subtree). |
| aPostRule | Function pointer to a post-rule function that gets called after the parser has processed this rule and its subtree. |
Returns: The newly created rule node in the rule tree
| IMPORT_C TBool | OptionalL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
| TBool | OptionalMatched | ( | ) | const [inline] |
Tests if an Optional node sub-rule matched.
Returns: True if the sub- rule matched; otherwise false
| IMPORT_C TBool | OrL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an EOr rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C TBool | PerformRuleL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Handles a node in the rule tree.
It calls the appropriate handler method for the rule type.
| Parameter | Description |
|---|---|
| aRule | Rule node |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C void | ProcessDataL | ( | HBufC8 & | aData | ) | [virtual] |
Called by the data provider to add data for the parser to process.
This implements MDataProviderObserver::ProcessDataL().
| Parameter | Description |
|---|---|
| aData | The data to process |
| IMPORT_C TBool | RangeL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an ERange rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C TBool | ReferenceL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes a reference rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| IMPORT_C void | ResetL | ( | ) | [virtual] |
Reset the parser to a state where it can accept and parse new input.
If no BNF tree yet exists the virtual method TreeL() is called to obtain the BNF tree for this parser. Any existing state of parsing and input data is destroyed.
| TBool | RuleMatched | ( | ) | const [inline] |
Tests if the used rule matched.
This is typically used in post-rule callbacks.
Returns: True if the used rule matched; otherwise false
| IMPORT_C TBool | SelectL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an ESelect rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse
| void | SetAttributeLookupTable | ( | CAttributeLookupTable & | aAttributeLookupTable | ) |
| void | SetState | ( | TParseState | aState | ) | [protected, inline] |
Sets the parser state.
| Parameter | Description |
|---|---|
| aState | Parser state |
Called by the data provider to report its status to its observer.
This implements MDataProviderObserver::SetStatus().
| Parameter | Description |
|---|---|
| aStatus | Status code |
| IMPORT_C void | StartConditional | ( | TParserNodeTypes | aRuleType | ) | [protected, virtual] |
| HBufC * | StringL | ( | ) | const [inline] |
Concatenates the rest of the input stream (which hasn't yet been processed) into a single string. The ownership of the string is given to the caller.
Returns: String containing the remaining data to be parsed. OWNERSHIP PASSED TO CALLED.
| TBool | Valid | ( | ) | const [inline] |
Checks if the input stream was completely processed
Returns: ETrue if all of the data was processed, EFalse if the data didn't match to the parsing rules
| IMPORT_C TBool | WithoutL | ( | CBNFNode & | aRule, |
| CFragmentedString::TStringMatch & | aMatched | |||
| ) | [protected, virtual] | |||
Processes an EWithout rule node.
It is called by PerformRuleL().
| Parameter | Description |
|---|---|
| aRule | The rule node being processed |
| aMatched | On return, flag indicating if input stream matched the rule |
Returns: ETrue if the function completed processing this node, otherwise EFalse