5.2 Types

5.2.1 p_code_point_t

The p_code_point_t type is aliased to a 32-bit unsigned integer. It is used to store decoded code points from the input text and perform lexing based on the grammar's lexer patterns.

5.2.2 p_context_t

Propane defines a p_context_t structure type. The structure is intended to be used opaquely and stores information related to the state of the lexer and parser. Integrating code must define an instance of the p_context_t structure. A pointer to this instance is passed to the generated functions.

5.2.3 p_position_t

The p_position_t structure contains two fields: row and col. These fields contain the 1-based row and column describing a parser position.

For D targets, the p_position_t structure can be checked for validity by querying the valid property.

For C targets, the p_position_t structure can be checked for validity by calling p_position_valid(pos) where pos is a p_position_t structure instance.

5.2.4 p_token_info_t

The p_token_info_t structure contains the following fields:

• position (p_position_t) holds the text position of the first code point in the token.
• end_position (p_position_t) holds the text position of the last code point in the token.
• length (size_t) holds the number of input bytes used by the token.
• token (p_token_t) holds the token ID of the lexed token
• pvalue (p_value_t) holds the parser value associated with the token.

5.2.5 Tree Node Types

If tree generation mode is enabled, a structure type for each rule will be generated. The name of the structure type is given by the name of the rule. Additionally a structure type called Token is generated to represent a tree node which refers to a raw parser token rather than a composite rule.

5.2.5.1 Tree Node Fields

All tree nodes have a position field specifying the text position of the beginning of the matched token or rule, and an end_position field specifying the text position of the end of the matched token or rule. Each of these fields are instances of the p_position_t structure.

A Token node will always have a valid position and end_position. A rule node may not have valid positions if the rule allows for an empty match. In this case the position structure should be checked for validity before using it. For C targets this can be accomplished with if (p_position_valid(node->position)) and for D targets this can be accomplished with if (node.position.valid).

A Token node has the following additional fields:

• token which specifies which token was parsed (one of TOKEN_*)
• pvalue which specifies the parser value for the token. If a lexer user code block assigned to $$, the assigned value will be stored here.

Tree node structures for rules contain generated fields based on the right hand side components specified for all rules of a given name.

In this example:

Start -> Items;

Items -> Item ItemsMore;
Items -> ;

The Start structure will have a field called pItems and another field of the same name but with a positional suffix (pItems1) which both point to the parsed Items node. Their value will be null if the parsed Items rule was empty.

The Items structure will have fields:

• pItem and pItem1 which point to the parsed Item structure.
• pItemsMore and pItemsMore2 which point to the parsed ItemsMore structure.

If a rule can be empty (for example in the second Items rule above), then an instance of a pointer to that rule's generated tree node will be null if the parser matches the empty rule pattern.

The non-positional tree node field pointer will not be generated if there are multiple positions in which an instance of the node it points to could be present. For example, in the below rules:

Dual -> One Two;
Dual -> Two One;

The generated Dual structure will contain pOne1, pTwo2, pTwo1, and pOne2 fields. However, a pOne field and pTwo field will not be generated since it would be ambiguous which one was matched.

If the first rule is matched, then pOne1 and pTwo2 will be non-null while pTwo1 and pOne2 will be null. If the second rule is matched instead, then the opposite would be the case.

If a field alias is present in a rule definition, an additional field will be generated in the tree node with the field alias name. For example:

Exp -> Exp:left plus ExpB:right;

In the generated Exp structure, the fields pExp, pExp1, and left will all point to the same child node (an instance of the Exp structure), and the fields pExpB, pExpB3, and right will all point to the same child node (an instance of the ExpB structure).