24.10 Step location accessors

This section describes step accessors that are not basic to stack manipulation. They provide Earley set location information about the parse tree.

A step’s location in terms of Earley sets is called its ES location. Every ES location is the ID of an Earley set. ES location is only relevant for steps that correspond to tree nodes.

Every tree node has both a start ES location and an end ES location. The start ES location is the first ES location of that parse node.

The end ES location of a leaf is the ES location where the next leaf symbol in the fringe of the current parse tree would start. Typically, this is the location where a leaf node actually starts but, at the end of a parse, there is not an actual next leaf node.

The start ES location of a MARPA_RULE_STEP step is the start ES location of its first child node in the current parse tree. The end ES location of a MARPA_RULE_STEP step is the end ES location of its last child node in the current parse tree.

Accessor macro: Marpa_Earley_Set_ID marpa_v_es_id (Marpa_Value v)

Return value: If the current step type is MARPA_STEP_RULE, MARPA_STEP_TOKEN, or MARPA_STEP_NULLING_SYMBOL, the return value is the end ES location of the parse node. If the current step type is anything else, or if the valuator is inactive, the return value is unspecified.

Accessor macro: Marpa_Earley_Set_ID marpa_v_rule_start_es_id (Marpa_Value v)

Return value: If the current step type is MARPA_STEP_RULE, the start ES location of the rule node. If the current step type is anything else, or if the valuator is inactive, the return value is unspecified.

Accessor macro: Marpa_Earley_Set_ID marpa_v_token_start_es_id (Marpa_Value v)

Return value: If the current step type is MARPA_STEP_TOKEN or MARPA_STEP_NULLING_SYMBOL, the start ES location of the leaf node. If the current step type is anything else, or if the valuator is inactive, the return value is unspecified.

For every parse node of the current parse tree, the Earley set length (ES length) of the node is the end ES location, less the start ES location. The ES length of a nulled node is always 0.

If v is a valuator whose current step type is MARPA_STEP_NULLING_SYMBOL, it is always the case that

         marpa_v_token_start_es_id(v) == marpa_v_es_id(v)

If v is a valuator whose current step type is MARPA_STEP_RULE or MARPA_STEP_TOKEN, it is always the case that

        marpa_v_token_start_es_id(v) <= marpa_v_es_id(v)

For the following examples,

• let Null be a nulling symbol,
• let Tok be a non-nullable symbol, and
• let the notation Sym@m-n indicate that the symbol Sym has ES start location m and ES end location n.

Ordered from left to right, a possible fringe is

        Null@0-0, Tok@0-1, Null@1-1, Tok@1-2, Null@2-2

Another example is

        Null@0-0, Null@0-0, Tok@0-1, Null@1-1, Null@1-1, Tok@1-2,
        Null@2-2, Null@2-2

In this second example note that when a nulled leaf immediately follows another nulled leaf, both leaves has the same start ES location and the same end ES location. This makes sense, because nulled symbol instances do not advance the current ES location, but it also implies that the ES locations and LHS symbol cannot be used to uniquely identify a parse node.