\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: