\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename internal.info
@include version_i.texi
@settitle Libmarpa @value{VERSION}
@finalout
@c %**end of header

@copying
This manual (@value{UPDATED})
is for the internals of Libmarpa @value{VERSION}.

Copyright @copyright{} 2014 Jeffrey Kegler.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{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
``@acronym{GNU} Free Documentation License.''
@end quotation
@end copying

@titlepage
@title Libmarpa internals
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Jeffrey Kegler
@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying

Published @value{UPDATED} by Jeffrey Kegler
@end titlepage
@c So the toc is printed at the start.
@contents

@ifnottex
@node Top, Copying, (dir), (dir)
@top Libmarpa internals
@insertcopying
@end ifnottex

@menu
* Copying::                     
* About this document::         
* Internal Interface::          
* GNU Free Documentation License::  

@detailmenu
 --- The Detailed Node Listing ---

Internal Interface

* Symbol internal methods::     
* Rule internals::              
* Grammar internals::           
* Recognizer internals::        
* Bocage internals::            
* Ordering internals::          
* Tree internals::              
* Valuator internals::          
* Debugging methods::           

@end detailmenu
@end menu

@node Copying, About this document, Top, Top
@unnumbered GNU LESSER GENERAL PUBLIC LICENSE
@include lgpl-3.0.texi

@node About this document, Internal Interface, Copying, Top
@chapter 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.

@node Internal Interface, GNU Free Documentation License, About this document, Top
@chapter 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''.

@menu
* Symbol internal methods::     
* Rule internals::              
* Grammar internals::           
* Recognizer internals::        
* Bocage internals::            
* Ordering internals::          
* Tree internals::              
* Valuator internals::          
* Debugging methods::           
@end menu

@node Symbol internal methods, Rule internals, Internal Interface, Internal Interface
@section Symbol internal methods

@deftypefun int _marpa_g_nsy_is_start ( Marpa_Grammar @var{g}, @
    Marpa_NSY_ID @var{nsy_id})
@end deftypefun
@deftypefun int _marpa_g_nsy_is_nulling ( @
  Marpa_Grammar @var{g}, @
  Marpa_NSY_ID @var{nsy_id})
@end deftypefun
@deftypefun int _marpa_g_nsy_is_lhs ( @
  Marpa_Grammar @var{g}, @
  Marpa_NSY_ID @var{nsy_id})
@end deftypefun
@deftypefun Marpa_NSY_ID _marpa_g_xsy_nulling_nsy ( @
    Marpa_Grammar @var{g}, @
    Marpa_Symbol_ID @var{symid})
@end deftypefun
@deftypefun Marpa_NSY_ID _marpa_g_xsy_nsy ( @
    Marpa_Grammar @var{g}, @
    Marpa_Symbol_ID @var{symid})
@end deftypefun
@deftypefun int _marpa_g_nsy_is_semantic ( @
  Marpa_Grammar @var{g}, @
  Marpa_NSY_ID @var{nsy_id})
@end deftypefun
@deftypefun Marpa_Rule_ID _marpa_g_source_xsy ( @
  Marpa_Grammar @var{g}, @
  Marpa_NSY_ID @var{nsy_id})
@end deftypefun
@deftypefun Marpa_Rule_ID _marpa_g_nsy_lhs_xrl ( @
  Marpa_Grammar @var{g}, @
  Marpa_NSY_ID @var{nsy_id})
@end deftypefun
@deftypefun int _marpa_g_nsy_xrl_offset ( @
  Marpa_Grammar @var{g}, @
  Marpa_NSY_ID @var{nsy_id} )
@end deftypefun

@node Rule internals, Grammar internals, Symbol internal methods, Internal Interface
@section Rule internals

@deftypefun int _marpa_g_rule_is_keep_separation ( @
    Marpa_Grammar @var{g}, @
    Marpa_Rule_ID @var{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
@var{rule_id} is not a sequence rule.
On failure, returns -2.
@end deftypefun

@deftypefun int _marpa_g_nsy_count ( @
  Marpa_Grammar @var{g})
@end deftypefun
@deftypefun int _marpa_g_irl_count ( @
  Marpa_Grammar @var{g})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_g_irl_lhs ( @
    Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
Return value: On success, the LHS symbol of the IRL.
On failure, -2.
@end deftypefun

@deftypefun int _marpa_g_irl_length ( @
    Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{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.
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_g_irl_rhs ( @
    Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id}, @
    int @var{ix})
The position in the IRL, @var{ix}, is zero-based.
If @var{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 @var{ix}
on the IRL's RHS.
If @var{ix} is greater than or equal to the length of
the IRL, -1.
On other failures, -2.
@end deftypefun
@deftypefun int _marpa_g_rule_is_used (Marpa_Grammar @var{g}, @
    Marpa_Rule_ID @var{rule_id})
@end deftypefun
@deftypefun int _marpa_g_irl_is_virtual_lhs (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun int _marpa_g_irl_is_virtual_rhs (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun @code{int} _marpa_g_virtual_start (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun @code{int} _marpa_g_virtual_end (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun Marpa_Rule_ID _marpa_g_source_xrl (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun int _marpa_g_real_symbol_count (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun Marpa_Rule_ID _marpa_g_irl_semantic_equivalent (Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun Marpa_Rank _marpa_g_irl_rank ( @
    Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{irl_id})
@end deftypefun
@deftypefun Marpa_Rank _marpa_g_nsy_rank ( @
    Marpa_Grammar @var{g}, @
    Marpa_IRL_ID @var{nsy_id})
@end deftypefun

@node Grammar internals, Recognizer internals, Rule internals, Internal Interface
@section 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
@cite{Marpa: The Program}.

@deftypefun int _marpa_g_ahm_count (Marpa_Grammar @var{g})
@end deftypefun
@deftypefun Marpa_Rule_ID _marpa_g_ahm_irl (Marpa_Grammar @var{g}, @
    Marpa_AHM_ID @var{item_id})
@end deftypefun
@deftypefun int _marpa_g_ahm_position (Marpa_Grammar @var{g}, @
    Marpa_AHM_ID @var{item_id})
@end deftypefun
@deftypefun Marpa_Symbol_ID _marpa_g_ahm_postdot (Marpa_Grammar @var{g}, @
    Marpa_AHM_ID @var{item_id})
@end deftypefun

@node Recognizer internals, Bocage internals, Grammar internals, Internal Interface
@section Recognizer internals


@deftypefun int _marpa_r_is_use_leo (Marpa_Recognizer @var{r})
@deftypefunx int _marpa_r_is_use_leo_set ( Marpa_Recognizer @var{r}, @
    int @var{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.
@end deftypefun

@deftypefun Marpa_Earley_Set_ID _marpa_r_trace_earley_set (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun int _marpa_r_earley_set_size (Marpa_Recognizer r, Marpa_Earley_Set_ID @var{set_id})
@end deftypefun

@deftypefun Marpa_Earleme _marpa_r_earley_set_trace (Marpa_Recognizer r, Marpa_Earley_Set_ID @var{set_id})
@end deftypefun

@deftypefun Marpa_AHM_ID _marpa_r_earley_item_trace (Marpa_Recognizer r, Marpa_Earley_Item_ID @var{item_id})
@end deftypefun

@deftypefun Marpa_Earley_Set_ID _marpa_r_earley_item_origin (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_leo_predecessor_symbol (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Earley_Set_ID _marpa_r_leo_base_origin (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_AHM_ID _marpa_r_leo_base_state (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_postdot_symbol_trace (Marpa_Recognizer r, Marpa_Symbol_ID @var{symid})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_first_postdot_item_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_next_postdot_item_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_postdot_item_symbol (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_first_token_link_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_next_token_link_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_first_completion_link_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_next_completion_link_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_first_leo_link_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_next_leo_link_trace (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_AHM_ID _marpa_r_source_predecessor_state (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_source_token (Marpa_Recognizer r, int *@var{value_p})
@end deftypefun

@deftypefun Marpa_Symbol_ID _marpa_r_source_leo_transition_symbol (Marpa_Recognizer @var{r})
@end deftypefun

@deftypefun Marpa_Earley_Set_ID _marpa_r_source_middle (Marpa_Recognizer @var{r})
@end deftypefun

@node Bocage internals, Ordering internals, Recognizer internals, Internal Interface
@section Bocage internals

@deftypefun int _marpa_b_and_node_count ( @
    Marpa_Bocage @var{b})
@end deftypefun
@deftypefun Marpa_Earley_Set_ID _marpa_b_and_node_middle ( @
    Marpa_Bocage @var{b}, @
    Marpa_And_Node_ID @var{and_node_id})
@end deftypefun
@deftypefun int _marpa_b_and_node_parent ( @
    Marpa_Bocage @var{b}, @
    Marpa_And_Node_ID @var{and_node_id})
@end deftypefun
@deftypefun int _marpa_b_and_node_predecessor ( @
    Marpa_Bocage @var{b}, @
    Marpa_And_Node_ID @var{and_node_id})
@end deftypefun
@deftypefun int _marpa_b_and_node_cause ( @
    Marpa_Bocage @var{b}, @
    Marpa_And_Node_ID @var{and_node_id})
@end deftypefun
@deftypefun int _marpa_b_and_node_symbol ( @
    Marpa_Bocage @var{b}, @
    Marpa_And_Node_ID @var{and_node_id})
@end deftypefun
@deftypefun Marpa_Symbol_ID _marpa_b_and_node_token ( @
    Marpa_Bocage @var{b}, @
    Marpa_And_Node_ID @var{and_node_id}, @
    int* @var{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 @var{value_p}, if that is non-null.
If @var{and_node_id} is not the ID of an and-node
whose cause is a token,
returns -1,
without changing @var{value_p}.
On failure, returns -2 without changing
@var{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.
@end deftypefun
@deftypefun Marpa_Or_Node_ID _marpa_b_top_or_node ( @
    Marpa_Bocage @var{b})

Return the ID of the top or-node.
@end deftypefun
@deftypefun int _marpa_b_or_node_set ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})

Return the ordinal of the current (final) Earley set of
the or-node.
@end deftypefun
@deftypefun int _marpa_b_or_node_origin ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun Marpa_IRL_ID _marpa_b_or_node_irl ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun int _marpa_b_or_node_position ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun int _marpa_b_or_node_is_whole ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun int _marpa_b_or_node_is_semantic ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun int _marpa_b_or_node_first_and ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun int _marpa_b_or_node_last_and ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun
@deftypefun int _marpa_b_or_node_and_count ( @
    Marpa_Bocage @var{b}, @
    Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun

@node Ordering internals, Tree internals, Bocage internals, Internal Interface
@section Ordering internals

@deftypefun Marpa_And_Node_ID _marpa_o_and_order_get ( @
    Marpa_Order @var{o}, @
    Marpa_Or_Node_ID @var{or_node_id}, @
    int @var{ix})
@end deftypefun

@deftypefun int _marpa_o_or_node_and_node_count ( @
  Marpa_Order @var{o}, @
  Marpa_Or_Node_ID @var{or_node_id})
@end deftypefun

@deftypefun int _marpa_o_or_node_and_node_id_by_ix ( @
  Marpa_Order @var{o}, @
  Marpa_Or_Node_ID @var{or_node_id}, @
  int @var{ix})
@end deftypefun

@node Tree internals, Valuator internals, Ordering internals, Internal Interface
@section 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".

@deftypefun int _marpa_t_size ( @
        Marpa_Tree @var{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.
@end deftypefun

@deftypefun Marpa_Or_Node_ID _marpa_t_nook_or_node ( @
    Marpa_Tree @var{t}, @
    Marpa_Nook_ID @var{nook_id})

Return the ID of the or-node for @var{nook_id}.
@end deftypefun

@deftypefun int _marpa_t_nook_choice ( @
        Marpa_Tree @var{t}, @
        Marpa_Nook_ID @var{nook_id} @
        )

Return the current choice for @var{nook_id}.
@end deftypefun

@deftypefun int _marpa_t_nook_parent ( @
        Marpa_Tree @var{t}, @
        Marpa_Nook_ID @var{nook_id} @
        )

Return the parent nook's ID for @var{nook_id}.
As with the other nook trace functions,
-1 is returned if @var{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 @var{nook_id} needs
to be checked with one of the trace functions
where -1 is never a valid value ---
for example, @code{_marpa_t_nook_or_node}.
@end deftypefun

@deftypefun int _marpa_t_nook_cause_is_ready ( @
        Marpa_Tree @var{t}, @
        Marpa_Nook_ID @var{nook_id} @
        )

Return the cause-is-ready bit for @var{nook_id}.
@end deftypefun

@deftypefun int _marpa_t_nook_predecessor_is_ready ( @
        Marpa_Tree @var{t}, @
        Marpa_Nook_ID @var{nook_id} @
        )

Return the predecessor-is-ready bit for @var{nook_id}.
@end deftypefun

@deftypefun int _marpa_t_nook_is_cause ( @
        Marpa_Tree @var{t}, @
        Marpa_Nook_ID @var{nook_id} @
        )

Return the is-cause bit for @var{nook_id}.
@end deftypefun

@deftypefun int _marpa_t_nook_is_predecessor ( @
        Marpa_Tree @var{t}, @
        Marpa_Nook_ID @var{nook_id} @
        )

Return the is-predecessor bit for @var{nook_id}.
@end deftypefun

@node Valuator internals, Debugging methods, Tree internals, Internal Interface
@section Valuator internals

@deftypefun int _marpa_v_trace ( @
    Marpa_Value @var{v}, @
    int @var{flag})
@end deftypefun

@deftypefun Marpa_Nook_ID _marpa_v_nook ( @
    Marpa_Value @var{v})
@end deftypefun

@node Debugging methods,  , Valuator internals, Internal Interface
@section Debugging methods

@deftypefun 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.
@end deftypefun

@deftypefun int marpa_debug_level_set ( int @var{level} )
@end deftypefun

@deftypefun void marpa_debug_handler_set ( int (*@var{debug_handler})(const char*, ...) )
@end deftypefun

@node GNU Free Documentation License,  , Internal Interface, Top
@appendix GNU Free Documentation License

@include fdl-1.3.texi

@bye

@c vim: expandtab shiftwidth=4: