     [file version_i.texi not included]

Libmarpa internals
******************

This manual (UPDATED) is for the internals of Libmarpa VERSION.

Copyright © 2014 Jeffrey Kegler.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation. A copy of the license is included in the section entitled ``GNU Free Documentation License.''

GNU LESSER GENERAL PUBLIC LICENSE
*********************************

     [file lgpl-3.0.texi not included]

About this document
*******************

This manual is a tool for is those working on the Libmarpa internals. Unless you are thoroughly familiar with Libmarpa already, it is not of interest to you.

Internal Interface
******************

Internal methods are only for testing and development of libmarpa. They are listed here (and sometimes described) for the convenience of those working on libmarpa's internals.

Internal methods are subject to change. Applications should not use internal methods. If a description exists and might be helpful, it may be included below, but all applications should treat these methods as ``undocumented''.

Symbol internal methods
=======================

 -- Function: int _marpa_g_nsy_is_start ( Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID)

 -- Function: int _marpa_g_nsy_is_nulling (
     Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID)

 -- Function: int _marpa_g_nsy_is_lhs (
     Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID)

 -- Function: Marpa_NSY_ID _marpa_g_xsy_nulling_nsy (
     Marpa_Grammar G,
     Marpa_Symbol_ID SYMID)

 -- Function: Marpa_NSY_ID _marpa_g_xsy_nsy (
     Marpa_Grammar G,
     Marpa_Symbol_ID SYMID)

 -- Function: int _marpa_g_nsy_is_semantic (
     Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID)

 -- Function: Marpa_Rule_ID _marpa_g_source_xsy (
     Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID)

 -- Function: Marpa_Rule_ID _marpa_g_nsy_lhs_xrl (
     Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID)

 -- Function: int _marpa_g_nsy_xrl_offset (
     Marpa_Grammar G,
     Marpa_NSY_ID NSY_ID )

Rule internals
==============

 -- Function: int _marpa_g_rule_is_keep_separation (
     Marpa_Grammar G,
     Marpa_Rule_ID RULE_ID)
     This function does nothing but return an undocumented flag. At some point, I may optimize cases where separators are discarded, in which case this flag will be used. I may also remove this call entirely. Return value: Returns 1 if the keep separation flag is set, 0 if not. Returns 0 if RULE_ID is not a sequence rule. On failure, returns -2.

 -- Function: int _marpa_g_nsy_count (
     Marpa_Grammar G)

 -- Function: int _marpa_g_irl_count (
     Marpa_Grammar G)

 -- Function: Marpa_Symbol_ID _marpa_g_irl_lhs (
     Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)
     Return value: On success, the LHS symbol of the IRL. On failure, -2.

 -- Function: int _marpa_g_irl_length (
     Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)
     The length of a IRL is the number of symbols on its RHS.

     Return value: On success, the IRL length. On failure, -2.

 -- Function: Marpa_Symbol_ID _marpa_g_irl_rhs (
     Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID,
     int IX)
     The position in the IRL, IX, is zero-based. If IX is greater than or equal the length of the IRL, it is a soft failure. This can be used in loops, to avoid having to determine the IRL's length explicitly.

     Return value: On success, the symbol in position IX on the IRL's RHS. If IX is greater than or equal to the length of the IRL, -1. On other failures, -2.

 -- Function: int _marpa_g_rule_is_used (Marpa_Grammar G,
     Marpa_Rule_ID RULE_ID)

 -- Function: int _marpa_g_irl_is_virtual_lhs (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: int _marpa_g_irl_is_virtual_rhs (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: int _marpa_g_virtual_start (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: int _marpa_g_virtual_end (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: Marpa_Rule_ID _marpa_g_source_xrl (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: int _marpa_g_real_symbol_count (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: Marpa_Rule_ID _marpa_g_irl_semantic_equivalent (Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: Marpa_Rank _marpa_g_irl_rank (
     Marpa_Grammar G,
     Marpa_IRL_ID IRL_ID)

 -- Function: Marpa_Rank _marpa_g_nsy_rank (
     Marpa_Grammar G,
     Marpa_IRL_ID NSY_ID)

Grammar internal methods
========================

The methods in this section are accessors for Libmarpa's AHMs. Their use requires familiarity with Marpa's internals, as described in Marpa: The Program.

 -- Function: int _marpa_g_ahm_count (Marpa_Grammar G)

 -- Function: Marpa_Rule_ID _marpa_g_ahm_irl (Marpa_Grammar G,
     Marpa_AHM_ID ITEM_ID)

 -- Function: int _marpa_g_ahm_position (Marpa_Grammar G,
     Marpa_AHM_ID ITEM_ID)

 -- Function: Marpa_Symbol_ID _marpa_g_ahm_postdot (Marpa_Grammar G,
     Marpa_AHM_ID ITEM_ID)

Recognizer internals
====================

 -- Function: int _marpa_r_is_use_leo (Marpa_Recognizer R)
 -- Function: int _marpa_r_is_use_leo_set ( Marpa_Recognizer R,
     int VALUE)
     Reports and sets, respectively, the ``use Leo'' flag. This flag controls whether Joop Leo's method for fast parsing of right recursion is used. By default, this value is 1 and Leo parsing is in use. This default should be used except for testing, debugging and development.

 -- Function: Marpa_Earley_Set_ID _marpa_r_trace_earley_set (Marpa_Recognizer R)

 -- Function: int _marpa_r_earley_set_size (Marpa_Recognizer r, Marpa_Earley_Set_ID SET_ID)

 -- Function: Marpa_Earleme _marpa_r_earley_set_trace (Marpa_Recognizer r, Marpa_Earley_Set_ID SET_ID)

 -- Function: Marpa_AHM_ID _marpa_r_earley_item_trace (Marpa_Recognizer r, Marpa_Earley_Item_ID ITEM_ID)

 -- Function: Marpa_Earley_Set_ID _marpa_r_earley_item_origin (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_leo_predecessor_symbol (Marpa_Recognizer R)

 -- Function: Marpa_Earley_Set_ID _marpa_r_leo_base_origin (Marpa_Recognizer R)

 -- Function: Marpa_AHM_ID _marpa_r_leo_base_state (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_postdot_symbol_trace (Marpa_Recognizer r, Marpa_Symbol_ID SYMID)

 -- Function: Marpa_Symbol_ID _marpa_r_first_postdot_item_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_next_postdot_item_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_postdot_item_symbol (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_first_token_link_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_next_token_link_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_first_completion_link_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_next_completion_link_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_first_leo_link_trace (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_next_leo_link_trace (Marpa_Recognizer R)

 -- Function: Marpa_AHM_ID _marpa_r_source_predecessor_state (Marpa_Recognizer R)

 -- Function: Marpa_Symbol_ID _marpa_r_source_token (Marpa_Recognizer r, int *VALUE_P)

 -- Function: Marpa_Symbol_ID _marpa_r_source_leo_transition_symbol (Marpa_Recognizer R)

 -- Function: Marpa_Earley_Set_ID _marpa_r_source_middle (Marpa_Recognizer R)

Bocage internals
================

 -- Function: int _marpa_b_and_node_count (
     Marpa_Bocage B)

 -- Function: Marpa_Earley_Set_ID _marpa_b_and_node_middle (
     Marpa_Bocage B,
     Marpa_And_Node_ID AND_NODE_ID)

 -- Function: int _marpa_b_and_node_parent (
     Marpa_Bocage B,
     Marpa_And_Node_ID AND_NODE_ID)

 -- Function: int _marpa_b_and_node_predecessor (
     Marpa_Bocage B,
     Marpa_And_Node_ID AND_NODE_ID)

 -- Function: int _marpa_b_and_node_cause (
     Marpa_Bocage B,
     Marpa_And_Node_ID AND_NODE_ID)

 -- Function: int _marpa_b_and_node_symbol (
     Marpa_Bocage B,
     Marpa_And_Node_ID AND_NODE_ID)

 -- Function: Marpa_Symbol_ID _marpa_b_and_node_token (
     Marpa_Bocage B,
     Marpa_And_Node_ID AND_NODE_ID,
     int* VALUE_P)

     Returns the data for the token of the and-node. The symbol id is the return value, and the token value is placed in the location pointed to by VALUE_P, if that is non-null. If AND_NODE_ID is not the ID of an and-node whose cause is a token, returns -1, without changing VALUE_P. On failure, returns -2 without changing VALUE_P.

     There is no function to simply return the token value -- because of the need to indicate errors, it is just as easy to return the symbol ID as well.

 -- Function: Marpa_Or_Node_ID _marpa_b_top_or_node (
     Marpa_Bocage B)

     Return the ID of the top or-node.

 -- Function: int _marpa_b_or_node_set (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

     Return the ordinal of the current (final) Earley set of the or-node.

 -- Function: int _marpa_b_or_node_origin (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: Marpa_IRL_ID _marpa_b_or_node_irl (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_b_or_node_position (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_b_or_node_is_whole (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_b_or_node_is_semantic (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_b_or_node_first_and (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_b_or_node_last_and (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_b_or_node_and_count (
     Marpa_Bocage B,
     Marpa_Or_Node_ID OR_NODE_ID)

Ordering internals
==================

 -- Function: Marpa_And_Node_ID _marpa_o_and_order_get (
     Marpa_Order O,
     Marpa_Or_Node_ID OR_NODE_ID,
     int IX)

 -- Function: int _marpa_o_or_node_and_node_count (
     Marpa_Order O,
     Marpa_Or_Node_ID OR_NODE_ID)

 -- Function: int _marpa_o_or_node_and_node_id_by_ix (
     Marpa_Order O,
     Marpa_Or_Node_ID OR_NODE_ID,
     int IX)

Tree internals
==============

In Marpa, a nook is any node of a parse tree. The usual term is "node", but within Marpa, the word "node" is already heavily overloaded. So what most texts call "tree nodes" are here called "nooks". "Nook" can be thought of as a pun on both "node" and "fork".

 -- Function: int _marpa_t_size (
     Marpa_Tree T)
     Return the size of the parse tree. This is the number of nooks in its stack. If there is a serious error, or if the tree is uninitialized, return -2. If the tree is exhausted, return -1.

 -- Function: Marpa_Or_Node_ID _marpa_t_nook_or_node (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID)

     Return the ID of the or-node for NOOK_ID.

 -- Function: int _marpa_t_nook_choice (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID
     )

     Return the current choice for NOOK_ID.

 -- Function: int _marpa_t_nook_parent (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID
     )

     Return the parent nook's ID for NOOK_ID. As with the other nook trace functions, -1 is returned if NOOK_ID is not the ID of a nook on the stack, but -1 can also be a valid value. If that's an issue, the NOOK_ID needs to be checked with one of the trace functions where -1 is never a valid value --- for example, _marpa_t_nook_or_node.

 -- Function: int _marpa_t_nook_cause_is_ready (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID
     )

     Return the cause-is-ready bit for NOOK_ID.

 -- Function: int _marpa_t_nook_predecessor_is_ready (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID
     )

     Return the predecessor-is-ready bit for NOOK_ID.

 -- Function: int _marpa_t_nook_is_cause (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID
     )

     Return the is-cause bit for NOOK_ID.

 -- Function: int _marpa_t_nook_is_predecessor (
     Marpa_Tree T,
     Marpa_Nook_ID NOOK_ID
     )

     Return the is-predecessor bit for NOOK_ID.

Valuator internals
==================

 -- Function: int _marpa_v_trace (
     Marpa_Value V,
     int FLAG)

 -- Function: Marpa_Nook_ID _marpa_v_nook (
     Marpa_Value V)

Debugging methods
=================

 -- Function: const char* _marpa_tag(void)
     Returns a ``tag'' value. This is to allow tagging the libraries with an completely arbitrary string identifier. independent even of the versioning mechanism. This allows debugging, for example, to determine which of two otherwise exactly identical libraries is in use.

 -- Function: int marpa_debug_level_set ( int LEVEL )

 -- Function: void marpa_debug_handler_set ( int (*DEBUG_HANDLER)(const char*, ...) )

GNU Free Documentation License
******************************

     [file fdl-1.3.texi not included]