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

@copying
This manual (@value{UPDATED})
is for 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 SLIF
@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 The Scanless interface (SLIF)
@insertcopying
@end ifnottex

@menu
* Copying::                     
* About this document::         
* About Libmarpa::              
* Architecture::                
* Input::                       
* Semantics::                   
* Threads::                     
* Fatal Errors::                
* Introduction to the external interface::  
* Static methods::              
* Configuration methods::       
* Grammar methods::             
* Recognizer methods::          
* Progress reports::            
* Bocage methods::              
* Ordering methods::            
* Tree methods::                
* Value methods::               
* Events::                      
* Error methods macros and codes::  
* Design notes::                
* Work in Progress::            
* GNU Free Documentation License::  

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

About this document

* How to read this document::   
* Prerequisites::               
* Parsing theory::              

Architecture

* Major objects::               
* Time objects::                
* Reference counting::          
* Numbered objects::            

Input

* Earlemes::                    
* Terminals::                   

Earlemes

* The traditional model::       
* The earleme variables::       
* The significances of the earleme variables::  
* The initial earleme settings::  
* The standard model of input::  
* Ambiguous input::             
* Variable length tokens::      
* The generalized model::       
* General rules for the earleme variables::  

Semantics

* How Libmarpa semantics work::  
* Valued and unvalued symbols::  

Introduction to the external interface

* About the overviews::         
* Return values::               
* Naming conventions::          

Grammar methods

* Grammar overview::            
* Grammar constructor::         
* Grammar reference counting::  
* Symbols::                     
* Rules::                       
* Sequences::                   
* Ranks::                       
* Grammar precomputation::      

Recognizer methods

* Recognizer overview::         
* Recognizer constructor::      
* Recognizer reference counting::  
* Recognizer life cycle mutators::  
* Location accessors::          
* Other parse status methods::  
* Untested recognizer methods::  

Bocage methods

* Bocage overview::             
* Bocage constructor::          
* Bocage reference counting::   
* Bocage accessor::             

Ordering methods

* Ordering overview::           
* Ordering constructor::        
* Ordering reference counting::  
* Order accessor::              
* Non-default ordering::        

Tree methods

* Tree overview::               
* Tree constructor::            
* Tree reference counting::     
* Tree iteration::              

Value methods

* Value overview::              
* How to use the valuator::     
* Advantages of step-driven valuation::  
* Maintaining the stack::       
* Valuator constructor::        
* Valuator reference counting::  
* Registering semantics::       
* Stepping through the valuator::  
* Valuator steps by type::      
* Basic step accessors::        
* Other step accessors::        

Maintaining the stack

* Sizing the stack::            
* Initializing locations in the stack::  

Events

* Events overview::             
* Event methods::               
* Event codes::                 

Error methods, macros and codes

* Error methods::               
* Error Macros::                
* External error codes::        
* Internal error codes::        

Design notes

* Why so many time objects::    
* Design of numbered objects::  
* LHS Terminals::               

Work in Progress

* Experimental methods::        
* Untested 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, About Libmarpa, Copying, Top
@chapter About this document

@menu
* How to read this document::   
* Prerequisites::               
* Parsing theory::              
@end menu

@node How to read this document, Prerequisites, About this document, About this document
@section How to read this document

This is essentially a reference document.

@node Prerequisites, Parsing theory, How to read this document, About this document
@section Prerequisites

This document is very far from self-contained.
It assumes the following:
@itemize
@item
The reader knows the C programming language
at least well
enough to understand function prototypes and return values.
@item
The reader
has read the documents for one of Libmarpa's upper layers.
As of this writing, the only such layer is @code{Marpa::R2}
or @code{Marpa::R3},
in Perl.
@item
The reader knows some parsing theory.
@xref{Parsing theory}.
@end itemize

@node Parsing theory,  , Prerequisites, About this document
@section Parsing theory

This document assumes some acquaintance
with parsing theory.
The reader's
level of knowledge is probably adequate
if he can
answer the following questions,
either immediately or after a little reflection.
@itemize @bullet
@item
What is a BNF rule?
@item
What is a Marpa sequence rule?
@item
As a reminder,
Marpa's sequence rules are implemented
as left recursions.
What does that mean?
@item
Take a Marpa sequence rule at random.
What does it look like when rewritten in BNF?
@item
What does the sequence look like when rewritten
in BNF as a right-recursion?
@end itemize

@node About Libmarpa, Architecture, About this document, Top
@chapter About the SLIF

This document is in draft, and this interface is alpha
and experimental.
Currently all methods begin with @code{marpa__} to indicate this.

The Scanless interface (SLIF) is a layser above
Libmarpa, which implements the Marpa parsing algorithm.
Marpa is named
after the legendary 11th century Tibetan translator,
Marpa Lotsawa.
In creating Marpa,
I depended heavily on previous work by Jay Earley,
Joop Leo,
John Aycock and Nigel Horspool.

The SLIF is a middle- or high-level interface.
It is intended for use directly from C or other languages.
However, layers may be added on top of the SLIF.

@node Untested methods,  , Experimental methods, Work in Progress
@section Methods

@deftypefun Marpa_SLR marpa__slr_new (void)

Return value: On success, the SLR object.
On failure, @code{NULL}.

@end deftypefun

@node Grammar reference counting, Symbols, Grammar constructor, Grammar methods
@section Tracking the reference count of the SLR

@deftypefun Marpa_SLR marpa__slr_ref (Marpa_SLR @var{slr})

Increases the reference count by 1.
Not needed by most applications.

Return value:
On success, the SLR object it was called with;
@code{NULL} on failure.

@end deftypefun

@deftypefun void marpa__slr_unref (Marpa_SLR @var{slr})
Decreases the reference count by 1,
destroying @var{slr} once the reference count reaches
zero.

@end deftypefun

@deftypefun void marpa__slr_event_clear( Marpa_SLR @var{slr} )
@end deftypefun

@deftypefun union marpa_slr_event_s * marpa__slr_event_push( Marpa_SLR @var{slr} )

Return value:
On success, the new event.
Never returns failure.

@end deftypefun

@deftypefun int marpa__slr_event_count( Marpa_SLR slr )
@end deftypefun

@deftypefun int marpa__slr_event_max_index( Marpa_SLR slr )
@end deftypefun

@deftypefun union marpa_slr_event_s * marpa__slr_event_entry( Marpa_SLR @var{slr}, int @var{i} )
@end deftypefun

@deftypefun void marpa__slr_lexeme_clear( Marpa_SLR @var{slr} )
@end deftypefun

@deftypefun union marpa_slr_event_s * marpa__slr_lexeme_push( Marpa_SLR @var{slr} )

Return value:
On success, the new event.
Never returns failure.

@end deftypefun

@deftypefun int marpa__slr_lexeme_count( Marpa_SLR slr )
@end deftypefun

@deftypefun union marpa_slr_event_s * marpa__slr_lexeme_entry( Marpa_SLR @var{slr}, int @var{i} )
@end deftypefun

@deftypefun int marpa__slif_op_id (const char* @var{op_name} )
@end deftypefun

@deftypefun const char* marpa__slif_op_name (Marpa_Op @var{op_id} )
@end deftypefun

@node GNU Free Documentation License,  , Work in Progress, Top
@appendix GNU Free Documentation License

@include fdl-1.3.texi

@bye
@c vim: expandtab shiftwidth=4:
