5.2 Types

5.2.1 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.2 p_position_t

The p_position_t structure contains two fields row and col. These fields contain the 0-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.3 AST Node Types

If AST 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 an AST node which refers to a raw parser token rather than a composite rule.

5.2.3.1 AST Node Fields

All AST 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.

AST 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 AST node will be null if the parser matches the empty rule pattern.

The non-positional AST 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 AST 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).