<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual (23 June 2022)
is for Libmarpa 9.0.3.
Copyright (C) 2022 Jeffrey Kegler.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE. -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Libmarpa 9.0.3</title>
<meta name="description" content="Libmarpa 9.0.3">
<meta name="keywords" content="Libmarpa 9.0.3">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="#Top" rel="start" title="Top">
<link href="#Index-of-terms" rel="index" title="Index of terms">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="dir.html#Top" rel="up" title="(dir)">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<h1 class="settitle" align="center">Libmarpa 9.0.3</h1>
<a name="SEC_Contents"></a>
<h2 class="contents-heading">Table of Contents</h2>
<div class="contents">
<ul class="no-bullet">
<li><a name="toc-No-warranty-1" href="#No-warranty">1 No warranty</a></li>
<li><a name="toc-About-this-document-1" href="#About-this-document">2 About this document</a>
<ul class="no-bullet">
<li><a name="toc-How-to-read-this-document-1" href="#How-to-read-this-document">2.1 How to read this document</a></li>
<li><a name="toc-Prerequisites-1" href="#Prerequisites">2.2 Prerequisites</a></li>
<li><a name="toc-Parsing-theory-1" href="#Parsing-theory">2.3 Parsing theory</a></li>
<li><a name="toc-Terminology-and-notation-1" href="#Terminology-and-notation">2.4 Terminology and notation</a>
<ul class="no-bullet">
<li><a name="toc-Application-and-diagnostic-behavior-1" href="#Application-and-diagnostic-behavior">2.4.1 Application and diagnostic behavior</a></li>
</ul></li>
</ul></li>
<li><a name="toc-About-Libmarpa-1" href="#About-Libmarpa">3 About Libmarpa</a></li>
<li><a name="toc-Architecture-1" href="#Architecture">4 Architecture</a>
<ul class="no-bullet">
<li><a name="toc-Major-objects-1" href="#Major-objects">4.1 Major objects</a></li>
<li><a name="toc-Time-objects-1" href="#Time-objects">4.2 Time objects</a></li>
<li><a name="toc-Reference-counting-1" href="#Reference-counting">4.3 Reference counting</a></li>
<li><a name="toc-Numbered-objects-1" href="#Numbered-objects">4.4 Numbered objects</a></li>
</ul></li>
<li><a name="toc-Input-1" href="#Input">5 Input</a>
<ul class="no-bullet">
<li><a name="toc-Earlemes-1" href="#Earlemes">5.1 Earlemes</a>
<ul class="no-bullet">
<li><a name="toc-The-traditional-input-model-1" href="#The-traditional-input-model">5.1.1 The traditional input model</a></li>
<li><a name="toc-The-latest-earleme-1" href="#The-latest-earleme">5.1.2 The latest earleme</a></li>
<li><a name="toc-The-current-earleme-1" href="#The-current-earleme">5.1.3 The current earleme</a></li>
<li><a name="toc-The-furthest-earleme-1" href="#The-furthest-earleme">5.1.4 The furthest earleme</a></li>
</ul></li>
<li><a name="toc-The-basic-models-of-input-1" href="#The-basic-models-of-input">5.2 The basic models of input</a>
<ul class="no-bullet">
<li><a name="toc-The-standard-model-of-input-1" href="#The-standard-model-of-input">5.2.1 The standard model of input</a></li>
<li><a name="toc-Ambiguous-input-1" href="#Ambiguous-input">5.2.2 Ambiguous input</a></li>
</ul></li>
<li><a name="toc-Terminals-1" href="#Terminals">5.3 Terminals</a></li>
</ul></li>
<li><a name="toc-Exhaustion-1" href="#Exhaustion">6 Exhaustion</a></li>
<li><a name="toc-Semantics-1" href="#Semantics">7 Semantics</a></li>
<li><a name="toc-Threads-1" href="#Threads">8 Threads</a></li>
<li><a name="toc-Failure-1" href="#Failure">9 Failure</a>
<ul class="no-bullet">
<li><a name="toc-Libmarpa_0027s-approach-to-failure-1" href="#Libmarpa_0027s-approach-to-failure">9.1 Libmarpa’s approach to failure</a></li>
<li><a name="toc-User-non_002dconformity-to-specified-behavior-1" href="#User-non_002dconformity-to-specified-behavior">9.2 User non-conformity to specified behavior</a></li>
<li><a name="toc-Classifying-failure-1" href="#Classifying-failure">9.3 Classifying failure</a></li>
<li><a name="toc-Memory-allocation-failure-1" href="#Memory-allocation-failure">9.4 Memory allocation failure</a></li>
<li><a name="toc-Undetected-failure-1" href="#Undetected-failure">9.5 Undetected failure</a></li>
<li><a name="toc-Irrecoverable-hard-failure-1" href="#Irrecoverable-hard-failure">9.6 Irrecoverable hard failure</a></li>
<li><a name="toc-Partially-recoverable-hard-failure-1" href="#Partially-recoverable-hard-failure">9.7 Partially recoverable hard failure</a></li>
<li><a name="toc-Library_002drecoverable-hard-failure-1" href="#Library_002drecoverable-hard-failure">9.8 Library-recoverable hard failure</a></li>
<li><a name="toc-Fully-recoverable-hard-failure-1" href="#Fully-recoverable-hard-failure">9.9 Fully recoverable hard failure</a></li>
<li><a name="toc-Soft-failure-1" href="#Soft-failure">9.10 Soft failure</a></li>
<li><a name="toc-Error-codes-1" href="#Error-codes">9.11 Error codes</a></li>
</ul></li>
<li><a name="toc-Introduction-to-the-method-descriptions-1" href="#Introduction-to-the-method-descriptions">10 Introduction to the method descriptions</a>
<ul class="no-bullet">
<li><a name="toc-About-the-overviews-1" href="#About-the-overviews">10.1 About the overviews</a></li>
<li><a name="toc-Naming-conventions-1" href="#Naming-conventions">10.2 Naming conventions</a></li>
<li><a name="toc-Return-values-1" href="#Return-values">10.3 Return values</a></li>
<li><a name="toc-How-to-read-the-method-descriptions-1" href="#How-to-read-the-method-descriptions">10.4 How to read the method descriptions</a></li>
</ul></li>
<li><a name="toc-Static-methods-1" href="#Static-methods">11 Static methods</a></li>
<li><a name="toc-Configuration-methods-1" href="#Configuration-methods">12 Configuration methods</a></li>
<li><a name="toc-Grammar-methods-1" href="#Grammar-methods">13 Grammar methods</a>
<ul class="no-bullet">
<li><a name="toc-Overview" href="#Grammar-overview">13.1 Overview</a></li>
<li><a name="toc-Creating-a-new-grammar" href="#Grammar-constructor">13.2 Creating a new grammar</a></li>
<li><a name="toc-Tracking-the-reference-count-of-the-grammar" href="#Grammar-reference-counting">13.3 Tracking the reference count of the grammar</a></li>
<li><a name="toc-Symbol-methods-1" href="#Symbol-methods">13.4 Symbol methods</a></li>
<li><a name="toc-Rule-methods-1" href="#Rule-methods">13.5 Rule methods</a></li>
<li><a name="toc-Sequence-methods-1" href="#Sequence-methods">13.6 Sequence methods</a></li>
<li><a name="toc-Rank-methods-1" href="#Rank-methods">13.7 Rank methods</a></li>
<li><a name="toc-Precomputing-the-Grammar" href="#Grammar-precomputation">13.8 Precomputing the Grammar</a></li>
</ul></li>
<li><a name="toc-Recognizer-methods-1" href="#Recognizer-methods">14 Recognizer methods</a>
<ul class="no-bullet">
<li><a name="toc-Recognizer-overview-1" href="#Recognizer-overview">14.1 Recognizer overview</a></li>
<li><a name="toc-Creating-a-new-recognizer-1" href="#Creating-a-new-recognizer">14.2 Creating a new recognizer</a></li>
<li><a name="toc-Keeping-the-reference-count-of-a-recognizer" href="#Recognizer-reference-counting">14.3 Keeping the reference count of a recognizer</a></li>
<li><a name="toc-Life-cycle-mutators" href="#Recognizer-life-cycle-mutators">14.4 Life cycle mutators</a></li>
<li><a name="toc-Location-accessors-1" href="#Location-accessors">14.5 Location accessors</a></li>
<li><a name="toc-Other-parse-status-methods-1" href="#Other-parse-status-methods">14.6 Other parse status methods</a></li>
</ul></li>
<li><a name="toc-Progress-reports-1" href="#Progress-reports">15 Progress reports</a></li>
<li><a name="toc-Bocage-methods-1" href="#Bocage-methods">16 Bocage methods</a>
<ul class="no-bullet">
<li><a name="toc-Overview-1" href="#Bocage-overview">16.1 Overview</a></li>
<li><a name="toc-Creating-a-new-bocage" href="#Bocage-constructor">16.2 Creating a new bocage</a></li>
<li><a name="toc-Reference-counting-2" href="#Bocage-reference-counting">16.3 Reference counting</a></li>
<li><a name="toc-Accessors" href="#Bocage-accessor">16.4 Accessors</a></li>
</ul></li>
<li><a name="toc-Ordering-methods-1" href="#Ordering-methods">17 Ordering methods</a>
<ul class="no-bullet">
<li><a name="toc-Overview-2" href="#Ordering-overview">17.1 Overview</a></li>
<li><a name="toc-Creating-an-ordering" href="#Ordering-constructor">17.2 Creating an ordering</a></li>
<li><a name="toc-Reference-counting-3" href="#Ordering-reference-counting">17.3 Reference counting</a></li>
<li><a name="toc-Accessors-1" href="#Order-accessor">17.4 Accessors</a></li>
<li><a name="toc-Non_002ddefault-ordering-1" href="#Non_002ddefault-ordering">17.5 Non-default ordering</a></li>
</ul></li>
<li><a name="toc-Tree-methods-1" href="#Tree-methods">18 Tree methods</a>
<ul class="no-bullet">
<li><a name="toc-Overview-3" href="#Tree-overview">18.1 Overview</a></li>
<li><a name="toc-Creating-a-new-tree-iterator" href="#Tree-constructor">18.2 Creating a new tree iterator</a></li>
<li><a name="toc-Reference-counting-4" href="#Tree-reference-counting">18.3 Reference counting</a></li>
<li><a name="toc-Iterating-through-the-trees" href="#Tree-iteration">18.4 Iterating through the trees</a></li>
</ul></li>
<li><a name="toc-Value-methods-1" href="#Value-methods">19 Value methods</a>
<ul class="no-bullet">
<li><a name="toc-Overview-4" href="#Value-overview">19.1 Overview</a></li>
<li><a name="toc-How-to-use-the-valuator-1" href="#How-to-use-the-valuator">19.2 How to use the valuator</a></li>
<li><a name="toc-Advantages-of-step_002ddriven-valuation-1" href="#Advantages-of-step_002ddriven-valuation">19.3 Advantages of step-driven valuation</a></li>
<li><a name="toc-Maintaining-the-stack-1" href="#Maintaining-the-stack">19.4 Maintaining the stack</a>
<ul class="no-bullet">
<li><a name="toc-Sizing-the-stack-1" href="#Sizing-the-stack">19.4.1 Sizing the stack</a></li>
<li><a name="toc-Initializing-locations-in-the-stack-1" href="#Initializing-locations-in-the-stack">19.4.2 Initializing locations in the stack</a></li>
</ul></li>
<li><a name="toc-Creating-a-new-valuator" href="#Valuator-constructor">19.5 Creating a new valuator</a></li>
<li><a name="toc-Reference-counting-5" href="#Valuator-reference-counting">19.6 Reference counting</a></li>
<li><a name="toc-Stepping-through-the-valuator-1" href="#Stepping-through-the-valuator">19.7 Stepping through the valuator</a></li>
<li><a name="toc-Valuator-steps-by-type-1" href="#Valuator-steps-by-type">19.8 Valuator steps by type</a></li>
<li><a name="toc-Basic-step-accessors-1" href="#Basic-step-accessors">19.9 Basic step accessors</a></li>
<li><a name="toc-Other-step-accessors-1" href="#Other-step-accessors">19.10 Other step accessors</a></li>
</ul></li>
<li><a name="toc-Events-1" href="#Events">20 Events</a>
<ul class="no-bullet">
<li><a name="toc-Overview-5" href="#Events-overview">20.1 Overview</a></li>
<li><a name="toc-Basic-event-accessors-1" href="#Basic-event-accessors">20.2 Basic event accessors</a></li>
<li><a name="toc-Completion-events-1" href="#Completion-events">20.3 Completion events</a></li>
<li><a name="toc-Symbol-nulled-events-1" href="#Symbol-nulled-events">20.4 Symbol nulled events</a></li>
<li><a name="toc-Prediction-events-1" href="#Prediction-events">20.5 Prediction events</a></li>
<li><a name="toc-Symbol-expected-events-1" href="#Symbol-expected-events">20.6 Symbol expected events</a></li>
<li><a name="toc-Event-codes-1" href="#Event-codes">20.7 Event codes</a></li>
</ul></li>
<li><a name="toc-Error-methods_002c-macros-and-codes" href="#Error-methods-macros-and-codes">21 Error methods, macros and codes</a>
<ul class="no-bullet">
<li><a name="toc-Error-methods-1" href="#Error-methods">21.1 Error methods</a></li>
<li><a name="toc-Error-Macros-1" href="#Error-Macros">21.2 Error Macros</a></li>
<li><a name="toc-External-error-codes-1" href="#External-error-codes">21.3 External error codes</a></li>
<li><a name="toc-Internal-error-codes-1" href="#Internal-error-codes">21.4 Internal error codes</a></li>
</ul></li>
<li><a name="toc-Technical-notes-1" href="#Technical-notes">22 Technical notes</a>
<ul class="no-bullet">
<li><a name="toc-Data-types-used-by-Libmarpa-1" href="#Data-types-used-by-Libmarpa">22.1 Data types used by Libmarpa</a></li>
<li><a name="toc-Why-so-many-time-objects_003f" href="#Why-so-many-time-objects">22.2 Why so many time objects?</a></li>
<li><a name="toc-Numbered-objects-2" href="#Design-of-numbered-objects">22.3 Numbered objects</a></li>
<li><a name="toc-LHS-terminals" href="#LHS-Terminals">22.4 LHS terminals</a></li>
</ul></li>
<li><a name="toc-Advanced-input-models-1" href="#Advanced-input-models">23 Advanced input models</a>
<ul class="no-bullet">
<li><a name="toc-The-dense-variable_002dlength-token-model-1" href="#The-dense-variable_002dlength-token-model">23.1 The dense variable-length token model</a></li>
<li><a name="toc-The-fully-general-input-model-1" href="#The-fully-general-input-model">23.2 The fully general input model</a></li>
</ul></li>
<li><a name="toc-Futures-1" href="#Futures">24 Futures</a>
<ul class="no-bullet">
<li><a name="toc-Orthogonal-treatment-of-exhaustion-1" href="#Orthogonal-treatment-of-exhaustion">24.1 Orthogonal treatment of exhaustion</a></li>
<li><a name="toc-Furthest-earleme-values-1" href="#Furthest-earleme-values">24.2 Furthest earleme values</a></li>
<li><a name="toc-Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029-1" href="#Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029">24.3 Additional recoverable failures in marpa_r_alternative()</a></li>
<li><a name="toc-Untested-methods-1" href="#Untested-methods">24.4 Untested methods</a>
<ul class="no-bullet">
<li><a name="toc-Ranking-methods-1" href="#Ranking-methods">24.4.1 Ranking methods</a></li>
<li><a name="toc-Zero_002dwidth-assertion-methods-1" href="#Zero_002dwidth-assertion-methods">24.4.2 Zero-width assertion methods</a></li>
<li><a name="toc-Methods-for-revising-parses-1" href="#Methods-for-revising-parses">24.4.3 Methods for revising parses</a></li>
</ul></li>
</ul></li>
<li><a name="toc-Deprecated-techniques-and-methods-1" href="#Deprecated-techniques-and-methods">25 Deprecated techniques and methods</a>
<ul class="no-bullet">
<li><a name="toc-Valued-and-unvalued-symbols-1" href="#Valued-and-unvalued-symbols">25.1 Valued and unvalued symbols</a>
<ul class="no-bullet">
<li><a name="toc-What-unvalued-symbols-were-1" href="#What-unvalued-symbols-were">25.1.1 What unvalued symbols were</a></li>
<li><a name="toc-Grammar-methods-dealing-with-unvalued-symbols-1" href="#Grammar-methods-dealing-with-unvalued-symbols">25.1.2 Grammar methods dealing with unvalued symbols</a></li>
<li><a name="toc-Registering-semantics-in-the-valuator-1" href="#Registering-semantics-in-the-valuator">25.1.3 Registering semantics in the valuator</a></li>
</ul></li>
</ul></li>
<li><a name="toc-Index-of-terms-1" href="#Index-of-terms">Index of terms</a></li>
</ul>
</div>
<a name="Top"></a>
<div class="header">
<p>
Next: <a href="#No-warranty" accesskey="n" rel="next">No warranty</a>, Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Libmarpa_003a-The-Marpa-low_002dlevel-library"></a>
<h1 class="top">Libmarpa: The Marpa low-level library</h1>
<p>This manual (23 June 2022)
is for Libmarpa 9.0.3.
</p>
<p>Copyright © 2022 Jeffrey Kegler.
</p>
<a name="license"></a><blockquote>
<p>Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the “Software”),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
</p>
<p>The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
</p>
<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
</p></blockquote>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#No-warranty" accesskey="1">No warranty</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#About-this-document" accesskey="2">About this document</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#About-Libmarpa" accesskey="3">About Libmarpa</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Architecture" accesskey="4">Architecture</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Input" accesskey="5">Input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Exhaustion" accesskey="6">Exhaustion</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Semantics" accesskey="7">Semantics</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Threads" accesskey="8">Threads</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Failure" accesskey="9">Failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Introduction-to-the-method-descriptions">Introduction to the method descriptions</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Static-methods">Static methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Configuration-methods">Configuration methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-methods">Grammar methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Recognizer-methods">Recognizer methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Progress-reports">Progress reports</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-methods">Bocage methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ordering-methods">Ordering methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-methods">Tree methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Value-methods">Value methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Events">Events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Error-methods-macros-and-codes">Error methods macros and codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Technical-notes">Technical notes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Advanced-input-models">Advanced input models</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Futures">Futures</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Deprecated-techniques-and-methods">Deprecated techniques and methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Index-of-terms">Index of terms</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
</pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> — The Detailed Node Listing —
About this document
</pre></th></tr><tr><td align="left" valign="top">• <a href="#How-to-read-this-document">How to read this document</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Prerequisites">Prerequisites</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Parsing-theory">Parsing theory</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Terminology-and-notation">Terminology and notation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Terminology and notation
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Application-and-diagnostic-behavior">Application and diagnostic behavior</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Architecture
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Major-objects">Major objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Time-objects">Time objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Reference-counting">Reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Numbered-objects">Numbered objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Input
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Earlemes">Earlemes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-basic-models-of-input">The basic models of input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Terminals">Terminals</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Earlemes
</pre></th></tr><tr><td align="left" valign="top">• <a href="#The-traditional-input-model">The traditional input model</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-latest-earleme">The latest earleme</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-current-earleme">The current earleme</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-furthest-earleme">The furthest earleme</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
The basic models of input
</pre></th></tr><tr><td align="left" valign="top">• <a href="#The-standard-model-of-input">The standard model of input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ambiguous-input">Ambiguous input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Failure
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Libmarpa_0027s-approach-to-failure">Libmarpa's approach to failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Classifying-failure">Classifying failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Memory-allocation-failure">Memory allocation failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Undetected-failure">Undetected failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Irrecoverable-hard-failure">Irrecoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Partially-recoverable-hard-failure">Partially recoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Library_002drecoverable-hard-failure">Library-recoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Fully-recoverable-hard-failure">Fully recoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Soft-failure">Soft failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Error-codes">Error codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Introduction to the method descriptions
</pre></th></tr><tr><td align="left" valign="top">• <a href="#About-the-overviews">About the overviews</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Naming-conventions">Naming conventions</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Return-values">Return values</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#How-to-read-the-method-descriptions">How to read the method descriptions</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Grammar methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Grammar-overview">Grammar overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-constructor">Grammar constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-reference-counting">Grammar reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Symbol-methods">Symbol methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Rule-methods">Rule methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Sequence-methods">Sequence methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Rank-methods">Rank methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-precomputation">Grammar precomputation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Recognizer methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Recognizer-overview">Recognizer overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Creating-a-new-recognizer">Creating a new recognizer</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Recognizer-reference-counting">Recognizer reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Recognizer-life-cycle-mutators">Recognizer life cycle mutators</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Location-accessors">Location accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Other-parse-status-methods">Other parse status methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Bocage methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Bocage-overview">Bocage overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-constructor">Bocage constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-reference-counting">Bocage reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-accessor">Bocage accessor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Ordering methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Ordering-overview">Ordering overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ordering-constructor">Ordering constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ordering-reference-counting">Ordering reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Order-accessor">Order accessor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Non_002ddefault-ordering">Non-default ordering</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Tree methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Tree-overview">Tree overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-constructor">Tree constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-reference-counting">Tree reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-iteration">Tree iteration</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Value methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Value-overview">Value overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#How-to-use-the-valuator">How to use the valuator</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Advantages-of-step_002ddriven-valuation">Advantages of step-driven valuation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Maintaining-the-stack">Maintaining the stack</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Valuator-constructor">Valuator constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Valuator-reference-counting">Valuator reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Stepping-through-the-valuator">Stepping through the valuator</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Valuator-steps-by-type">Valuator steps by type</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Basic-step-accessors">Basic step accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Other-step-accessors">Other step accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Maintaining the stack
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Sizing-the-stack">Sizing the stack</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Initializing-locations-in-the-stack">Initializing locations in the stack</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Events
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Events-overview">Events overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Basic-event-accessors">Basic event accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Completion-events">Completion events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Symbol-nulled-events">Symbol nulled events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Prediction-events">Prediction events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Symbol-expected-events">Symbol expected events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Event-codes">Event codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Error methods, macros and codes
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Error-methods">Error methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Error-Macros">Error Macros</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#External-error-codes">External error codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Internal-error-codes">Internal error codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Technical notes
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Data-types-used-by-Libmarpa">Data types used by Libmarpa</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Why-so-many-time-objects">Why so many time objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Design-of-numbered-objects">Design of numbered objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#LHS-Terminals">LHS Terminals</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Advanced input models
</pre></th></tr><tr><td align="left" valign="top">• <a href="#The-dense-variable_002dlength-token-model">The dense variable-length token model</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-fully-general-input-model">The fully general input model</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Futures
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Orthogonal-treatment-of-exhaustion">Orthogonal treatment of exhaustion</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Furthest-earleme-values">Furthest earleme values</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029">Additional recoverable failures in marpa_r_alternative()</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Untested-methods">Untested methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Untested methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Ranking-methods">Ranking methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Zero_002dwidth-assertion-methods">Zero-width assertion methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Methods-for-revising-parses">Methods for revising parses</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Deprecated techniques and methods
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Valued-and-unvalued-symbols">Valued and unvalued symbols</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
Valued and unvalued symbols
</pre></th></tr><tr><td align="left" valign="top">• <a href="#What-unvalued-symbols-were">What unvalued symbols were</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-methods-dealing-with-unvalued-symbols">Grammar methods dealing with unvalued symbols</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Registering-semantics-in-the-valuator">Registering semantics in the valuator</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
</pre></th></tr></table>
<hr>
<a name="No-warranty"></a>
<div class="header">
<p>
Next: <a href="#About-this-document" accesskey="n" rel="next">About this document</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="No-warranty-1"></a>
<h2 class="chapter">1 No warranty</h2>
<p>The Libmarpa license takes precedence over the
statements in this document.
In particular, the license states
that Libmarpa is free software and has no warranty.
No statement in this document should be construed
as providing any kind of warranty.
</p>
<hr>
<a name="About-this-document"></a>
<div class="header">
<p>
Next: <a href="#About-Libmarpa" accesskey="n" rel="next">About Libmarpa</a>, Previous: <a href="#No-warranty" accesskey="p" rel="prev">No warranty</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="About-this-document-1"></a>
<h2 class="chapter">2 About this document</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#How-to-read-this-document" accesskey="1">How to read this document</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Prerequisites" accesskey="2">Prerequisites</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Parsing-theory" accesskey="3">Parsing theory</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Terminology-and-notation" accesskey="4">Terminology and notation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="How-to-read-this-document"></a>
<div class="header">
<p>
Next: <a href="#Prerequisites" accesskey="n" rel="next">Prerequisites</a>, Previous: <a href="#About-this-document" accesskey="p" rel="prev">About this document</a>, Up: <a href="#About-this-document" accesskey="u" rel="up">About this document</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-to-read-this-document-1"></a>
<h3 class="section">2.1 How to read this document</h3>
<p>This is essentially a reference document,
but its early chapters lay out concepts
essential to the others.
Readers will usually want to read the
chapters up and including
<a href="#Introduction-to-the-method-descriptions">Introduction to the method descriptions</a>
in order.
Otherwise, they should follow their interests.
</p>
<hr>
<a name="Prerequisites"></a>
<div class="header">
<p>
Next: <a href="#Parsing-theory" accesskey="n" rel="next">Parsing theory</a>, Previous: <a href="#How-to-read-this-document" accesskey="p" rel="prev">How to read this document</a>, Up: <a href="#About-this-document" accesskey="u" rel="up">About this document</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Prerequisites-1"></a>
<h3 class="section">2.2 Prerequisites</h3>
<p>This document is very far from self-contained.
It assumes the following:
</p><ul>
<li> The reader knows the C programming language
at least well
enough to understand function prototypes and return values.
</li><li> 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</code>
or <code>Marpa::R3</code>,
in Perl.
</li><li> The reader knows some parsing theory
(<a href="#Parsing-theory">Parsing theory</a>).
</li></ul>
<hr>
<a name="Parsing-theory"></a>
<div class="header">
<p>
Next: <a href="#Terminology-and-notation" accesskey="n" rel="next">Terminology and notation</a>, Previous: <a href="#Prerequisites" accesskey="p" rel="prev">Prerequisites</a>, Up: <a href="#About-this-document" accesskey="u" rel="up">About this document</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Parsing-theory-1"></a>
<h3 class="section">2.3 Parsing theory</h3>
<p>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.
</p><ul>
<li> What is a BNF rule?
</li><li> What is a Marpa sequence rule?
</li><li> As a reminder,
Marpa’s sequence rules are implemented
as left recursions.
What does that mean?
</li><li> Take a Marpa sequence rule at random.
What does it look like when rewritten in BNF?
</li><li> What does the sequence look like when rewritten
in BNF as a right-recursion?
</li></ul>
<hr>
<a name="Terminology-and-notation"></a>
<div class="header">
<p>
Previous: <a href="#Parsing-theory" accesskey="p" rel="prev">Parsing theory</a>, Up: <a href="#About-this-document" accesskey="u" rel="up">About this document</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Terminology-and-notation-1"></a>
<h3 class="section">2.4 Terminology and notation</h3>
<p>In this document,
</p><ul>
<li> A
<a name="index-value_002c-boolean"></a>
<a name="index-boolean"></a>
<a name="index-boolean-value"></a>
<em>boolean</em> value, or <em>boolean</em>,
is an integer which is 0 or 1.
</li><li> <a name="index-iff"></a>
<em>iff</em> abbreviates “if and only if”.
</li><li> <a name="index-application"></a>
<em>application</em> means an “application” of Libmarpa.
In this document,
a Libmarpa application is not necessarily an application program.
For our purposes, an “application”
might be another library which uses Libmarpa.
</li><li> <a name="index-max_0028x_002cy_0029"></a>
<code>max(x,y)</code> is the maximum of
<code>x</code> and <code>y</code>,
where <code>x</code> and <code>y</code> are two numbers.
</li><li> <a name="index-method"></a>
<em>Libmarpa method</em>, or just <em>method</em> means a C function
or a function-like macro of the Libmarpa library.
</li><li> <a name="index-user"></a>
<em>user</em> means a “user” of the Libmarpa library.
A user of the library is also a programmer,
so that in this documents, “user”
and “programmer” are essentially synonyms.
</li><li> <a name="index-we"></a>
<a name="index-us"></a>
<a name="index-our"></a>
<em>We</em> (and “us” and ”our”) refer to the authors.
As of this writing, there is a primary author,
but the plural is traditional, and our “we”
is intended to include the reader
and everyone
we are joining on the millenia-old voyage of discovery
into mathematics and language.
</li></ul>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Application-and-diagnostic-behavior" accesskey="1">Application and diagnostic behavior</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Application-and-diagnostic-behavior"></a>
<div class="header">
<p>
Previous: <a href="#Terminology-and-notation" accesskey="p" rel="prev">Terminology and notation</a>, Up: <a href="#Terminology-and-notation" accesskey="u" rel="up">Terminology and notation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Application-and-diagnostic-behavior-1"></a>
<h4 class="subsection">2.4.1 Application and diagnostic behavior</h4>
<p>An
<a name="index-application-behavior"></a>
<a name="index-behavior_002c-application"></a>
<em>application behavior</em>
is a behavior on which it is intended that
the design of applications
will be based.
Most of the behaviors specified in this document are application
behaviors.
We sometimes say that “applications may expect” a certain behavior
to emphasize that that behavior is an application behavior.
</p>
<p>After an irrecoverable failure, the behavior of a Libmarpa application
is undefined,
so that there are no behaviors which can be relied on for normal
application processing,
and therefore, there are no application behaviors.
In this circumstance,
some of the application behaviors become
diagnostic behaviors.
A
<a name="index-diagnostic-behavior"></a>
<a name="index-behavior_002c-diagnostic"></a>
<em>diagnostic behavior</em>
is a behavior which it is suggested
that the programmer may attempt in the face of an irrecoverable failure,
for testing, diagnostics and debugging.
They are hoped for, rather than expected,
and intended
to allow the programmer to deal with irrecoverable
failures as smoothly as possible.
(See <a href="#Failure">Failure</a>.)
</p>
<p>In this document,
a behavior is a diagnostic behavior only if that is specifically
indicated.
Applications should not be designed to rely
on diagnostics behaviors.
We sometimes say that “diagnostics may attempt” a certain behavior
to emphasize that that behavior is a diagnostic behavior.
</p>
<hr>
<a name="About-Libmarpa"></a>
<div class="header">
<p>
Next: <a href="#Architecture" accesskey="n" rel="next">Architecture</a>, Previous: <a href="#About-this-document" accesskey="p" rel="prev">About this document</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="About-Libmarpa-1"></a>
<h2 class="chapter">3 About Libmarpa</h2>
<p>Libmarpa 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.
</p>
<p>Libmarpa implements the entire Marpa algorithm.
This library does
the necessary grammar preprocessing, recognizes the input,
and produces parse trees.
It also supports the ordering, iteration
and evaluation of the parse
trees.
</p>
<p>Libmarpa is very low-level.
For example, it has no strings.
Rules, symbols, and token values are all represented
by integers.
This, of course, will not suffice for many applications.
Users will very often want
names for the symbols, non-integer values for
tokens, or both.
Typically, applications will use arrays to
translate Libmarpa’s integer ID’s to strings or other
values as required.
</p>
<p>Libmarpa also does <strong>not</strong> implement most of the semantics.
Libmarpa does have an evaluator (called a “valuator”),
but it does <strong>not</strong>
manipulate the stack directly.
Instead, Libmarpa,
based on its traversal of the parse tree,
passes optimized step by step stack manipulation
instructions to the upper layer.
These instructions indicate the token or rule involved,
and the proper location for the true token value or
the result of the rule evaluation.
For rule evaluations, the instructions include the stack location
of the arguments.
</p>
<p>Marpa requires most semantics to be
implemented in the application.
This allows the application total flexibility.
It also puts
the application is in a much better position to prevent errors,
to catch errors at runtime or,
failing all else,
to successfully debug the logic.
</p>
<hr>
<a name="Architecture"></a>
<div class="header">
<p>
Next: <a href="#Input" accesskey="n" rel="next">Input</a>, Previous: <a href="#About-Libmarpa" accesskey="p" rel="prev">About Libmarpa</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Architecture-1"></a>
<h2 class="chapter">4 Architecture</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Major-objects" accesskey="1">Major objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Time-objects" accesskey="2">Time objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Reference-counting" accesskey="3">Reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Numbered-objects" accesskey="4">Numbered objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Major-objects"></a>
<div class="header">
<p>
Next: <a href="#Time-objects" accesskey="n" rel="next">Time objects</a>, Previous: <a href="#Architecture" accesskey="p" rel="prev">Architecture</a>, Up: <a href="#Architecture" accesskey="u" rel="up">Architecture</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Major-objects-1"></a>
<h3 class="section">4.1 Major objects</h3>
<p>The classes of
Libmarpa’s object system fall into two types:
major and numbered.
These are the Libmarpa’s major classes,
in sequence.
</p>
<ul>
<li> Configuration:
A configuration object is
a thread-safe way to hold configuration variables,
as well as the return code from failed attempts
to create grammar objects.
</li><li> Grammar:
A grammar object contains rules and symbols,
with their properties.
</li><li> Recognizer:
A recognizer object reads input.
</li><li> Bocage:
A bocage object is a collection of
parse trees, as found by a recognizer.
Bocages are similar to parse forests.
</li><li> Ordering:
An ordering object
is an ordering of the trees
in a bocage.
</li><li> Tree:
A tree object is a bocage iterator.
</li><li> Value:
A value object is a tree iterator.
Iteration of tree using a value object
produces “steps”.
These “steps” are
instructions to
the application on how
to evaluate the semantics,
and how to manipulate the stack.
</li></ul>
<p>The major objects have one letter abbreviations,
which are used frequently.
These are, in the standard sequence,
</p>
<ul>
<li> Configuration: C
</li><li> Grammar: G
</li><li> Recognizer: R
</li><li> Bocage: B
</li><li> Ordering: O
</li><li> Tree: T
</li><li> Value: V
</li></ul>
<hr>
<a name="Time-objects"></a>
<div class="header">
<p>
Next: <a href="#Reference-counting" accesskey="n" rel="next">Reference counting</a>, Previous: <a href="#Major-objects" accesskey="p" rel="prev">Major objects</a>, Up: <a href="#Architecture" accesskey="u" rel="up">Architecture</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Time-objects-1"></a>
<h3 class="section">4.2 Time objects</h3>
<p>All of Libmarpa’s major classes,
except the configuration class,
are “time” classes.
Except for objects in the grammar class,
all time objects are created from another time
object.
Each time object is created from a time object
of the class before it in the sequence.
A recognizer cannot be created without a precomputed grammar;
a bocage cannot be created without a recognizer;
and so on.
</p>
<p>When one time object is used to create a second
time object,
the first time object is the
<a name="index-parent-objectparent-object-_0028of-a-time-object_0029"></a>
<em>parent object</em>
and the second time object is the
<a name="index-child-objectchild-object-_0028of-a-time-object_0029"></a>
<em>child object</em>.
For example, when a bocage is created from a
recognizer,
the recognizer is the parent object,
and the bocage is the child object.
</p>
<p>Grammars have no parent object.
Every other time object has exactly one parent object.
Value objects have no child objects.
All other time objects can have any number of children,
from zero up to a number determined by memory or
some other machine-determined limit.
</p>
<p>Every time object has a
<a name="index-base-grammarbase-grammar-_0028of-a-time-object_0029"></a>
<em>base grammar</em>.
A grammar object is its own base grammar.
The base grammar of a recognizer is the grammar
that it was created with.
The base grammar of any other time object is the base
grammar of its parent object.
For example,
the base grammar of a bocage is the base
grammar of the recognizer that it was created
with.
</p>
<hr>
<a name="Reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Numbered-objects" accesskey="n" rel="next">Numbered objects</a>, Previous: <a href="#Time-objects" accesskey="p" rel="prev">Time objects</a>, Up: <a href="#Architecture" accesskey="u" rel="up">Architecture</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reference-counting-1"></a>
<h3 class="section">4.3 Reference counting</h3>
<p>Every object in a “time” class
has its own, distinct, lifetime,
which is controlled by the object’s reference count.
Reference counting follows the usual practice.
Contexts which take a share of the
“ownership” of an object
increase the reference count by 1.
When a context relinquishes its share of
the ownership of an object, it decreases the reference
count by 1.
</p>
<p>Each class of time object has a “ref” and an “unref”
method, to be used by those contexts which need to
explicitly increment and decrement the reference count.
For example, the “ref” method for the grammar class is
<code>marpa_g_ref()</code>
and the “unref” method for the grammar class is
<code>marpa_g_unref()</code>.
</p>
<p>Time objects do not have explicit destructors.
When the reference count of a time object reaches
0, that time object is destroyed.
</p>
<p>Much of the necessary reference counting
is performed automatically.
The context calling the constructor of a time object
does not need to explicitly increase the reference
count, because
Libmarpa time objects are
always created with a reference count of 1.
</p>
<p>Child objects “own” their parents,
and when a child object is successfully created,
the reference count of its parent object is
automatically incremented to reflect this.
When a child object is destroyed, it
automatically decrements the reference count of its parent.
</p>
<p>In a typical application, a calling context needs only
to remember
to “unref” each time object that it creates,
once it is finished with that time object.
All other reference decrements and increments are taken
care of automatically.
The typical application never needs to explicitly
call one of the “ref” methods.
</p>
<p>More complex applications may find it convenient
to have one or more contexts share ownership of objects
created in another context.
These more complex situations
are the only cases in which the “ref” methods
will be needed.
</p>
<hr>
<a name="Numbered-objects"></a>
<div class="header">
<p>
Previous: <a href="#Reference-counting" accesskey="p" rel="prev">Reference counting</a>, Up: <a href="#Architecture" accesskey="u" rel="up">Architecture</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Numbered-objects-1"></a>
<h3 class="section">4.4 Numbered objects</h3>
<p>In addition to its major, “time” objects, Libmarpa also has
numbered objects.
Numbered objects do not have lifetimes of their own.
Every numbered object belongs to a time object,
and is destroyed with it.
Rules and symbols are numbered objects.
Tokens values are another class of numbered
objects.
</p>
<hr>
<a name="Input"></a>
<div class="header">
<p>
Next: <a href="#Exhaustion" accesskey="n" rel="next">Exhaustion</a>, Previous: <a href="#Architecture" accesskey="p" rel="prev">Architecture</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Input-1"></a>
<h2 class="chapter">5 Input</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Earlemes" accesskey="1">Earlemes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-basic-models-of-input" accesskey="2">The basic models of input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Terminals" accesskey="3">Terminals</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Earlemes"></a>
<div class="header">
<p>
Next: <a href="#The-basic-models-of-input" accesskey="n" rel="next">The basic models of input</a>, Previous: <a href="#Input" accesskey="p" rel="prev">Input</a>, Up: <a href="#Input" accesskey="u" rel="up">Input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Earlemes-1"></a>
<h3 class="section">5.1 Earlemes</h3>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#The-traditional-input-model" accesskey="1">The traditional input model</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-latest-earleme" accesskey="2">The latest earleme</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-current-earleme" accesskey="3">The current earleme</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-furthest-earleme" accesskey="4">The furthest earleme</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="The-traditional-input-model"></a>
<div class="header">
<p>
Next: <a href="#The-latest-earleme" accesskey="n" rel="next">The latest earleme</a>, Previous: <a href="#Earlemes" accesskey="p" rel="prev">Earlemes</a>, Up: <a href="#Earlemes" accesskey="u" rel="up">Earlemes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-traditional-input-model-1"></a>
<h4 class="subsection">5.1.1 The traditional input model</h4>
<p>In traditional Earley parsers, the concept of location is very simple.
Locations are numbered from 0 to <var>n</var>, where <var>n</var> is the length of
the input.
Every location has an Earley set, and vice versa.
Location 0 is the start location.
Every location after the start location has exactly one input token
associated with it.
</p>
<p>Some applications
do not fit this traditional input model —
natural language processing requires ambiguous tokens,
for example.
Libmarpa allows a wide variety of alternative input models.
</p>
<p>In Libmarpa a location is called a
<a name="index-earleme"></a>
<em>earleme</em>.
The number of an Earley set is the
<a name="index-ID-_0028of-an-Earley-set_0029"></a>
<em>ID of the Earley set</em>,
or its
<a name="index-ordinal-_0028of-an-Earley-set_0029"></a>
<em>ordinal</em>.
In the traditional model, the ordinal of an Earley set and
its earleme are always exactly the same, but in Libmarpa’s
advanced input models
the ordinal of an Earley set can be different from
its location (earleme).
</p>
<p>The important earleme values are
the latest earleme.
the current earleme, and
the furthest earleme.
Latest, current and furthest earleme,
when they have determinate values,
obey a lexical order in this sense:
The latest earleme is always at or before the current earleme,
and the current earleme is always at or before the furthest earleme.
</p>
<hr>
<a name="The-latest-earleme"></a>
<div class="header">
<p>
Next: <a href="#The-current-earleme" accesskey="n" rel="next">The current earleme</a>, Previous: <a href="#The-traditional-input-model" accesskey="p" rel="prev">The traditional input model</a>, Up: <a href="#Earlemes" accesskey="u" rel="up">Earlemes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-latest-earleme-1"></a>
<h4 class="subsection">5.1.2 The latest earleme</h4>
<p>The
<a name="index-Earley-set_002c-latest"></a>
<em>latest Earley set</em>
is the Earley set completed most recently.
This is initially the Earley set at location 0.
The latest Earley set is always the Earley set with the highest ordinal,
and the Earley set with the highest earleme location.
The
<a name="index-earleme_002c-latest"></a>
<em>latest earleme</em> is the earleme of the latest Earley set.
If there is an Earley set at the current earleme,
it is the latest Earley set and the latest earleme
is equal to the current earleme.
There is never an Earley set after the current earleme,
and therefore the latest Earley set is never after the
current earleme.
The <code>marpa_r_start input()</code> and
<code>marpa_r_earleme_complete()</code> methods
are only ones that change the latest earleme.
See <a href="#marpa_005fr_005fstart_005finput">marpa_r_start_input()</a> and
<a href="#marpa_005fr_005fearleme_005fcomplete">marpa_r_earleme_complete()</a>.
</p>
<p>The latest earleme is different from the current earleme if and only if
there is no Earley set at the current earleme.
A different end of parsing can be specified,
but by default, parsing is of the input
in the range
from earleme 0 to the latest earleme.
</p>
<hr>
<a name="The-current-earleme"></a>
<div class="header">
<p>
Next: <a href="#The-furthest-earleme" accesskey="n" rel="next">The furthest earleme</a>, Previous: <a href="#The-latest-earleme" accesskey="p" rel="prev">The latest earleme</a>, Up: <a href="#Earlemes" accesskey="u" rel="up">Earlemes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-current-earleme-1"></a>
<h4 class="subsection">5.1.3 The current earleme</h4>
<p>The
<a name="index-earleme_002c-current"></a>
<em>current earleme</em>
is the earleme that Libmarpa is currently working on.
More specifically, it is the one at which new tokens will <strong>start</strong>.
Since tokens are never zero length, a new token will always end after the
current earleme.
<code>marpa_r_start_input()</code>
initializes the current earleme to 0,
and every call to
<code>marpa_r_earleme_complete()</code>
advances the
current earleme by 1.
The <code>marpa_r_start input()</code> and
<code>marpa_r_earleme_complete()</code> methods
are only ones that change the current earleme.
See <a href="#marpa_005fr_005fstart_005finput">marpa_r_start_input()</a> and
<a href="#marpa_005fr_005fearleme_005fcomplete">marpa_r_earleme_complete()</a>.
</p>
<hr>
<a name="The-furthest-earleme"></a>
<div class="header">
<p>
Previous: <a href="#The-current-earleme" accesskey="p" rel="prev">The current earleme</a>, Up: <a href="#Earlemes" accesskey="u" rel="up">Earlemes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-furthest-earleme-1"></a>
<h4 class="subsection">5.1.4 The furthest earleme</h4>
<p>Loosely speaking,
the
<a name="index-earleme_002c-furthest"></a>
<em>furthest earleme</em>
is the furthest earleme reached by the parse.
More precisely,
it is the highest numbered
earleme at which a token ends
and is 0 if there are no tokens.
The furthest earleme is 0 when a recognizer is
created.
With every call to
<code>marpa_r_alternative()</code>, the end of the token
it adds is calculated.
A token ends at the earleme location <var>current</var>+<var>length</var>,
where <var>current</var> is the current earleme,
and <var>length</var> is the length of the newly added token.
If <code>old_f</code> is the furthest earleme before
a call to
<code>marpa_r_alternative()</code>,
the furthest earleme after the call
is <code>max(old_f, current+length)</code>.
The <code>marpa_r_new()</code> and
<code>marpa_r_alternative()</code> methods
are only ones that change the furthest earleme.
See <a href="#marpa_005fr_005fnew">marpa_r_new()</a> and
<a href="#marpa_005fr_005falternative">marpa_r_alternative()</a>.
</p>
<p>In the basic input models,
where every token has length 1,
calling
<code>marpa_r_earleme_complete()</code>
after each
<code>marpa_r_alternative()</code>
call is sufficient to process
all inputs,
and the furthest earleme’s value
can be typically be ignored.
In alternative input models,
where tokens have lengths greater than 1,
calling <code>marpa_r_earleme_complete()</code>
once after the last token
is read may not be enough to ensure that all tokens have been processed.
To ensure that all tokens have been processed,
an application must advance the current earleme
by calling
<code>marpa_r_earleme_complete()</code>,
until the current earleme is equal to the furthest earleme.
</p>
<hr>
<a name="The-basic-models-of-input"></a>
<div class="header">
<p>
Next: <a href="#Terminals" accesskey="n" rel="next">Terminals</a>, Previous: <a href="#Earlemes" accesskey="p" rel="prev">Earlemes</a>, Up: <a href="#Input" accesskey="u" rel="up">Input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-basic-models-of-input-1"></a>
<h3 class="section">5.2 The basic models of input</h3>
<p>For the purposes of presentation,
we (somewhat arbitrarily)
divide Libmarpa’s input models
into two groups:
basic and advanced.
In the
<a name="index-basic-models-of-input"></a>
<a name="index-models-of-input_002c-basic"></a>
<a name="index-input_002c-basic-models-of"></a>
<em>basic input models of input</em>,
every token is exactly one earleme long.
This implies that, in a basic model of input,
</p><ul>
<li> every token is the same length,
</li><li> the ordinal of an Earley set
will always be the same as its earleme location, and
</li><li> the latest earleme and the current earleme are always equal.
</li></ul>
<p>In the
<a name="index-advanced-models-of-input"></a>
<a name="index-models-of-input_002c-advanced"></a>
<a name="index-input_002c-advanced-models-of"></a>
<em>advanced models of input</em>,
tokens may have a length other than 1.
Most applications use the basic input models.
The details of the advanced models of input are
presented in a later chapter.
See <a href="#Advanced-input-models">Advanced input models</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#The-standard-model-of-input" accesskey="1">The standard model of input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ambiguous-input" accesskey="2">Ambiguous input</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="The-standard-model-of-input"></a>
<div class="header">
<p>
Next: <a href="#Ambiguous-input" accesskey="n" rel="next">Ambiguous input</a>, Previous: <a href="#The-basic-models-of-input" accesskey="p" rel="prev">The basic models of input</a>, Up: <a href="#The-basic-models-of-input" accesskey="u" rel="up">The basic models of input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-standard-model-of-input-1"></a>
<h4 class="subsection">5.2.1 The standard model of input</h4>
<p>In the standard model of input,
there is exactly one successful
<code>marpa_r_alternative()</code> call
immediately previous
to every
<code>marpa_r_earleme_complete()</code> call.
A <code>marpa_r_alternative()</code> call is
<a name="index-previous-_0028to-a-marpa_005fr_005fearleme_005fcomplete_0028_0029-call_0029_002c-immediately"></a>
<a name="index-immediately-previous-_0028to-a-marpa_005fr_005fearleme_005fcomplete_0028_0029-call_0029"></a>
<em>immediately previous</em> to a
<code>marpa_r_earleme_complete()</code> call
iff
that <code>marpa_r_earleme_complete()</code> call is
the first
<code>marpa_r_earleme_complete()</code> call after
the <code>marpa_r_alternative()</code> call.
</p>
<p>Recall that, since the standard model is
a basic model,
the token length in every successful call to <code>marpa_r_alternative()</code>
will be one.
For an input of length <var>n</var>, there will be
exactly <var>n</var> <code>marpa_r_earleme_complete()</code> calls,
and all but the last call
to <code>marpa_r_earleme_complete()</code>
must be successful.
</p>
<p>In the standard model,
after a successful call
to
<code>marpa_r_alternative()</code>,
if <var>c</var> is the value of the current earleme before the call,
</p><ul>
<li> the current earleme will remain unchanged and therefore
will be <var>c</var>; and
</li><li> the furthest earleme be <var>c</var>+1.
</li></ul>
<p>In the standard model,
a call to
<code>marpa_r_earleme_complete()</code>
follows a successful call of
<code>marpa_r_alternative()</code>,
so that the value of the furthest earleme before the call to
<code>marpa_r_earleme_complete()</code> will be <code>c+1</code>,
where <var>c</var> is the value of the current earleme.
After a successful call to
<code>marpa_r_earleme_complete()</code>,
</p><ul>
<li> the current earleme will be advanced to <code>c+1</code>; and
</li><li> the furthest earleme will be <var>c+1</var>, and therefore equal
to the current earleme.
</li></ul>
<p>Recall that, in the basic models of input,
the latest earleme is always equal to the current earleme.
</p>
<hr>
<a name="Ambiguous-input"></a>
<div class="header">
<p>
Previous: <a href="#The-standard-model-of-input" accesskey="p" rel="prev">The standard model of input</a>, Up: <a href="#The-basic-models-of-input" accesskey="u" rel="up">The basic models of input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Ambiguous-input-1"></a>
<h4 class="subsection">5.2.2 Ambiguous input</h4>
<p>We can loosen the standard model to
allow more than one successful call to
<code>marpa_r_alternative()</code>
immediately previous to each call to
<code>marpa_r_earleme_complete()</code>.
This change will mean that multiple tokens become possible
at each earleme —
in other words, that the input becomes ambiguous.
We continue to require that there be
at least one successful call to
<code>marpa_r_alternative()</code>
before each call to
<code>marpa_r_earleme_complete()</code>.
And we recall that,
since this is a basic input model,
all tokens must have a length of 1.
</p>
<p>In the ambiguous input model, the behavior of the current,
latest and furthest earlemes are exactly
as described for the standard model.
See <a href="#The-standard-model-of-input">The standard model of input</a>.
</p>
<hr>
<a name="Terminals"></a>
<div class="header">
<p>
Previous: <a href="#The-basic-models-of-input" accesskey="p" rel="prev">The basic models of input</a>, Up: <a href="#Input" accesskey="u" rel="up">Input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Terminals-1"></a>
<h3 class="section">5.3 Terminals</h3>
<p>A terminal symbol is a symbol which
may appear in the input.
Traditionally,
all LHS symbols, as well as
the start symbol, must be non-terminals.
This is Marpa’s behavior, by default.
</p>
<p>Marpa allows the user to eliminate the distinction
between terminals and non-terminals.
In this, it
differs from traditional parsers.
Libmarpa
can arrange for a terminal
to appear on the LHS of one or more rules,
or for a terminal to be the start symbol.
However,
since terminals can never be zero length,
it is a logical contradiction for a nulling
symbol to also be a terminal
and Marpa does not allow it.
</p>
<p>Token values are <code>int</code>’s.
Libmarpa does nothing with token values except accept
them from the application and return them during
parse evaluation.
</p>
<hr>
<a name="Exhaustion"></a>
<div class="header">
<p>
Next: <a href="#Semantics" accesskey="n" rel="next">Semantics</a>, Previous: <a href="#Input" accesskey="p" rel="prev">Input</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Exhaustion-1"></a>
<h2 class="chapter">6 Exhaustion</h2>
<p>A parse is
<a name="index-exhausted-parse"></a>
<a name="index-parse_002c-exhausted"></a>
<em>exhausted</em> when it cannot accept any further input.
A parse is
<a name="index-active-parse"></a>
<a name="index-parse_002c-active"></a>
<em>active</em> iff it is not exhausted.
For a parse to be exhausted,
the furthest earleme and the current earleme
must be equal.
However, the converse is not always the case:
if more tokens can be read at the current earleme,
then it is possible for
the furthest earleme and the current earleme
to be equal in an active parse.
</p>
<p>Parse exhaustion always has a location.
That is, if a parse is exhausted it is exhausted at some earleme location <code>X</code>.
If a parse is exhausted at location <code>X</code>, then
</p><ul>
<li> There may be valid parses at <code>X</code>.
</li><li> The parse was active at all locations earlier than <code>X</code>.
</li><li> There may be valid parses at locations before <code>X</code>.
</li><li> There will be no valid parses at locations after <code>X</code>.
</li><li> No tokens can start at location <code>X</code>.
</li><li> No tokens can end at a location after <code>X</code>.
</li><li> No tokens can start at any location after <code>X</code>.
</li><li> No tokens will be accepted by an exhausted parser.
It is an irrecoverable hard failure to call <code>marpa_r_alternative()</code>
after a parser has become exhausted.
</li><li> No Earley sets will be at any location after <code>X</code>.
</li><li> No earlemes are completed by, and no Earley sets are created by, an exhausted parser.
It is an irrecoverable hard failure to call <code>marpa_r_earleme_complete()</code>
after a parser has become exhausted.
</li></ul>
<p>Users sometimes assume that parse exhaustion means parse failure.
But other users sometimes assume that parse exhaustion means parse success.
For many grammars,
there are strong associations between parse exhaustion
and parse success,
but the strong association can go either way,
Both exhaustion-loving and exhaustion-hating
grammars are very common in
practical application.
</p>
<p>In an
<a name="index-exhaustion_002dhating-applications"></a>
<a name="index-applications_002c-exhaustion_002dhating"></a>
<em>exhaustion-hating</em>
application,
parse exhaustion typically means parse failure.
C programs, Perl scripts and most programming languages
are exhaustion-hating applications.
If a C program is well-formed,
it is always possible to read more input.
The same is true of a Perl program that does not have a <code>__DATA__</code> section.
</p>
<p>In an
<a name="index-exhaustion_002dloving-applications"></a>
<a name="index-applications_002c-exhaustion_002dloving"></a>
<em>exhaustion-loving</em>
application
parse exhaustion means parse success.
A toy example of an exhaustion-loving
application is the language consisting of balanced parentheses.
When the parentheses come into perfect balance the parse is exhausted,
because any further input would unbalance the brackets.
And the parse succeeds when the parentheses come into perfect balance.
Exhaustion means success.
Any language which balances start and end indicators will tend to
be exhaustion-loving.
HTML and XML, with their start and end tags, can be seen
as exhaustion-loving languages.
</p>
<p>One common form of exhaustion-loving parsing
occurs in lexers which look for longest matches.
Exhaustion will indicate that the longest match has been found.
</p>
<p>It is possible for a language to be
exhaustion-loving at some points
and exhaustion-hating at others.
We mentioned Perl’s <code>__DATA__</code> as a complication in a
basically exhaustion-hating language.
</p>
<p><code>marpa_r_earleme_complete()</code> and
<code>marpa_r_start_input</code> are the only methods
that may encounter parse exhaustion.
See <a href="#marpa_005fr_005fearleme_005fcomplete">marpa_r_earleme_complete()</a> and
<a href="#marpa_005fr_005fstart_005finput">marpa_r_start_input()</a>.
When the <code>marpa_r_start_input</code> or
<code>marpa_r_earleme_complete()</code> methods
exhaust the parse,
they generate a <code>MARPA_EVENT_EXHAUSTED</code> event.
Applications
can also query
parse exhaustion status directly
with the
<code>marpa_r_is_exhausted()</code> method.
See <a href="#marpa_005fr_005fis_005fexhausted">marpa_r_is_exhausted()</a>.
</p>
<hr>
<a name="Semantics"></a>
<div class="header">
<p>
Next: <a href="#Threads" accesskey="n" rel="next">Threads</a>, Previous: <a href="#Exhaustion" accesskey="p" rel="prev">Exhaustion</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Semantics-1"></a>
<h2 class="chapter">7 Semantics</h2>
<p>Libmarpa handling of semantics is unusual.
Most semantics are left up to the application,
but Libmarpa guides them.
Specifically, the application is expected to maintain the evaluation
stack.
Libmarpa’s valuator provides instructions on how to handle the stack.
Libmarpa’s stack handling instructions
are called “steps”.
For example, a Libmarpa step might tell the application that the value
of a token needs to go into a certain stack position.
Or a Libmarpa step might tell the application that a rule is to be evaluated.
For rule evalution, Libmarpa will tell the application where the operands
are to be found,
and where the result must go.
</p>
<p>The detailed discussion of
Libmarpa’s handling of semantics is in the reference chapters
of this document,
under the appropriate methods and classes.
The most extensive discussion of the semantics
is in the section that deals with the methods of the value time class
(<a href="#Value-methods">Value methods</a>).
</p>
<hr>
<a name="Threads"></a>
<div class="header">
<p>
Next: <a href="#Failure" accesskey="n" rel="next">Failure</a>, Previous: <a href="#Semantics" accesskey="p" rel="prev">Semantics</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Threads-1"></a>
<h2 class="chapter">8 Threads</h2>
<p>Libmarpa is thread-safe,
given circumstances as described below.
The Libmarpa methods are not reentrant.
</p>
<p>Libmarpa is C89-compliant.
It uses no global data,
and calls only the routines
that are defined in the C89 standard
and that can be made thread-safe.
In most modern implementations,
the default C89 implementation is thread-safe
to the extent possible.
But the C89 standard does not require thread-safety,
and even most modern environments allow the user
to turn thread safety off.
To be thread-safe, Libmarpa must be compiled
and linked in an environment that provides
thread-safety.
</p>
<p>While Libmarpa can be used safely across
multiple threads,
a Libmarpa grammar cannot be.
Further, a Libmarpa time object can
only be used safely in the same thread
as its base grammar.
This is because all
time objects with the same base grammar share data
from that base grammar.
</p>
<p>To work around this limitation,
the same grammar definition can be
used to a create a new
Libmarpa grammar
time object in each thread.
If there is sufficient interest, future versions of
Libmarpa could allow thread-safe
cloning of grammars and other
time objects.
</p>
<hr>
<a name="Failure"></a>
<div class="header">
<p>
Next: <a href="#Introduction-to-the-method-descriptions" accesskey="n" rel="next">Introduction to the method descriptions</a>, Previous: <a href="#Threads" accesskey="p" rel="prev">Threads</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Failure-1"></a>
<h2 class="chapter">9 Failure</h2>
<p>As a reminder,
no language in this chapter
(or, for that matter, in this document)
should be read as providing,
or suggesting the existence of,
a warranty.
See <a href="#license">license</a>.
Also, see <a href="#No-warranty">No warranty</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Libmarpa_0027s-approach-to-failure" accesskey="1">Libmarpa's approach to failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#User-non_002dconformity-to-specified-behavior" accesskey="2">User non-conformity to specified behavior</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Classifying-failure" accesskey="3">Classifying failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Memory-allocation-failure" accesskey="4">Memory allocation failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Undetected-failure" accesskey="5">Undetected failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Irrecoverable-hard-failure" accesskey="6">Irrecoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Partially-recoverable-hard-failure" accesskey="7">Partially recoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Library_002drecoverable-hard-failure" accesskey="8">Library-recoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Fully-recoverable-hard-failure" accesskey="9">Fully recoverable hard failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Soft-failure">Soft failure</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Error-codes">Error codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Libmarpa_0027s-approach-to-failure"></a>
<div class="header">
<p>
Next: <a href="#User-non_002dconformity-to-specified-behavior" accesskey="n" rel="next">User non-conformity to specified behavior</a>, Previous: <a href="#Failure" accesskey="p" rel="prev">Failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Libmarpa_0027s-approach-to-failure-1"></a>
<h3 class="section">9.1 Libmarpa’s approach to failure</h3>
<p>Libmarpa is a C language library,
and inherits the traditional C language approach to
avoiding and handling user programming errors.
This approach will strike readers unfamiliar with this
tradition as putting an appallingly large
portion of the burden of avoiding application
programmer error
on the application programmer themself.
</p>
<p>But in the early 1970’s, when the C language first stabilized,
the alternative,
and the consensus choice for its target applications
was assembly language.
In that context, C was radical in its willingness to
incur a price in efficiency in order to protect the programmer
from themself.
C was considered to take a excessively "hand holding"
approach which very much flew in the face of consensus.
</p>
<p>The decades have made a large difference in the trade-offs,
and the consensus about the degree to which even a
low-level language should protect the user has changed.
It seems inevitable that C will be replaced as the low-level
language of choice, by a language which places
fewer burdens on the programmer,
and more on the machine.
The question seems to be not whether C will be dethroned
as the “go to” language for low-level progamming,
but when, and by which alternative.
</p>
<p>Modern hardware makes many simple checks essentially cost-free,
and Libmarpa’s efforts to protect the application programmer go well
beyond what
would have been considered best practice in the past.
But it remains a C language library.
But, on the whole, the Libmarpa application programmer must be prepared to exercise
the high degree of carefulness traditionally required by its C language environment.
Libmarpa
places the burden of avoiding irrecoverable failures,
and of handling recoverable failures,
largely on the application programmer.
</p>
<hr>
<a name="User-non_002dconformity-to-specified-behavior"></a>
<div class="header">
<p>
Next: <a href="#Classifying-failure" accesskey="n" rel="next">Classifying failure</a>, Previous: <a href="#Libmarpa_0027s-approach-to-failure" accesskey="p" rel="prev">Libmarpa's approach to failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="User-non_002dconformity-to-specified-behavior-1"></a>
<h3 class="section">9.2 User non-conformity to specified behavior</h3>
<p>This document specifies many behaviors
for Libmarpa application programs to follow,
such as the nature of the arguments to each method.
The C language environment specifies
many more behaviors,
such as proper memory management.
When a non-conformity to specified behavior is unintentional
and problematic,
it is frequently called a “bug”.
Even the most carefully programmed Libmarpa application may sometimes
contain a “bug”.
In addition, some specified behaviors are explicitly stated as characterizing
a primary branch of the processing,
rather than made mandatory for all successful processing.
Non-conformity to non-mandatory behaviors can be efficiently recoverable,
and is often intentional.
</p>
<p>This chapter describes how
non-conformity to specified behavior
by a Libmarpa application
is handled by Libmarpa.
Non-conformity to specified behavior
by a Libmarpa application
is also called, for the purposes of this document,
a
<a name="index-Libmarpa-application-programming-failure"></a>
<a name="index-failure_002c-Libmarpa-application-programming"></a>
<a name="index-failure"></a>
<em>Libmarpa application programming failure</em>.
In contexts where no ambiguity arises,
<em>Libmarpa application programming failure</em>
will
usually be abbreviated to
<em>failure</em>.
</p>
<a name="index-Libmarpa-application-programming-success"></a>
<a name="index-success_002c-Libmarpa-application-programming"></a>
<a name="index-success"></a>
<p><em>Libmarpa application programming success</em>
in a context
is defined as the absence of unrecovered failure in that context.
When no ambiguity arises,
<em>Libmarpa application programming success</em>
is almost
always abbreviated to
<em>success</em>.
For example, the success of an application means the application
ran without any irrecoverable failures,
and that it recovered from all the recoverable failures that were detected.
</p>
<hr>
<a name="Classifying-failure"></a>
<div class="header">
<p>
Next: <a href="#Memory-allocation-failure" accesskey="n" rel="next">Memory allocation failure</a>, Previous: <a href="#User-non_002dconformity-to-specified-behavior" accesskey="p" rel="prev">User non-conformity to specified behavior</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Classifying-failure-1"></a>
<h3 class="section">9.3 Classifying failure</h3>
<p>A Libmarpa application programming failure,
unless specified otherwise,
is an irrecoverable failure.
Once an irrecoverable failure has occurred,
the further behavior of the program is undefined.
Nonetheless, we specify,
and Libmarpa attempts,
diagnostics behaviors
(see <a href="#Application-and-diagnostic-behavior">Application and diagnostic behavior</a>)
in an effort to handle irrecoverable failures as
smoothly as possible.
</p>
<p>A Libmarpa application programming failure
is recoverable if and only if it is specified as such.
</p>
<p>A failure is called a
<a name="index-hard-failure"></a>
<a name="index-failure_002c-hard"></a>
<em>hard failure</em>
is it has an error code
associated with it.
A recoverable failure is called a
<a name="index-soft-failure"></a>
<a name="index-failure_002c-soft"></a>
<em>soft failure</em>
if it has no associated error code.
(For more on error codes, see <a href="#Error-codes">Error codes</a>.)
</p>
<p>All failures fall into one of five types.
In order of severity, these are
</p><ul>
<li> <strong>memory allocation failures</strong>,
</li><li> <strong>undetected failures</strong>,
</li><li> <strong>irrecoverable hard failures</strong>,
</li><li> <strong>partially recoverable hard failures</strong>, and
</li><li> <strong>fully recoverable hard failures</strong>, and
</li><li> <strong>soft failures</strong>.
</li></ul>
<hr>
<a name="Memory-allocation-failure"></a>
<div class="header">
<p>
Next: <a href="#Undetected-failure" accesskey="n" rel="next">Undetected failure</a>, Previous: <a href="#Classifying-failure" accesskey="p" rel="prev">Classifying failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Memory-allocation-failure-1"></a>
<h3 class="section">9.4 Memory allocation failure</h3>
<p>Failure to allocate memory is the most irrecoverable of irrecoverable
errors.
Even effective error handling assumes the ability to allocate memory,
so that the practice has been, in the event of a memory allocation failure,
to take Draconian action.
On
<a name="index-memory-allocation-failur"></a>
<a name="index-failure_002c-memory-allocation"></a>
<em>memory allocation failure</em>,
as with all irrecoverable failures,
Libmarpa’s behavior in undefined,
but Libmarpa attempts to terminate the current program abnormally by calling <code>abort()</code>.
</p>
<p>Memory allocation failure is the only case in which Libmarpa
terminates the program.
In all other cases,
Libmarpa leaves the decision to terminate the program,
whether normally or abnormally,
up to the application programmer.
</p>
<p>Memory allocation failure does not have an error code.
As a pedantic matter, memory allocation failure
is neither a hard or a soft failure.
</p>
<hr>
<a name="Undetected-failure"></a>
<div class="header">
<p>
Next: <a href="#Irrecoverable-hard-failure" accesskey="n" rel="next">Irrecoverable hard failure</a>, Previous: <a href="#Memory-allocation-failure" accesskey="p" rel="prev">Memory allocation failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Undetected-failure-1"></a>
<h3 class="section">9.5 Undetected failure</h3>
<p>An
<a name="index-undetected-failure"></a>
<a name="index-failure_002c-undetected"></a>
<em>undetected failure</em> is a failure that the Libmarpa
library does not detect.
Many failures are impossible or impractical
for a C library to detect.
Two examples of failure that the Libmarpa methods do not detect
are writes outside the bounds of allocated memory,
and use of memory after it has been freed.
C is not strongly typed, and arguments
of Libmarpa routines undergo only a few simple tests,
tests which are inadequate to detect many of the potential problems.
</p>
<p>By undetected failure we emphasize that we mean failures undetected
<strong>by the Libmarpa methods</strong>.
In the examples just given,
there exist tools that can help the programmer
detect memory errors
and other tools exist
to check the sanity of method arguments.
</p>
<p>This document points out some of the potentially undetected problems,
when doing so seems more helpful than tedious.
But any attempt to list all the undetected problems would be too large
and unwieldy to be useful.
</p>
<p>Undetected failure is always irrecoverable.
An undetected failure
is neither a hard or a soft failure.
</p>
<hr>
<a name="Irrecoverable-hard-failure"></a>
<div class="header">
<p>
Next: <a href="#Partially-recoverable-hard-failure" accesskey="n" rel="next">Partially recoverable hard failure</a>, Previous: <a href="#Undetected-failure" accesskey="p" rel="prev">Undetected failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Irrecoverable-hard-failure-1"></a>
<h3 class="section">9.6 Irrecoverable hard failure</h3>
<p>An
<a name="index-irrecoverable-hard-failure"></a>
<a name="index-hard-failure_002c-irrecoverable"></a>
<a name="index-failure_002c-irrecoverable-hard"></a>
<em>irrecoverable hard failure</em>
is
an irrecoverable Libmarpa application programming failure that has an
error code associated with it.
Libmarpa attempts to behave as predictably as possible
in the face of a hard failure,
but once an irrecoverable failure occurs,
the behavior of a Libmarpa application is undefined.
</p>
<p>In the event of an irrecoverable failure,
there are no application behaviors.
The diagnostic behavior for a hard failure is as described
for the method which detects the hard failure.
At a minimum, this diagnostic behavior will be returning from
the method which detects the hard failure with the return
value specified for hard failure,
and setting the error code as specified for hard failure.
</p>
<hr>
<a name="Partially-recoverable-hard-failure"></a>
<div class="header">
<p>
Next: <a href="#Library_002drecoverable-hard-failure" accesskey="n" rel="next">Library-recoverable hard failure</a>, Previous: <a href="#Irrecoverable-hard-failure" accesskey="p" rel="prev">Irrecoverable hard failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Partially-recoverable-hard-failure-1"></a>
<h3 class="section">9.7 Partially recoverable hard failure</h3>
<p>A
<a name="index-partially-recoverable-hard-failure"></a>
<a name="index-hard-failure_002c-partially-recoverable"></a>
<a name="index-failure_002c-partially-recoverable-hard"></a>
<em>partially recoverable hard failure</em>
is
a recoverable Libmarpa application programming failure
</p><ul>
<li> that has an error code associated with it; and
</li><li> after which some, but not all, of the
application behaviors remain available to the programmer.
</li></ul>
<p>For every partially recoverable hard failure,
this document specifies the application behaviors that remain
available after it occurs.
The most common kind of
partially recoverable hard failure is a
library-recoverable hard failure.
For an example of
partially recoverable hard failure,
see <a href="#Library_002drecoverable-hard-failure">Library-recoverable hard failure</a>.
</p>
<hr>
<a name="Library_002drecoverable-hard-failure"></a>
<div class="header">
<p>
Next: <a href="#Fully-recoverable-hard-failure" accesskey="n" rel="next">Fully recoverable hard failure</a>, Previous: <a href="#Partially-recoverable-hard-failure" accesskey="p" rel="prev">Partially recoverable hard failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Library_002drecoverable-hard-failure-1"></a>
<h3 class="section">9.8 Library-recoverable hard failure</h3>
<p>A
<a name="index-library_002drecoverable-hard-failure"></a>
<a name="index-hard-failure_002c-library_002drecoverable"></a>
<a name="index-failure_002c-library_002drecoverable-hard"></a>
<em>library-recoverable hard failure</em>
is a type of partially recoverable hard failure.
Loosely described, it is a hard failure which
allows the programmer to continue to use many
of the Libmarpa methods in the library,
but which disallows certain methods on some objects.
</p>
<p>To state the restrictions of application behaviors
more precisely, let
the “failure grammar” be the base grammar
of the method which detected the library-recoverable hard failure.
After a library-recoverable hard failure,
the following behaviors are no longer applcation
behaviors:
</p><ul>
<li> Libmarpa mutator and constructor method calls where the base grammar is the
failure grammar.
</li></ul>
<p>Recall that any use of a behavior which is not an application
behavior is an irrecoverable failure.
</p>
<p>The application behaviors
remaining after a library-recoverable hard failure
are the following:
</p><ul>
<li> All Libmarpa accessor method calls, even those whose base
grammar is the failure grammar.
</li><li> All Libmarpa destructor method calls, even those whose base
grammar is the failure grammar.
An application will often want to destroy all Libmarpa objects
whose base grammar is the failure grammar,
in order to clear memory of unusable objects.
</li><li> All Libmarpa mutator and constructor method calls,
except those whose base grammar is the failure grammar.
</li><li> All Libmarpa static method calls.
</li><li> All use of non-Libmarpa interfaces, including other libraries
and the C language environment.
</li></ul>
<p>An example of a library-recoverable hard failure is
the <code>MARPA_ERR_COUNTED_NULLABLE</code> error
in the <code>marpa_g_precompute</code> method.
See <a href="#marpa_005fg_005fprecompute">marpa_g_precompute()</a>.
</p>
<hr>
<a name="Fully-recoverable-hard-failure"></a>
<div class="header">
<p>
Next: <a href="#Soft-failure" accesskey="n" rel="next">Soft failure</a>, Previous: <a href="#Library_002drecoverable-hard-failure" accesskey="p" rel="prev">Library-recoverable hard failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Fully-recoverable-hard-failure-1"></a>
<h3 class="section">9.9 Fully recoverable hard failure</h3>
<p>A
<a name="index-fully-recoverable-hard-failure"></a>
<a name="index-hard-failure_002c-fully-recoverable"></a>
<a name="index-failure_002c-fully-recoverable-hard"></a>
<em>fully recoverable hard failure</em>
is
a recoverable Libmarpa application programming failure
</p><ul>
<li> that has an error code associated with it; and
</li><li> after which all of the
application behaviors remain available to the programmer.
</li></ul>
<p>One example of a fully recoverable hard failure is
the error code <code>MARPA_ERR_UNEXPECTED_TOKEN_ID</code>.
The “Ruby Slippers” parsing technique
(see <a href="#Ruby-Slippers">Ruby Slippers</a>),
which has seen extensive usage,
is based
on Libmarpa’s ability to recover from
a <code>MARPA_ERR_UNEXPECTED_TOKEN_ID</code> error
fully and efficiently,
</p>
<hr>
<a name="Soft-failure"></a>
<div class="header">
<p>
Next: <a href="#Error-codes" accesskey="n" rel="next">Error codes</a>, Previous: <a href="#Fully-recoverable-hard-failure" accesskey="p" rel="prev">Fully recoverable hard failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Soft-failure-1"></a>
<h3 class="section">9.10 Soft failure</h3>
<p>An
<a name="index-soft-failure-1"></a>
<a name="index-failure_002c-soft-1"></a>
<em>soft failure</em>
is
an recoverable Libmarpa application programming failure that has no
error code associated with it.
Hard errors are assigned error codes in order to tell them apart.
Error codes are not necessary or useful for soft errors,
because there is at most one type of soft failure per Libmarpa method.
</p>
<p><em>Soft failures</em>
are so called,
because they are the least severe kind of failure.
The most severe failures are “bugs” —
unintended, and a symptom of a problem.
Soft failures, on the other hand, are a frequent occurrence
in normal, successful, processing.
In the phrase “soft failure”, the word “failure” is used
in the same sense that its cognate “fail” is used
when we say that a loop terminates when it “fails” its
loop condition.
That ”failure” is of a condition necessary to continue on
a main branch of processing, and a signal to proceed on another branch.
</p>
<p>It is expected that Libmarpa applications will be designed
such that successful execution
is based on the handling specified for soft failures.
In fact, a non-trival Libmarpa application can hardly be designed
except on that basis.
</p>
<hr>
<a name="Error-codes"></a>
<div class="header">
<p>
Previous: <a href="#Soft-failure" accesskey="p" rel="prev">Soft failure</a>, Up: <a href="#Failure" accesskey="u" rel="up">Failure</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error-codes-1"></a>
<h3 class="section">9.11 Error codes</h3>
<p>As stated, every hard failure has an associated error code.
Full descriptions of the error codes
that are returned by the external methods
are given in their own section
(<a href="#External-error-codes">External error codes</a>).
</p>
<p>How the error code is accessed depends on the method
which detects the hard failure associated with that error code.
Methods for time objects always set the error code in the base grammar,
from which it may be accessed using the error methods described below
(<a href="#Error-methods">Error methods</a>).
If a method has no base grammar,
the way in which the error code for the hard failures that it detects
can be accessed will be stated in the
description of that method.
</p>
<p>Since the error of a time object is set in the base grammar,
it follows that every object with the same base grammar
has the same error code.
Objects with different base grammars may have different error codes.
</p>
<p>While error codes are properties of a base grammar,
irrecoverability is application-wide.
That is, whenever any irrecoverable failure occurs, the entire
application is irrecoverable.
Once an application becomes irrecoverable,
those Libmarpa objects with error codes for recoverable errors
are still subject to the general irrecoverability.
</p>
<hr>
<a name="Introduction-to-the-method-descriptions"></a>
<div class="header">
<p>
Next: <a href="#Static-methods" accesskey="n" rel="next">Static methods</a>, Previous: <a href="#Failure" accesskey="p" rel="prev">Failure</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Introduction-to-the-method-descriptions-1"></a>
<h2 class="chapter">10 Introduction to the method descriptions</h2>
<p>The following chapters describe Libmarpa’s methods
in detail.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#About-the-overviews" accesskey="1">About the overviews</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Naming-conventions" accesskey="2">Naming conventions</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Return-values" accesskey="3">Return values</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#How-to-read-the-method-descriptions" accesskey="4">How to read the method descriptions</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="About-the-overviews"></a>
<div class="header">
<p>
Next: <a href="#Naming-conventions" accesskey="n" rel="next">Naming conventions</a>, Previous: <a href="#Introduction-to-the-method-descriptions" accesskey="p" rel="prev">Introduction to the method descriptions</a>, Up: <a href="#Introduction-to-the-method-descriptions" accesskey="u" rel="up">Introduction to the method descriptions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="About-the-overviews-1"></a>
<h3 class="section">10.1 About the overviews</h3>
<p>The method descriptions are grouped into chapters and sections.
Each such group of methods descriptions begins, optionally, with an overview.
These overviews, again optionally, end with a “cheat sheet”.
The “cheat sheets” name the
most important Libmarpa methods in that chapter
or section,
in the order in which they are typically used,
and very briefly describe their purpose.
</p>
<p>The overviews sometimes speak of
an “archetypal” application.
The
<a name="index-archetypal-Libmarpa-application"></a>
<a name="index-Libmarpa-application_002c-archetypal"></a>
<em>archetypal Libmarpa application</em>
implements a complete logic flow,
starting with the creation of a grammar,
and proceeding all the way
to the return of the final result from a value object.
In the archetypal Libmarpa application,
the grammar, input and semantics are
all small but non-trivial.
</p>
<hr>
<a name="Naming-conventions"></a>
<div class="header">
<p>
Next: <a href="#Return-values" accesskey="n" rel="next">Return values</a>, Previous: <a href="#About-the-overviews" accesskey="p" rel="prev">About the overviews</a>, Up: <a href="#Introduction-to-the-method-descriptions" accesskey="u" rel="up">Introduction to the method descriptions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Naming-conventions-1"></a>
<h3 class="section">10.2 Naming conventions</h3>
<p>Methods in Libmarpa follow a strict naming convention.
All methods have a name beginning with
<code>marpa_</code>,
if they are part of the
external interface.
If an external method is not a static method,
its name is prefixed with one of
<code>marpa_c_</code>,
<code>marpa_g_</code>,
<code>marpa_r_</code>,
<code>marpa_b_</code>,
<code>marpa_o_</code>,
<code>marpa_t_</code> or
<code>marpa_v_</code>,
where the single letter between underscores
is one of the Libmarpa major class abbreviations.
The letter indicates which class
the method belongs to.
</p>
<p>Methods that are exported,
but that are part of
the internal interface,
begin with <code>_marpa_</code>.
Methods that are part of the internal interface
(often called “internal methods”)
are subject to change and are intended for use
only by Libmarpa’s developers.
</p>
<p>Libmarpa reserves the
<code>marpa_</code>
and <code>_marpa_</code> prefixes for itself,
with all their capitalization variants.
All Libmarpa names visible outside the package
will begin with a capitalization variant
of one of these two prefixes.
</p>
<hr>
<a name="Return-values"></a>
<div class="header">
<p>
Next: <a href="#How-to-read-the-method-descriptions" accesskey="n" rel="next">How to read the method descriptions</a>, Previous: <a href="#Naming-conventions" accesskey="p" rel="prev">Naming conventions</a>, Up: <a href="#Introduction-to-the-method-descriptions" accesskey="u" rel="up">Introduction to the method descriptions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Return-values-1"></a>
<h3 class="section">10.3 Return values</h3>
<p>Some general conventions for return values are worth
mentioning:
</p><ul>
<li> For methods that return an integer,
a return value of -1
usually indicates soft failure.
</li><li> For methods that return an integer,
a return value of -2
usually indicates hard failure.
</li><li> For methods that return an integer,
a return value greater of zero or more usually indicates success.
</li><li> If a method returns an pointer value,
<code>NULL</code> usually indicates failure.
Any other result usually indicates success.
</li></ul>
<p>The Libmarpa programmer should not overly rely on the general
conventions for return values.
In particular, -2 may sometimes be ambiguous —
both a valid return value
for success, and a potential indication of hard failure.
In this case, the programmer must distinguish the two return statuses
based on the error code,
and a programmer who is relying too heavily on the general
conventions will fall into a trap.
For a the description of the return values of
<code>marpa_g_rule_rank_set()</code>,
see <a href="#Rank-methods">Rank methods</a>.
</p>
<hr>
<a name="How-to-read-the-method-descriptions"></a>
<div class="header">
<p>
Previous: <a href="#Return-values" accesskey="p" rel="prev">Return values</a>, Up: <a href="#Introduction-to-the-method-descriptions" accesskey="u" rel="up">Introduction to the method descriptions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-to-read-the-method-descriptions-1"></a>
<h3 class="section">10.4 How to read the method descriptions</h3>
<p>The method descriptions are written on the assumption
that the reader has the following in mind while reading them:
</p>
<ul>
<li> Each method description begins with the signature
of its “topic method”.
</li><li> In the method description, the phrase "this method"
always refers to the topic method.
</li><li> Whenever "this method" is the subject of a sentence
in the method description, it may be elided,
so that, for example,
"This method returns 42" becomes
"Returns 42".
</li><li> If the return type of a method is not <code>void</code>,
the last paragraph of its method description is a
“return value summary”.
The return value summary
starts with the label “<strong>Return Value</strong>”.
</li><li> Every method returns in exactly one of three
statuses: success, hard failure, or soft failure.
</li><li> A return status of hard failure indicates that the method detected
a hard failure.
</li><li> A method may have several kinds of hard failure,
including several kinds of irrecoverable hard failure
and several kinds of recoverable hard failure.
On return, these can be distinguished by their error codes.
</li><li> If a method call hard fails,
its error code is that associated with the hard failure.
Unless stated otherwise in the return value summary,
the error code is set in the base
grammar of the method call, and may be accessed
with the methods described below.
See <a href="#Error-methods">Error methods</a>.
</li><li> If a method allows a recoverable hard failure, this is explicitly stated
in its return value summary,
along with the associated error code.
The method description with state
the circumstances under which the recoverable hard failure occurs,
and what the application must do to recover.
</li><li> A return status of soft failure indicates that the method detected
a soft failure.
</li><li> Every method has at most one kind of soft failure.
</li><li> If a method allows a soft failure, this is explicitly stated
in its return value summary,
and the method description will state
the circumstances under which the soft failure occurs,
and what the application must do to recover.
</li><li> If a method call soft fails, the value of the error code is
indeterminate.
</li><li> If a method call succeeds, the value of the error code is
indeterminate.
</li><li> A return status of success indicates that the method did not detect
any failures.
</li><li> If both a hard failure and a soft failure occur,
the return status will be hard failure.
</li><li> If both a recoverable hard failure and
an irrecoverable hard failure occur,
the error code will be for an irrecoverable hard failure.
</li><li> The behaviors specified for success and soft failure
are application behaviors.
</li><li> The behaviors specified for hard failures
are diagnostic behaviors if an irrecoverable failure
occurred,
and application behaviors otherwise.
</li></ul>
<hr>
<a name="Static-methods"></a>
<div class="header">
<p>
Next: <a href="#Configuration-methods" accesskey="n" rel="next">Configuration methods</a>, Previous: <a href="#Introduction-to-the-method-descriptions" accesskey="p" rel="prev">Introduction to the method descriptions</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Static-methods-1"></a>
<h2 class="chapter">11 Static methods</h2>
<a name="marpa_005fcheck_005fversion"></a><dl>
<dt><a name="index-marpa_005fcheck_005fversion"></a>Function: <em>Marpa_Error_Code</em> <strong>marpa_check_version</strong> <em>( int <var>required_major</var>, int <var>required_minor</var>, int <var>required_micro</var> )</em></dt>
<dd>
<p>[Accessor] Checks that the Marpa library in use is compatible with the
given version. Generally, the application programmer will pass in the constants
<code>MARPA_MAJOR_VERSION</code>,
<code>MARPA_MINOR_VERSION</code>, and
<code>MARPA_MICRO_VERSION</code>
as the three arguments,
to check that their application was compiled with headers
the match the version of Libmarpa that they
are using.
</p>
<p>If <var>required_major</var>.<var>required_minor</var>.<var>required_micro</var>
is an exact match with 9.0.3,
the method succeeds.
Otherwise the return status is an irrecoverable
hard failure.
</p>
<p><strong>Return value</strong>: On success, <code>MARPA_ERR_NONE</code>.
On hard failure, the error code.
</p>
</dd></dl>
<a name="marpa_005fversion"></a><dl>
<dt><a name="index-marpa_005fversion"></a>Function: <em>Marpa_Error_Code</em> <strong>marpa_version</strong> <em>( int* version)</em></dt>
<dd>
<p>[Accessor] Writes the version number in <var>version</var>.
It is an undetected irrecoverable hard failure
if <var>version</var> does not have room for three <code>int</code>’s.
</p>
<p><strong>Return value</strong>: Always succeeds.
The return value is indeterminate.
</p>
</dd></dl>
<hr>
<a name="Configuration-methods"></a>
<div class="header">
<p>
Next: <a href="#Grammar-methods" accesskey="n" rel="next">Grammar methods</a>, Previous: <a href="#Static-methods" accesskey="p" rel="prev">Static methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Configuration-methods-1"></a>
<h2 class="chapter">12 Configuration methods</h2>
<p>The configuration object is intended for future extensions.
These may
allow the application to override Libmarpa’s memory allocation
and fatal error handling without resorting to global
variables, and therefore in a thread-safe way.
Currently, the only function of the <code>Marpa_Config</code>
class is to give
<code>marpa_g_new()</code>
a place to put its error code.
</p>
<p><code>Marpa_Config</code> is Libmarpa’s only “major”
class which is not a time class.
There is no constructor or destructor, although
<code>Marpa_Config</code> objects <strong>do</strong> need to be initialized
before use.
Aside from its own accessor,
<code>Marpa_Config</code> objects are only used by
<code>marpa_g_new()</code>
and no reference to their location is not kept
in any of Libmarpa’s time objects.
The intent is to that it be convenient
to have them in memory that might be deallocated
soon after
<code>marpa_g_new()</code>
returns.
For example, they could be put on the stack.
</p>
<a name="marpa_005fc_005finit"></a><dl>
<dt><a name="index-marpa_005fc_005finit"></a>Function: <em>int</em> <strong>marpa_c_init</strong> <em>( Marpa_Config* <var>config</var>)</em></dt>
<dd>
<p>[Mutator] Initialize the <var>config</var> information to “safe” default
values.
An irrecoverable error will result
if an uninitialized
configuration is used to create a grammar.
</p>
<p><strong>Return value</strong>: Always succeeds. The return value is indeterminate.
</p>
</dd></dl>
<a name="marpa_005fc_005ferror"></a><dl>
<dt><a name="index-marpa_005fc_005ferror"></a>Function: <em>Marpa_Error_Code</em> <strong>marpa_c_error</strong> <em>( Marpa_Config* <var>config</var>, const char** <var>p_error_string</var> )</em></dt>
<dd>
<p>[Accessor] Error codes are usually kept in the base grammar,
which leaves
<code>marpa_g_new()</code>
no place to put
its error code on failure.
Objects of
the <code>Marpa_Config</code> class provide such a place.
<var>p_error_string</var> is reserved for use by
the internals.
Applications should set it to <code>NULL</code>.
</p>
<p><strong>Return value</strong>: The error code in <var>config</var>.
Always succeeds, so that
<code>marpa_c_error()</code>
never requires an error code
for itself.
</p>
</dd></dl>
<hr>
<a name="Grammar-methods"></a>
<div class="header">
<p>
Next: <a href="#Recognizer-methods" accesskey="n" rel="next">Recognizer methods</a>, Previous: <a href="#Configuration-methods" accesskey="p" rel="prev">Configuration methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Grammar-methods-1"></a>
<h2 class="chapter">13 Grammar methods</h2>
<a name="index-grammars"></a>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Grammar-overview" accesskey="1">Grammar overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-constructor" accesskey="2">Grammar constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-reference-counting" accesskey="3">Grammar reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Symbol-methods" accesskey="4">Symbol methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Rule-methods" accesskey="5">Rule methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Sequence-methods" accesskey="6">Sequence methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Rank-methods" accesskey="7">Rank methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-precomputation" accesskey="8">Grammar precomputation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Grammar-overview"></a>
<div class="header">
<p>
Next: <a href="#Grammar-constructor" accesskey="n" rel="next">Grammar constructor</a>, Previous: <a href="#Grammar-methods" accesskey="p" rel="prev">Grammar methods</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Overview"></a>
<h3 class="section">13.1 Overview</h3>
<p>An archetypal application has a grammar.
To create a grammar, use the
<code>marpa_g_new()</code>
method.
When a grammar is no longer in use, its memory can be freed
using the
<code>marpa_g_unref()</code>
method.
</p>
<p>To be precomputed,
a grammar must have one or more symbols.
To create symbols, use the
<code>marpa_g_symbol_new()</code>
method.
</p>
<p>To be precomputed,
a grammar must have one or more rules.
To create rules, use the
<code>marpa_g_rule_new()</code>
and
<code>marpa_g_sequence_new()</code>
methods.
</p>
<p>For non-trivial parsing,
one or more of the symbols must be terminals.
To mark a symbol as a terminal,
use the
<code>marpa_g_symbol_is_terminal_set()</code>
method.
</p>
<p>To be precomputed,
a grammar must have exactly one start symbol.
To mark a symbol as the start symbol,
use the
<code>marpa_g_start_symbol_set()</code>
method.
</p>
<p>Before parsing with a grammar, it must be precomputed.
To precompute a grammar,
use the
<code>marpa_g_precompute()</code>
method.
</p>
<hr>
<a name="Grammar-constructor"></a>
<div class="header">
<p>
Next: <a href="#Grammar-reference-counting" accesskey="n" rel="next">Grammar reference counting</a>, Previous: <a href="#Grammar-overview" accesskey="p" rel="prev">Grammar overview</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Creating-a-new-grammar"></a>
<h3 class="section">13.2 Creating a new grammar</h3>
<a name="index-grammar-constructor"></a>
<a name="marpa_005fg_005fnew"></a><dl>
<dt><a name="index-marpa_005fg_005fnew"></a>Function: <em>Marpa_Grammar</em> <strong>marpa_g_new</strong> <em>( Marpa_Config* <var>configuration</var> )</em></dt>
<dd>
<p>[Constructor] Creates a new grammar time object.
The returned grammar object is not yet precomputed,
and will have no symbols and rules.
Its reference count will be 1.
</p>
<p>Unless the application calls
<code>marpa_c_error()</code>
Libmarpa will not reference the location
pointed to by the <var>configuration</var>
argument after
<code>marpa_g_new()</code>
returns.
(See <a href="#marpa_005fc_005ferror">marpa_c_error()</a>.)
The <var>configuration</var> argument may be <code>NULL</code>,
but if it is,
there will be no way to determine
the error code on failure.
</p>
<p><strong>Return value</strong>: On success, the grammar object.
On hard failure, <code>NULL</code>.
Also on hard failure,
if the <var>configuration</var> argument is not <code>NULL</code>,
the error code is set in <var>configuration</var>.
The error code may be accessed using
<code>marpa_c_error()</code>.
</p>
</dd></dl>
<a name="marpa_005fg_005fforce_005fvalued"></a><dl>
<dt><a name="index-marpa_005fg_005fforce_005fvalued"></a>Function: <em>int</em> <strong>marpa_g_force_valued</strong> <em>( Marpa_Grammar <var>g</var> )</em></dt>
<dd>
<p>[Mutator] It is recommended that
this call be made immediately after the
grammar constructor.
It turns off a deprecated feature.
</p>
<p>The
<code>marpa_g_force_valued()</code>
forces all the
symbols in a grammar to be “valued”.
The opposite of a valued symbol is one about whose value
you do not care.
This distinction has been made in the past in hope
of gaining efficiencies at evaluation time.
Current thinking is that the gains do not repay the extra
complexity.
</p>
<p><strong>Return value</strong>: On success, a non-negative integer, whose value is otherwise indeterminate.
On failure, -2.
</p></dd></dl>
<hr>
<a name="Grammar-reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Symbol-methods" accesskey="n" rel="next">Symbol methods</a>, Previous: <a href="#Grammar-constructor" accesskey="p" rel="prev">Grammar constructor</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Tracking-the-reference-count-of-the-grammar"></a>
<h3 class="section">13.3 Tracking the reference count of the grammar</h3>
<a name="index-grammar-destructor"></a>
<a name="index-grammar-reference"></a>
<a name="index-grammar-reference-count"></a>
<a name="marpa_005fg_005fref"></a><dl>
<dt><a name="index-marpa_005fg_005fref"></a>Function: <em>Marpa_Grammar</em> <strong>marpa_g_ref</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Mutator] Increases the reference count of <var>g</var> by 1.
Not needed by most applications.
</p>
<p><strong>Return value</strong>:
On success, <var>g</var>.
On hard failure, <code>NULL</code>.
</p>
</dd></dl>
<a name="marpa_005fg_005funref"></a><dl>
<dt><a name="index-marpa_005fg_005funref"></a>Function: <em>void</em> <strong>marpa_g_unref</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Destructor] Decreases the reference count by 1,
destroying <var>g</var> once the reference count reaches
zero.
</p>
</dd></dl>
<hr>
<a name="Symbol-methods"></a>
<div class="header">
<p>
Next: <a href="#Rule-methods" accesskey="n" rel="next">Rule methods</a>, Previous: <a href="#Grammar-reference-counting" accesskey="p" rel="prev">Grammar reference counting</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Symbol-methods-1"></a>
<h3 class="section">13.4 Symbol methods</h3>
<a name="marpa_005fg_005fstart_005fsymbol"></a><dl>
<dt><a name="index-marpa_005fg_005fstart_005fsymbol"></a>Function: <em>Marpa_Symbol_ID</em> <strong>marpa_g_start_symbol</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Accessor] When successful, returns the ID of the start symbol.
Soft fails, if there is no start symbol.
The start symbol is set by the
<code>marpa_g_start_symbol_set()</code>
call.
</p>
<p><strong>Return value</strong>:
On success, the ID of the start symbol,
which is always a non-negative number.
On soft failure, -1.
On hard failure, -2.
</p></dd></dl>
<a name="marpa_005fg_005fstart_005fsymbol_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005fstart_005fsymbol_005fset"></a>Function: <em>Marpa_Symbol_ID</em> <strong>marpa_g_start_symbol_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Mutator] When successful,
sets the start symbol of grammar <var>g</var> to symbol <var>sym_id</var>.
Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
</p>
<p><strong>Return value</strong>: On success, <var>sym_id</var>,
which will always be a non-negative number.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fhighest_005fsymbol_005fid"></a><dl>
<dt><a name="index-marpa_005fg_005fhighest_005fsymbol_005fid"></a>Function: <em>int</em> <strong>marpa_g_highest_symbol_id</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Accessor] <strong>Return value</strong>: On success, the numerically largest symbol ID
of <var>g</var>.
On hard failure, -2.
</p></dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005faccessible"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005faccessible"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_accessible</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Accessor] A symbol is
<a name="index-accessible-symbol"></a>
<a name="index-symbol_002c-accessible"></a>
<em>accessible</em>
if it can be reached from the start symbol.
Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success, 1 if symbol <var>sym_id</var> is accessible, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fnullable"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fnullable"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_nullable</strong> <em>( Marpa_Grammar g, Marpa_Symbol_ID sym_id)</em></dt>
<dd>
<p>[Accessor] A symbol is
<a name="index-nullable-symbol"></a>
<a name="index-symbol_002c-nullable"></a>
<em>nullable</em>
if it sometimes produces the empty string.
A <strong>nulling</strong> symbol is always a <strong>nullable</strong> symbol,
but not all <strong>nullable</strong> symbols are <strong>nulling</strong> symbols.
Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success, 1 if symbol <var>sym_id</var> is nullable, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fnulling"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fnulling"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_nulling</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Accessor] A symbol is
<a name="index-nulling-symbol"></a>
<a name="index-symbol_002c-nulling"></a>
<em>nulling</em>
if it always produces the empty string.
Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success, 1 if symbol <var>sym_id</var> is nulling, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fproductive"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fproductive"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_productive</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Accessor] A symbol is
<a name="index-productive-symbol"></a>
<a name="index-symbol_002c-productive"></a>
<em>productive</em>
if it can produce a string of terminals.
All nullable symbols are considered productive.
Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success, 1 if symbol <var>sym_id</var> is productive, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fstart"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fstart"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_start</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Accessor] On success, if <var>sym_id</var> is the start symbol, returns 1.
On success, if <var>sym_id</var> is not the start symbol, returns 0.
On success, if no start symbol has been set, returns 0.
is the start symbol.
</p>
<p>Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
</p>
<p><strong>Return value</strong>:
On success, 1 or 0.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fterminal"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fterminal"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_terminal</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Accessor] On succcess, returns the “terminal status” of a <var>sym_id</var>.
The terminal status is 1 if <var>sym_id</var> is a terminal,
0 otherwise.
To be used as an input symbol
in the
<code>marpa_r_alternative()</code>
method,
a symbol must be a terminal.
</p>
<p>By default, a symbol is a terminal if and only if it
does not appear on the LHS of any rule.
The terminal status can be set explicitly with the
<code>marpa_g_symbol_is_terminal_set()</code> method.
See <a href="#marpa_005fg_005fsymbol_005fis_005fterminal_005fset">marpa_g_symbol_is_terminal_set()</a>.
</p>
<p>Soft fails if <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
</p>
<p><strong>Return value</strong>:
On success, 1 or 0.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fterminal_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fterminal_005fset"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_terminal_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>value</var>)</em></dt>
<dd>
<p>[Mutator] Sets the “terminal status” of a symbol.
This function flags symbol <var>sym_id</var> as a terminal if
<var>value</var> is 1,
or flags it as a non-terminal if <var>value</var> is 0.
To be used as an input symbol
in the
<code>marpa_r_alternative()</code>
method,
a symbol must be a terminal.
On success, this method returns <var>value</var>.
</p>
<p>Once set to a value with this method,
the terminal status of a symbol is “locked” at that value.
A subsequent call to this method
that attempts
to change the terminal status
of <var>sym_id</var> to a value different from its current one
will hard fail
with error code <code>MARPA_ERR_TERMINAL_IS_LOCKED</code>.
Other hard failures include
when <var>value</var> is not 0 or 1;
and
when the grammar <var>g</var> is precomputed.
</p>
<p>By default, a symbol is a terminal if and only if it
does not appear on the LHS of any rule.
An attempt to flag a nulling symbol
as a terminal will cause a failure,
but this is not necessarily detected before precomputation.
</p>
<p><strong>Return value</strong>:
On success, <var>value</var>, which will be 1 or 0.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fnew"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fnew"></a>Function: <em>Marpa_Symbol_ID</em> <strong>marpa_g_symbol_new</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Mutator] When successful, creates a new symbol in grammar <var>g</var>.
</p>
<p><strong>Return value</strong>: On success, the ID of the new symbol;
which will be a non-negative integer.
On hard failure, -2.
</p>
</dd></dl>
<hr>
<a name="Rule-methods"></a>
<div class="header">
<p>
Next: <a href="#Sequence-methods" accesskey="n" rel="next">Sequence methods</a>, Previous: <a href="#Symbol-methods" accesskey="p" rel="prev">Symbol methods</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Rule-methods-1"></a>
<h3 class="section">13.5 Rule methods</h3>
<a name="marpa_005fg_005fhighest_005frule_005fid"></a><dl>
<dt><a name="index-marpa_005fg_005fhighest_005frule_005fid"></a>Function: <em>int</em> <strong>marpa_g_highest_rule_id</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Accessor] <strong>Return value</strong>: On success, the numerically largest rule ID
of <var>g</var>.
On hard failure, -2.
</p></dd></dl>
<a name="marpa_005fg_005frule_005fis_005faccessible"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fis_005faccessible"></a>Function: <em>int</em> <strong>marpa_g_rule_is_accessible</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] A rule is
<a name="index-accessible-rule"></a>
<a name="index-rule_002c-accessible"></a>
<em>accessible</em>
if it can be reached from the start symbol.
A rule is accessible if and only if its LHS symbol is accessible.
The start rule is always an accessible rule.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success 1 or 0:
1 if rule with ID <var>rule_id</var> is accessible, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fis_005fnullable"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fis_005fnullable"></a>Function: <em>int</em> <strong>marpa_g_rule_is_nullable</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>ruleid</var>)</em></dt>
<dd>
<p>[Accessor] A rule is
<a name="index-nullable-rule"></a>
<a name="index-rule_002c-nullable"></a>
<em>nullable</em>
if it sometimes produces the empty string.
A <strong>nulling</strong> rule is always a <strong>nullable</strong> rule,
but not all <strong>nullable</strong> rules are <strong>nulling</strong> rules.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success 1 or 0:
1 if the rule with ID <var>rule_id</var> is nullable, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fis_005fnulling"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fis_005fnulling"></a>Function: <em>int</em> <strong>marpa_g_rule_is_nulling</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>ruleid</var>)</em></dt>
<dd>
<p>[Accessor] A rule is
<a name="index-nulling-rule"></a>
<a name="index-rule_002c-nulling"></a>
<em>nulling</em>
if it always produces the empty string.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success 1 or 0:
1 if the rule with ID <var>rule_id</var> is nulling, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fis_005floop"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fis_005floop"></a>Function: <em>int</em> <strong>marpa_g_rule_is_loop</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] A rule is a loop rule if it non-trivially
produces the string of length one
which consists only of its LHS symbol.
Such a derivation takes the parse back to where
it started, hence the term “loop”.
“Non-trivially” means the zero-step derivation does not count — the
derivation must have at least one step.
</p>
<p>The presence of a loop rule makes a grammar infinitely ambiguous,
and applications will typically want to treat them as fatal errors.
But nothing forces an application to do this,
and Marpa will successfully parse and evaluate grammars with
loop rules.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success 1 or 0:
1 if the rule with ID <var>rule_id</var> is a loop rule, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fis_005fproductive"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fis_005fproductive"></a>Function: <em>int</em> <strong>marpa_g_rule_is_productive</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] A rule is
<a name="index-productive-rule"></a>
<a name="index-rule_002c-productive"></a>
<em>productive</em>
if it can produce a string of terminals.
A rule is productive if and only if all the symbols on
its RHS are productive.
The empty string counts as a string of terminals,
so that a nullable rule is always a productive rule.
For that same reason,
an empty rule is considered productive.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
A common hard failure is calling this method with
a grammar that is not precomputed.
</p>
<p><strong>Return value</strong>: On success 1 or 0:
1 if the rule with ID <var>rule_id</var> is productive, 0 if not.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005flength"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005flength"></a>Function: <em>int</em> <strong>marpa_g_rule_length</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] The length of a rule is the number of symbols on its RHS.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
</p>
<p><strong>Return value</strong>: On success,
the length of the rule with ID <var>rule_id</var>.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005flhs"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005flhs"></a>Function: <em>Marpa_Symbol_ID</em> <strong>marpa_g_rule_lhs</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
</p>
<p><strong>Return value</strong>: On success, the ID of the LHS
symbol of the rule with ID <var>rule_id</var>.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fnew"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fnew"></a>Function: <em>Marpa_Rule_ID</em> <strong>marpa_g_rule_new</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>lhs_id</var>, Marpa_Symbol_ID *<var>rhs_ids</var>, int <var>length</var>)</em></dt>
<dd>
<p>[Mutator] On success, creates a new external BNF rule in grammar <var>g</var>.
The ID of the new rule will be a non-negative integer,
which will be unique to that rule.
In addition to BNF rules, Marpa also allows sequence rules,
which are created by
the
<code>marpa_g_sequence_new()</code> method.
See <a href="#marpa_005fg_005fsequence_005fnew">marpa_g_sequence_new()</a>.
</p>
<p>Sequence rules and BNF rules are both rules:
They share the same series of rule IDs,
and are accessed and manipulated by the same methods,
with the only differences being as noted
in the descriptions of those methods.
</p>
<p>The LHS symbol is <var>lhs_id</var>,
and there are <var>length</var> symbols on the RHS.
The RHS symbols are in an array
pointed to by <var>rhs_ids</var>.
</p>
<p>Possible hard failures, with their error codes, include:
</p><ul>
<li> <code>MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE</code>: The LHS symbol is the same
as that of a sequence rule.
</li><li> <code>MARPA_ERR_DUPLICATE_RULE</code>: The new rule would duplicate another BNF
rule.
Another BNF rule is considered the duplicate of the new one,
if its LHS symbol is the same as symbol <var>lhs_id</var>,
if its length is the same as <var>length</var>,
and if its RHS symbols match one for one those
in the array of symbols <var>rhs_ids</var>.
</li></ul>
<p><strong>Return value</strong>: On success, the ID of the new external rule.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005frhs"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005frhs"></a>Function: <em>Marpa_Symbol_ID</em> <strong>marpa_g_rule_rhs</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>, int <var>ix</var>)</em></dt>
<dd>
<p>[Accessor] When successful, returns the ID of the symbol at index <var>ix</var>
in the RHS of the rule with ID <var>rule_id</var>.
The indexing of RHS symbols is zero-based.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
</p>
<p>A common hard failure is for <var>ix</var>
not to be a valid index of the RHS.
This happens if <var>ix</var>
is less than zero,
or or if <var>ix</var> is greater than or equal to the length of
the rule.
</p>
<p><strong>Return value</strong>: On success, a symbol ID,
which is always non-negative.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<hr>
<a name="Sequence-methods"></a>
<div class="header">
<p>
Next: <a href="#Rank-methods" accesskey="n" rel="next">Rank methods</a>, Previous: <a href="#Rule-methods" accesskey="p" rel="prev">Rule methods</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Sequence-methods-1"></a>
<h3 class="section">13.6 Sequence methods</h3>
<a name="marpa_005fg_005frule_005fis_005fproper_005fseparation"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fis_005fproper_005fseparation"></a>Function: <em>int</em> <strong>marpa_g_rule_is_proper_separation</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] When successful, returns
</p><ul>
<li> 1 if <var>rule_id</var> is the ID of a sequence rule whose
proper separation flag is set,
</li><li> 0 if <var>rule_id</var> is the ID of a sequence rule whose
proper separation flag is not set,
</li><li> 0 if <var>rule_id</var> is the ID of a rule that is not
a sequence rule.
</li></ul>
<p>Does not distinguish sequence rules without proper
separation from non-sequence rules.
That is,
does not distinguish an unset proper separation flag
from a
proper separation flag which value is undefined
because <var>rule_id</var> is the ID of a BNF rule.
Applications which want to determine whether
or not a rule is a sequence rule
can use
<code>marpa_g_sequence_min()</code> to do this.
See <a href="#marpa_005fg_005fsequence_005fmin">marpa_g_sequence_min()</a>.
</p>
<p>Soft fails if <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
</p>
<p><strong>Return value</strong>:
On success, 1 or 0.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsequence_005fmin"></a><dl>
<dt><a name="index-marpa_005fg_005fsequence_005fmin"></a>Function: <em>int</em> <strong>marpa_g_sequence_min</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] On success, returns the mininum length of a sequence rule.
Soft fails if a rule with ID <var>rule_id</var> exists,
but is not a sequence rule.
This soft failure can used to test whether
or not a rule is a sequence rule.
</p>
<p>Hard fails irrecoverably if
<var>rule_id</var> is not well-formed (a non-negative number).
Also, hard fails irrecoverably if no rule with ID <var>rule_id</var> exists,
even when <var>rule_id</var> is well formed.
Note that,
in its handling of the non-existence of a rule for its rule
argument, this method differs from many of the other grammar
methods.
Grammar methods which take a rule ID argument
more often treat the
non-existence of rule for a well-formed
rule ID as a soft, recoverable, failure.
</p>
<p><strong>Return value</strong>:
On success, the minimum length of the sequence rule
with ID <var>rule_id</var>, which is always non-negative.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsequence_005fnew"></a><dl>
<dt><a name="index-marpa_005fg_005fsequence_005fnew"></a>Function: <em>Marpa_Rule_ID</em> <strong>marpa_g_sequence_new</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>lhs_id</var>, Marpa_Symbol_ID <var>rhs_id</var>, Marpa_Symbol_ID <var>separator_id</var>, int <var>min</var>, int <var>flags</var> )</em></dt>
<dd>
<p>[Mutator] When successful,
adds a new sequence rule to grammar <var>g</var>,
and return its ID.
The ID of the sequence rule will be a non-negative integer,
which is unique to that rule.
All rules are numbered in the same series,
so that a BNF rule will never have the same rule ID as a sequence
rule, and vice versa.
</p>
<p>Sequence rules are “sugar” —
their presence in the Libmarpa interface does not extend its power.
Every Libmarpa grammar which can be written using sequence rules
can be rewritten as a grammar without sequence rules.
</p>
<p>The LHS of the sequence is <var>lhs_id</var>,
and the item to be repeated on the RHS of the sequence is <var>rhs_id</var>.
The sequence must be repeated at least <var>min</var> times,
where <var>min</var> is 0 or 1.
If <var>separator_id</var> is non-negative,
it is a separator symbol.
</p>
<p>The LHS symbol cannot be the LHS of any other rule,
whether a BNF rule or a sequence rule.
On an attempt to create an sequence rule with a duplicate
LHS,
this method hard fails,
with an error code of
<code>MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE</code>.
</p>
<p>The sequence RHS, or item,
is restricted to a single symbol,
and that symbol cannot be nullable.
If <var>separator_id</var> is a symbol, it also cannot
be a nullable symbol.
Nullables on the RHS of sequence rules are prohibited
because it is not completely clear what
an application intends
when it asks for a sequence of items,
some of which are nullable —
the most natural interpretation of this usually results in a highly
ambiguous grammar.
</p>
<p>Libmarpa allows highly ambiquous grammars
and a programmer who wants a grammar
with sequences containing nullable items or separators can
can write that grammar using BNF rules.
The use of BNF rules
make it clearer that ambiguity is what the programmer
intended, and allows the programmer more flexibility.
</p>
<p>If <code>flags & MARPA_PROPER_SEPARATION</code> is non-zero,
separation is “proper”, that is,
a trailing separator is not allowed.
The term
<a name="index-proper-separation"></a>
<a name="index-separation_002c-proper"></a>
<em>proper</em>
is based on the idea that
properly-speaking, separators should actually separate items.
Proper separation has no effect at the Libmarpa level —
it is tracked as a convenience for the higher-level interfaces to
Libmarpa,
which may want to offer the ability to
discard separators in the semantics.
(Some higher-level interfaces, in fact, may choose to discard separation by default.)
At the Libmarpa level, sequences always “keep
separators”.
</p>
<p><strong>Return value</strong>: On success, the ID of the newly added
sequence rule, which is always non-negative.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsequence_005fseparator"></a><dl>
<dt><a name="index-marpa_005fg_005fsequence_005fseparator"></a>Function: <em>int</em> <strong>marpa_g_sequence_separator</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>)</em></dt>
<dd>
<p>[Accessor] On success, returns the symbol ID of the separator
of the sequence rule with ID <var>rule_id</var>.
Soft fails if there is no separator.
The causes of hard failure include
<var>rule_id</var> not being well-formed;
<var>rule_id</var> not being the ID of a rule which exists; and
<var>rule_id</var> not being the ID a sequence rule.
</p>
<p><strong>Return value</strong>:
On success, a symbol ID, which is always non-negative.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fcounted"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fcounted"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_counted</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd>
<p>[Accessor] On success, returns a boolean whose value is
1 iff the symbol with
ID <var>sym_id</var> is counted.
A symbol is
<a name="index-counted-symbol"></a>
<a name="index-symbol_002c-counted"></a>
<em>counted</em>
iff
</p><ul>
<li> it appears on the RHS of a sequence rule, or
</li><li> it is used as the separator symbol of a sequence rule.
</li></ul>
<p>Soft fails iff <var>sym_id</var> is well-formed (a non-negative integer),
but a symbol with that ID does not exist.
</p>
<p><strong>Return value</strong>:
On success, a boolean.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<hr>
<a name="Rank-methods"></a>
<div class="header">
<p>
Next: <a href="#Grammar-precomputation" accesskey="n" rel="next">Grammar precomputation</a>, Previous: <a href="#Sequence-methods" accesskey="p" rel="prev">Sequence methods</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Rank-methods-1"></a>
<h3 class="section">13.7 Rank methods</h3>
<a name="marpa_005fg_005frule_005frank"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005frank"></a>Function: <em>Marpa_Rank</em> <strong>marpa_g_rule_rank</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID rule_id)</em></dt>
<dd>
<p>[Accessor] When successful, returns
the rank of the rule with ID <var>rule_id</var>.
When a rule is created, its rank
is initialized to the default rank of the grammar.
The default rank of the grammar is 0.
</p>
<p><strong>Return value</strong>:
On success, returns a rule rank,
and sets the error code to
<code>MARPA_ERR_NONE</code>.
The rule rank is an integer.
On hard failure, returns -2,
and sets the error code to an appropriate
value, which will never be
<code>MARPA_ERR_NONE</code>.
Note that -2 is a valid rule rank,
so that when -2 is returned,
the error code is the only way to distinguish
success from failure.
The error code can be determined using
<code>marpa_g_error()</code>.
See <a href="#marpa_005fg_005ferror">marpa_g_error()</a>.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005frank_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005frank_005fset"></a>Function: <em>Marpa_Rank</em> <strong>marpa_g_rule_rank_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>, Marpa_Rank <var>rank</var>)</em></dt>
<dd>
<p>[Mutator] When successful,
sets
the rank of the rule with ID <var>rule_id</var> to <var>rank</var>
and returns <var>rank</var>.
</p>
<p><strong>Return value</strong>:
On success, returns <var>rank</var>,
which will be an integer,
and sets the error code to
<code>MARPA_ERR_NONE</code>.
On hard failure, returns -2,
and sets the error code to an appropriate
value, which will never be
<code>MARPA_ERR_NONE</code>.
Note that -2 is a valid rule rank,
so that when -2 is returned,
the error code is the only way to distinguish
success from failure.
The error code can be determined using
<code>marpa_g_error()</code>.
See <a href="#marpa_005fg_005ferror">marpa_g_error()</a>.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fnull_005fhigh"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fnull_005fhigh"></a>Function: <em>int</em> <strong>marpa_g_rule_null_high</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID rule_id)</em></dt>
<dd>
<p>[Accessor] On success, returns a boolean whose value is 1
iff “null ranks high” is set in the rule with ID <var>rule_id</var>.
When a rule is created, it has “null ranks high” set.
</p>
<p>For more on the
“null ranks high” setting, read the description of
<code>marpa_g_rule_null_high_set()</code>.
See <a href="#marpa_005fg_005frule_005fnull_005fhigh_005fset">marpa_g_rule_null_high_set()</a>.
</p>
<p>Soft fails iff <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
</p>
<p><strong>Return value</strong>:
On success, a boolean.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005frule_005fnull_005fhigh_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005frule_005fnull_005fhigh_005fset"></a>Function: <em>int</em> <strong>marpa_g_rule_null_high_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rule_ID <var>rule_id</var>, int <var>flag</var>)</em></dt>
<dd>
<p>[Mutator] On success,
</p><ul>
<li> sets “null ranks high” in the rule with ID <var>rule_id</var> if the value
of the boolean <var>flag</var> is 1;
</li><li> unsets “null ranks high” in the rule with ID <var>rule_id</var> if the value
of the boolean <var>flag</var> is 0; and
</li><li> returns <var>flag</var>.
</li></ul>
<p>The “null ranks high” setting affects the ranking of rules
with properly nullable symbols on their right hand side.
If a rule has properly nullable symbols on its RHS,
each instance in which it appears in a parse will have a pattern
of nulled and non-nulled symbols.
Such a pattern is called a “null variant”.
</p>
<p>If the “null ranks high” is set,
nulled symbols rank high.
If the “null ranks high” is unset is the default),
nulled symbols rank low.
Ranking of a null variants is done from left-to-right.
</p>
<p>Soft fails iff <var>rule_id</var> is well-formed (a non-negative integer),
but a rule with that ID does not exist.
</p>
<p>Hard fails if
the grammar has been precomputed.
</p>
<p><strong>Return value</strong>:
On success, a boolean.
On soft failure, -1.
On hard failure, -2.
</p>
</dd></dl>
<hr>
<a name="Grammar-precomputation"></a>
<div class="header">
<p>
Previous: <a href="#Rank-methods" accesskey="p" rel="prev">Rank methods</a>, Up: <a href="#Grammar-methods" accesskey="u" rel="up">Grammar methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Precomputing-the-Grammar"></a>
<h3 class="section">13.8 Precomputing the Grammar</h3>
<a name="marpa_005fg_005fhas_005fcycle"></a><dl>
<dt><a name="index-marpa_005fg_005fhas_005fcycle"></a>Function: <em>int</em> <strong>marpa_g_has_cycle</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Accessor] On success, returns a boolean which is 1 iff
<var>g</var> has a cycle.
Cycles make a grammar infinitely ambiguous,
and are considered useless in current
practice.
Cycles make processing the grammar less
efficient, sometimes considerably so.
Applications will almost always want to treat cycles
as mistakes on the part of the writer of the grammar.
To determine which rules are in the cycle,
<code>marpa_g_rule_is_loop()</code>
can be used.
</p>
<p><strong>Return value</strong>: On success, a boolean.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fis_005fprecomputed"></a><dl>
<dt><a name="index-marpa_005fg_005fis_005fprecomputed"></a>Function: <em>int</em> <strong>marpa_g_is_precomputed</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Accessor] <strong>Return value</strong>: On success, a boolean which is 1 iff
grammar <var>g</var> is precomputed.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fg_005fprecompute"></a><dl>
<dt><a name="index-marpa_005fg_005fprecompute"></a>Function: <em>int</em> <strong>marpa_g_precompute</strong> <em>(Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>[Mutator] On success,
and on fully recoverable hard failure,
precomputes the grammar <var>g</var>.
Precomputation involves running a series of grammar checks
and “precomputing” some useful information which is kept
internally to save repeated calculations.
After precomputation, the grammar is “frozen” in many respects,
and many grammar mutators which succeed before precomputation
will cause hard failures after precomputation.
Precomputation is necessary for a recognizer to be generated
from a grammar.
</p>
<p>When called, clears any events already in the event queue.
May return one or more events.
The types of event that this method may return
are
A <code>MARPA_EVENT_LOOP_RULES</code>,
<code>MARPA_EVENT_COUNTED_NULLABLE</code>,
<code>MARPA_EVENT_NULLING_TERMINAL</code>.
All of these events occur only on failure.
Applications must be prepared for this method
to return additional events,
including events which occur on success.
Events may be queried using the
<code>marpa_g_event()</code> method.
See <a href="#marpa_005fg_005fevent">marpa_g_event()</a>.
</p>
<p>The fully recoverable hard failure is
<code>MARPA_ERR_GRAMMAR_HAS_CYCLE</code>.
Recall that for fully recoverable hard failures
this method precomputes the grammar.
Most appplications, however, will want to treat
a grammar with cycles as if it were
a library-recoverable error.
A <code>MARPA_ERR_GRAMMAR_HAS_CYCLE</code> error occurs
iff
a <code>MARPA_EVENT_LOOP_RULES</code> event occurs.
For more details on cycles,
see <a href="#marpa_005fg_005fhas_005fcycle">marpa_g_has_cycle()</a>.
</p>
<p>The error code <code>MARPA_ERR_COUNTED_NULLABLE</code>
is library-recoverable.
This failure occurs when a symbol on the RHS of a sequence rule is
nullable,
which Libmarpa does not allow in a grammar.
Error code <code>MARPA_ERR_COUNTED_NULLABLE</code> occurs iff
one or more <code>MARPA_EVENT_COUNTED_NULLABLE</code> events occur.
There is one <code>MARPA_EVENT_COUNTED_NULLABLE</code> event for every symbol
which is a nullable on the right hand side of a sequence
rule.
An application may use these events to inform the user
of the problematic symbols,
and this detail may help the user fix the grammar.
</p>
<p>The error code item <code>MARPA_ERR_NULLING_TERMINAL</code>
is library-recoverable.
This failure occurs when a nulling
symbol is also flagged as a terminal.
Since terminals cannot be of zero length, this is a logical
impossibility,
and Libmarpa does not allow nulling terminals in a grammar.
Error code item <code>MARPA_ERR_NULLING_TERMINAL</code> occurs iff
one or more <code>MARPA_EVENT_NULLING_TERMINAL</code> events occur.
There is one <code>MARPA_EVENT_NULLING_TERMINAL</code> events
for every nulling terminal in the grammar.
An application may use these events to inform the user
of the problematic symbols,
and this detail may help the user fix the grammar.
</p>
<p>Among the other error codes which may case this
method to fail
are the following:
</p>
<ul>
<li> <code>MARPA_ERR_NO_RULES</code>: The grammar has no rules.
</li><li> <code>MARPA_ERR_NO_START_SYMBOL</code>: No start symbol was specified.
</li><li> <code>MARPA_ERR_INVALID_START_SYMBOL</code>: A start symbol ID was specified, but it
is not the ID of a valid symbol.
</li><li> <code>MARPA_ERR_START_NOT_LHS</code>: The start symbol is not on the LHS of any rule.
</li><li> <code>MARPA_ERR_UNPRODUCTIVE_START</code>: The start symbol is not productive.
</li></ul>
<p>More details of these can be found under the
description of the appropriate code.
See <a href="#External-error-codes">External error codes</a>.
</p>
<p><strong>Return value</strong>: On success, a non-negative number,
whose value is otherwise indeterminate.
On hard failure, -2.
For the error code <code>MARPA_ERR_GRAMMAR_HAS_CYCLE</code>,
the hard failure is fully recoverable.
For the error codes <code>MARPA_ERR_COUNTED_NULLABLE</code>
and <code>MARPA_ERR_NULLING_TERMINAL</code>,
the hard failure is library-recoverable.
</p>
</dd></dl>
<hr>
<a name="Recognizer-methods"></a>
<div class="header">
<p>
Next: <a href="#Progress-reports" accesskey="n" rel="next">Progress reports</a>, Previous: <a href="#Grammar-methods" accesskey="p" rel="prev">Grammar methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Recognizer-methods-1"></a>
<h2 class="chapter">14 Recognizer methods</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Recognizer-overview" accesskey="1">Recognizer overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Creating-a-new-recognizer" accesskey="2">Creating a new recognizer</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Recognizer-reference-counting" accesskey="3">Recognizer reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Recognizer-life-cycle-mutators" accesskey="4">Recognizer life cycle mutators</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Location-accessors" accesskey="5">Location accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Other-parse-status-methods" accesskey="6">Other parse status methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Recognizer-overview"></a>
<div class="header">
<p>
Next: <a href="#Creating-a-new-recognizer" accesskey="n" rel="next">Creating a new recognizer</a>, Previous: <a href="#Recognizer-methods" accesskey="p" rel="prev">Recognizer methods</a>, Up: <a href="#Recognizer-methods" accesskey="u" rel="up">Recognizer methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Recognizer-overview-1"></a>
<h3 class="section">14.1 Recognizer overview</h3>
<p>An archetypal application uses a recognizer to read input.
To create a recognizer, use the
<code>marpa_r_new()</code>
method.
When a recognizer is no longer in use, its memory can be freed
using the
<code>marpa_r_unref()</code>
method.
</p>
<p>To make a recognizer ready for input,
use the
<code>marpa_r_start_input()</code>
method.
</p>
<p>The recognizer starts with its current earleme
at location 0.
To read a token at the current earleme,
use the
<code>marpa_r_alternative()</code>
call.
</p>
<p>To complete the processing of the current earleme,
and move forward to a new one,
use the
<code>marpa_r_earleme_complete()</code>
call.
</p>
<hr>
<a name="Creating-a-new-recognizer"></a>
<div class="header">
<p>
Next: <a href="#Recognizer-reference-counting" accesskey="n" rel="next">Recognizer reference counting</a>, Previous: <a href="#Recognizer-overview" accesskey="p" rel="prev">Recognizer overview</a>, Up: <a href="#Recognizer-methods" accesskey="u" rel="up">Recognizer methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Creating-a-new-recognizer-1"></a>
<h3 class="section">14.2 Creating a new recognizer</h3>
<a name="marpa_005fr_005fnew"></a><dl>
<dt><a name="index-marpa_005fr_005fnew"></a>Function: <em>Marpa_Recognizer</em> <strong>marpa_r_new</strong> <em>( Marpa_Grammar <var>g</var> )</em></dt>
<dd>
<p>[Constructor]
On success, creates a new recognizer and
increments the reference count of <var>g</var>,
the base grammar, by one.
In the new recognizer,
</p><ul>
<li> the reference count will be 1;
</li><li> the furthest earleme will be 0; and
</li><li> latest and current earleme will be undefined.
</li></ul>
<p><strong>Return value</strong>:
On success, the newly created recognizer, which is never <code>NULL</code>.
If <var>g</var> is not precomputed, or on other hard failure, <code>NULL</code>.
</p></dd></dl>
<hr>
<a name="Recognizer-reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Recognizer-life-cycle-mutators" accesskey="n" rel="next">Recognizer life cycle mutators</a>, Previous: <a href="#Creating-a-new-recognizer" accesskey="p" rel="prev">Creating a new recognizer</a>, Up: <a href="#Recognizer-methods" accesskey="u" rel="up">Recognizer methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Keeping-the-reference-count-of-a-recognizer"></a>
<h3 class="section">14.3 Keeping the reference count of a recognizer</h3>
<a name="marpa_005fr_005fref"></a><dl>
<dt><a name="index-marpa_005fr_005fref"></a>Function: <em>Marpa_Recognizer</em> <strong>marpa_r_ref</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd>
<p>[Mutator]
Increases the reference count by 1.
This method is not needed by most applications.
</p>
<p><strong>Return value</strong>:
On success, the recognizer object, <var>r</var>, which is never <code>NULL</code>.
On hard failure, <code>NULL</code>.
</p>
</dd></dl>
<a name="marpa_005fr_005funref"></a><dl>
<dt><a name="index-marpa_005fr_005funref"></a>Function: <em>void</em> <strong>marpa_r_unref</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd>
<p>[Destructor] Decreases the reference count by 1,
destroying <var>r</var> once the reference count reaches
zero.
When <var>r</var> is destroyed, the reference count
of its base grammar is decreased by one.
If this takes the reference count of the base grammar
to zero, the base grammar is also destroyed.
</p>
</dd></dl>
<hr>
<a name="Recognizer-life-cycle-mutators"></a>
<div class="header">
<p>
Next: <a href="#Location-accessors" accesskey="n" rel="next">Location accessors</a>, Previous: <a href="#Recognizer-reference-counting" accesskey="p" rel="prev">Recognizer reference counting</a>, Up: <a href="#Recognizer-methods" accesskey="u" rel="up">Recognizer methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Life-cycle-mutators"></a>
<h3 class="section">14.4 Life cycle mutators</h3>
<a name="marpa_005fr_005fstart_005finput"></a><dl>
<dt><a name="index-marpa_005fr_005fstart_005finput"></a>Function: <em>int</em> <strong>marpa_r_start_input</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd>
<p>[Mutator] When successful, does the following:
</p><ul>
<li> Readies <var>r</var> to accept input.
</li><li> Completes the first Earley set,
which is the Earley set whose ID is 0
and which is located at earleme 0.
</li><li> Leaves the latest, current and furthest earlemes all at 0.
</li><li> Clears any events that were in the event queue before this method was called.
</li><li> If this method exhausts the parse, generates a <code>MARPA_EVENT_EXHAUSTED</code> event.
See <a href="#Exhaustion">Exhaustion</a>.
</li><li> May generate one or more <code>MARPA_EVENT_SYMBOL_NULLED</code>,
<code>MARPA_EVENT_SYMBOL_PREDICTED</code>, or <code>MARPA_EVENT_SYMBOL_EXPECTED</code> events.
See <a href="#Events">Events</a>.
</li></ul>
<p><strong>Return value</strong>: On success, a non-negative value,
whose value is otherwise indeterminate.
On hard failure, -2.
</p>
</dd></dl>
<a name="marpa_005fr_005falternative"></a><dl>
<dt><a name="index-marpa_005fr_005falternative"></a>Function: <em>int</em> <strong>marpa_r_alternative</strong> <em>(Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID <var>token_id</var>, int <var>value</var>, int <var>length</var>)</em></dt>
<dd>
<p>The <var>token_id</var> argument must be the symbol ID of a terminal.
The <var>value</var> argument is an
integer that represents the “value” of the
token, and which should not be zero.
The <var>length</var> argument is the length of the token, which must
be greater than zero.
</p>
<p>On success, does the following,
where <var>current</var> is the value of the current earleme
before the call and
<var>furthest</var> is the value of the furthest earleme
before the call:
</p><ul>
<li> Reads a new token into <var>r</var>.
The symbol ID of the token will be
<var>token_id</var>.
The token will start at <var>current</var>
and end at <code><var>current</var>+<var>length</var></code>.
</li><li> Sets the value of the furthest earleme to
<code>max(<var>current</var>+<var>length</var>,<var>furthest</var>)</code>.
</li><li> Leaves
the values of the latest and current earlemes unchanged.
</li></ul>
<p>After recoverable failure, the following are the case:
</p><ul>
<li> The tokens read into <var>r</var> are unchanged.
Specifically, no new token has been read into <var>r</var>.
</li><li> The values of the latest, current and furthest earlemes
are unchanged.
</li></ul>
<p>Libmarpa allows tokens to be ambiguous.
Two tokens are ambiguous if they end at the same earleme location.
If two tokens are ambiguous, Libmarpa will attempt to produce all the parses
that include either of them.
</p>
<p>Libmarpa allows tokens to overlap.
Let the notation
<var>t</var>@<var>s</var>-<var>e</var> indicate that token <var>t</var> starts
at earleme <var>s</var> and ends at earleme <var>e</var>.
Let <var>t1</var>@<var>s1</var>-<var>e1</var>
and <var>t2</var>@<var>s2</var>-<var>e2</var>
be two tokens such that <var>s1</var><=<var>s2</var>.
We say that <var>t1</var> and <var>t2</var> overlap iff
<var>e1</var>><var>s2</var>.
</p>
<p>The <var>value</var> argument
is not used inside Libmarpa — it is simply
stored to be returned by the valuator
as a convenience for the application.
In applications where the token’s actual value is not an integer, it is
expected that the application will use <var>value</var> as
a “virtual” value,
perhaps finding the actual value by using <var>value</var>
to index an array.
Some applications may prefer to track token values on
their own, perhaps based on
the earleme location and <var>token_id</var>,
instead of using Libmarpa’s token values.
</p>
<p>A <var>value</var> of 0 does not cause a failure,
but it is reserved for unvalued symbols,
a now-deprecated feature.
See <a href="#Valued-and-unvalued-symbols">Valued and unvalued symbols</a>.
</p>
<p>Hard fails irrecoverably with <code>MARPA_ERR_DUPLICATE_TOKEN</code>
if the token added would be a duplicate.
Two tokens are duplicates iff all of the following are true:
</p><ul>
<li> They would have the same start earleme.
In other words, if <code>marpa_r_alternative()</code> attempts
to read them while at the same current earleme.
</li><li> They have the same <var>token_id</var>.
</li><li> They have the same <var>length</var>.
</li></ul>
<a name="Ruby-Slippers"></a><p>If a token was not accepted
because of its token ID,
hard fails with the <code>MARPA_ERR_UNEXPECTED_TOKEN_ID</code>.
This hard failure is fully recoverable
so that, for example,
the application may
retry this method with different token IDs
until it succeeds.
These retries are efficient,
and are quite useable as a parsing
technique —
so much so we have given the technique a name:
<a name="index-Ruby-Slippers"></a>
<em>the Ruby Slippers</em>.
The Ruby Slippers are used in several
applications.
</p>
<p><strong>Return value</strong>: On success, <code>MARPA_ERR_NONE</code>.
On failure, an error code other than <code>MARPA_ERR_NONE</code>.
The hard failure for <code>MARPA_ERR_UNEXPECTED_TOKEN_ID</code>
is fully recoverable.
</p>
</dd></dl>
<a name="marpa_005fr_005fearleme_005fcomplete"></a><dl>
<dt><a name="index-marpa_005fr_005fearleme_005fcomplete"></a>Function: <em>int</em> <strong>marpa_r_earleme_complete</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd>
<p>For the purposes of this method description, we define the following:
</p><ul>
<li> <var>current</var> is the value of the current earleme before the call of
<code>marpa_r_earleme_complete</code>.
</li><li> <var>latest</var> is the value of the latest earleme before the call of
<code>marpa_r_earleme_complete</code>.
</li><li> An “expected” terminal is one expected at a current earleme,
in the same sense that
<code>marpa_r_terminal_is_expected()</code> determines if a terminal is “expected”
at the current earleme.
See <a href="#marpa_005fr_005fterminals_005fexpected">marpa_r_terminals_expected()</a>.
</li><li> An “anticipated” terminal is one
that was accepted by
the <code>marpa_r_alternative()</code> to end at an earleme after the current
earleme.
An anticipated terminal will have length greater than one.
“Anticipated” terminals only occur if the application is using
an advanced model of input.
See <a href="#Advanced-input-models">Advanced input models</a>.
</li></ul>
<p>On success, does the final processing for the current earleme, including
the following:
</p><ul>
<li> Advances the current earleme,
incrementing its value by 1.
That is, sets the current earleme to <code><var>current</var>+1</code>.
</li><li> If any token was accepted at <var>current</var>,
creates a new Earley set
which will be the latest Earley set.
After the call, the latest
earleme will be equal to the new current earleme,
<code><var>current</var>+1</code>.
</li><li> If no token was accepted at <var>current</var>,
no Earley set is created.
After the call,
the value of the latest earleme will be unchanged —
that is, it will remain at <var>latest</var>.
Success when no tokens were accepted at <var>current</var>
can only occur if the application is using an advanced model of input.
See <a href="#Advanced-input-models">Advanced input models</a>.
</li><li> The value of the furthest earleme is never changed by
a call to
<code>marpa_r_earleme_complete()</code>.
</li><li> Clears the event queue of any events which
occured before this method was called.
</li><li> May generate one or more <code>MARPA_EVENT_SYMBOL_COMPLETED</code>,
<code>MARPA_EVENT_SYMBOL_NULLED</code>, <code>MARPA_EVENT_SYMBOL_PREDICTED</code>,
or <code>MARPA_EVENT_SYMBOL_EXPECTED</code> events.
See <a href="#Events">Events</a>.
</li><li> If an application-settable threshold
on the number of Earley items has been reached or exceeded,
generates a <code>MARPA_EVENT_EARLEY_ITEM_THRESHOLD</code> event.
Often, the application will want to treat this event
as if it were a library-recoverable
failure.
See <a href="#marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold_005fset">marpa_r_earley_item_warning_threshold_set()</a>.
</li><li> If the parse is exhausted,
triggers a
<code>MARPA_EVENT_EXHAUSTED</code> event.
Exhaustion on success only occurs if no terminals
are expected at the current earleme after
the call to this method
(that is, at <code><var>current</var>+1</code>)
and no terminals are anticipated
after <code><var>current</var>+1</code>.
</li></ul>
<p>On hard failure
with the code <code>MARPA_ERR_PARSE_EXHAUSTED</code>, does the following:
</p><ul>
<li> Leaves the current earleme at <var>current</var>.
The current earleme will be the same as the furthest earleme.
</li><li> The value of the furthest earleme is never changed by
a call to
<code>marpa_r_earleme_complete()</code>.
</li><li> Leaves the value of the latest earleme at <var>latest</var>.
No new Earley set is created.
</li><li> Sets the parse exhausted, so that no more tokens
will be accepted. See <a href="#Exhaustion">Exhaustion</a>.
</li><li> Leaves the parse in a state where no terminals
are expected or anticipated.
</li><li> Clears the event queue of any events which
occured before the call to this method.
</li><li> Triggers a
<code>MARPA_EVENT_EXHAUSTED</code> event and no others.
</li><li> Leaves valid any parses that were valid at
the current or earlier earlemes.
Processing with these can continue,
and it for this reason that we consider
hard failures with the code <code>MARPA_ERR_PARSE_EXHAUSTED</code>
to be fully recoverable.
</li></ul>
<p>We note that exhaustion can occur when this method fails
and when it succeeds.
The distinction is that, on success, the call creates a new Earley set before
becoming exhausted while,
on failure, it becomes exhausted without creating a new Earley set.
</p>
<p><strong>Return value</strong>: On success, the number of events generated.
On hard failure, -2.
Hard failure with the code
<code>MARPA_ERR_PARSE_EXHAUSTED</code>
is fully recoverable.
</p></dd></dl>
<hr>
<a name="Location-accessors"></a>
<div class="header">
<p>
Next: <a href="#Other-parse-status-methods" accesskey="n" rel="next">Other parse status methods</a>, Previous: <a href="#Recognizer-life-cycle-mutators" accesskey="p" rel="prev">Recognizer life cycle mutators</a>, Up: <a href="#Recognizer-methods" accesskey="u" rel="up">Recognizer methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Location-accessors-1"></a>
<h3 class="section">14.5 Location accessors</h3>
<a name="marpa_005fr_005fcurrent_005fearleme"></a><dl>
<dt><a name="index-marpa_005fr_005fcurrent_005fearleme"></a>Function: <em><code>Marpa_Earleme</code></em> <strong>marpa_r_current_earleme</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd><p>Return value: If input has started, the current earleme.
If input has not started, -1.
Always succeeds.
</p></dd></dl>
<a name="marpa_005fr_005fearleme"></a><dl>
<dt><a name="index-marpa_005fr_005fearleme"></a>Function: <em>Marpa_Earleme</em> <strong>marpa_r_earleme</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Earley_Set_ID <var>set_id</var>)</em></dt>
<dd>
<p>In the default, token-stream model, Earley set ID and earleme
are always equal, but this is not the case in other input
models.
(The ID of an Earley set ID is also called its ordinal.)
If there is no Earley set whose ID is
<var>set_id</var>,
<code>marpa_r_earleme()</code>
fails.
If <var>set_id</var> was negative,
the error code is set to
<code>MARPA_ERR_INVALID_LOCATION</code>.
If <var>set_id</var> is greater than the ordinal
of the latest Earley set,
the error code is set to
<code>MARPA_ERR_NO_EARLEY_SET_AT_LOCATION</code>.
</p>
<p>At this writing, there is no method for
the inverse operation (conversion of an earleme to an Earley set
ID).
One consideration in writing
such a method is that not all earlemes correspond to Earley sets.
Applications that want to map earlemes
to Earley sets will have no trouble if they
are using the standard input model —
the Earley set
ID is always exactly equal to the earleme in that model.
For other applications
that want an earleme-to-ID mapping,
the most general method is create an ID-to-earleme
array using the
<code>marpa_r_earleme()</code>
method
and invert it.
</p>
<p>Return value:
On success,
the earleme corresponding to Earley
set <var>set_id</var>.
On failure, -2.
</p></dd></dl>
<a name="marpa_005fr_005fearley_005fset_005fvalue"></a><dl>
<dt><a name="index-marpa_005fr_005fearley_005fset_005fvalue"></a>Function: <em>int</em> <strong>marpa_r_earley_set_value</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Earley_Set_ID earley_set)</em></dt>
<dd><p>Returns the integer value of <var>earley_set</var>.
For more details, see
the description of
<code>marpa_r_earley_set_values()</code>.
</p>
<p>Return value: On success, the value of <var>earley_set</var>.
On failure, -2.
</p></dd></dl>
<a name="marpa_005fr_005fearley_005fset_005fvalues"></a><dl>
<dt><a name="index-marpa_005fr_005fearley_005fset_005fvalues"></a>Function: <em>int</em> <strong>marpa_r_earley_set_values</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Earley_Set_ID earley_set, int* p_value, void** p_pvalue )</em></dt>
<dd><p>If <var>p_value</var> is non-zero,
sets the location pointed to by
<var>p_value</var> to the integer value of the Earley set.
Similarly, if <var>p_pvalue</var> is non-zero,
sets the location pointed to by
<var>p_pvalue</var> to the pointer value of the Earley set.
</p>
<p>The “value” and “pointer” of an Earley set are
an arbitrary integer
and an arbitrary pointer
that the application
can use for its own purposes.
In character-per-earleme input models, for example,
the integer can be the codepoint of the current character.
In a traditional token-per-earleme input model,
they could be used to indicate the string value of the token –
the pointer could point to the start of the string,
and the integer could indicate its length.
</p>
<p>The Earley set value and pointer can be set using
the
<code>marpa_r_latest_earley_set_values_set()</code>
method.
The Earley set integer value defaults to -1,
and the pointer value defaults to <code>NULL</code>.
</p>
<p>Return value: On success, returns a non-negative integer.
On failure, returns -2.
</p></dd></dl>
<a name="marpa_005fr_005ffurthest_005fearleme"></a><dl>
<dt><a name="index-marpa_005fr_005ffurthest_005fearleme"></a>Function: <em><code>unsigned int</code></em> <strong>marpa_r_furthest_earleme</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd>
<p>Always returns the furthest earleme.
</p>
<p><strong>Return value</strong>: On success, the furthest earleme.
Always succeeds.
</p>
</dd></dl>
<a name="marpa_005fr_005flatest_005fearley_005fset"></a><dl>
<dt><a name="index-marpa_005fr_005flatest_005fearley_005fset"></a>Function: <em>Marpa_Earley_Set_ID</em> <strong>marpa_r_latest_earley_set</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd><p>This method returns the Earley set ID (ordinal) of the latest Earley set.
Applications that want the
value of the latest earleme can convert
this value using
the
<code>marpa_r_earleme()</code>
method.
</p>
<p>Return value: On success, the ID of the latest Earley set.
Always succeeds.
</p></dd></dl>
<a name="marpa_005fr_005flatest_005fearley_005fset_005fvalue_005fset"></a><dl>
<dt><a name="index-marpa_005fr_005flatest_005fearley_005fset_005fvalue_005fset"></a>Function: <em>int</em> <strong>marpa_r_latest_earley_set_value_set</strong> <em>( Marpa_Recognizer <var>r</var>, int value)</em></dt>
<dd><p>Sets the integer value of the latest Earley set.
For more details, see
the description of
<code>marpa_r_latest_earley_set_values_set()</code>.
</p>
<p>Return value: On success, the new value of <var>earley_set</var>.
On failure, -2.
</p></dd></dl>
<a name="marpa_005fr_005flatest_005fearley_005fset_005fvalues_005fset"></a><dl>
<dt><a name="index-marpa_005fr_005flatest_005fearley_005fset_005fvalues_005fset"></a>Function: <em>int</em> <strong>marpa_r_latest_earley_set_values_set</strong> <em>( Marpa_Recognizer <var>r</var>, int value, void* pvalue)</em></dt>
<dd><p>Sets the integer and pointer value of the latest Earley set.
For more about the “integer value” and “pointer value”
of an Earley set,
see the description of the
<code>marpa_r_earley_set_values()</code>
method.
</p>
<p>Return value: On success, returns a non-negative integer.
On failure, returns -2.
</p></dd></dl>
<hr>
<a name="Other-parse-status-methods"></a>
<div class="header">
<p>
Previous: <a href="#Location-accessors" accesskey="p" rel="prev">Location accessors</a>, Up: <a href="#Recognizer-methods" accesskey="u" rel="up">Recognizer methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Other-parse-status-methods-1"></a>
<h3 class="section">14.6 Other parse status methods</h3>
<a name="marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold"></a><dl>
<dt><a name="index-marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold"></a>Function: <em>int</em> <strong>marpa_r_earley_item_warning_threshold</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd>
<p>Returns the Earley item warning threshold.
See <a href="#marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold_005fset">marpa_r_earley_item_warning_threshold_set()</a>.
</p>
<p><strong>Return value</strong>:
The Earley item warning threshold.
Always succeeds.
</p></dd></dl>
<a name="marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold_005fset"></a><dl>
<dt><a name="index-marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold_005fset"></a>Function: <em>int</em> <strong>marpa_r_earley_item_warning_threshold_set</strong> <em>(Marpa_Recognizer <var>r</var>, int <var>threshold</var>)</em></dt>
<dd>
<p>[Mutator] On success, sets
the Earley item warning threshold.
The
<a name="index-Earley-item-warning-threshold"></a>
<em>Earley item warning threshold</em>
is a number that is compared with
the count of Earley items in each Earley set.
When it is matched or exceeded,
a <code>MARPA_EVENT_EARLEY_ITEM_THRESHOLD</code> event is created.
See <a href="#MARPA_005fEVENT_005fEARLEY_005fITEM_005fTHRESHOLD">MARPA_EVENT_EARLEY_ITEM_THRESHOLD</a>.
</p>
<p>If <var>threshold</var> is zero or less,
an unlimited number of Earley items
will be allowed without warning.
This will rarely be what the user wants.
</p>
<p>By default, Libmarpa calculates a value based on the grammar.
The formula Libmarpa uses is the result of some experience,
and most applications will
be happy with it.
</p>
<p>What should be done when the threshold is exceeded, depends on the application,
but exceeding the threshold means that it is very likely
that the time and space resources consumed by
the parse will prove excessive.
This is often a sign of a bug in the grammar.
Applications often will want to smoothly shut down
the parse,
in effect treating
the <code>MARPA_EVENT_EARLEY_ITEM_THRESHOLD</code> event
as equivalent to library-recoverable hard failure.
</p>
<p>Return value:
The value that the Earley item warning threshold has
after the method call is finished.
Always succeeds.
</p></dd></dl>
<a name="marpa_005fr_005fis_005fexhausted"></a><dl>
<dt><a name="index-marpa_005fr_005fis_005fexhausted"></a>Function: <em>int</em> <strong>marpa_r_is_exhausted</strong> <em>(Marpa_Recognizer <var>r</var>)</em></dt>
<dd><p>A parser is “exhausted” if it cannot accept any more input.
Both successful and failed parses can be exhausted.
In many grammars,
the parse is always exhausted as soon as it succeeds.
Good parses may also exist at earlemes prior to the
current one.
</p>
<p>Return value:
1 if the parser is exhausted, 0 otherwise.
Always succeeds.
</p></dd></dl>
<a name="marpa_005fr_005fterminals_005fexpected"></a><dl>
<dt><a name="index-marpa_005fr_005fterminals_005fexpected"></a>Function: <em>int</em> <strong>marpa_r_terminals_expected</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID* <var>buffer</var>)</em></dt>
<dd><p>Returns a list of the ID’s of the symbols
that are acceptable as tokens
at the current earleme.
<var>buffer</var> is expected to be large enough to hold
the result.
This is guaranteed to be the case if the buffer
is large enough to hold a number of
<code>Marpa_Symbol_ID</code>’s that
is greater than or equal to the number of symbols
in the grammar.
</p>
<p>Return value: On success, the number of <code>Marpa_Symbol_ID</code>’s
in <var>buffer</var>.
On failure, -2.
</p></dd></dl>
<a name="marpa_005fr_005fterminal_005fis_005fexpected"></a><dl>
<dt><a name="index-marpa_005fr_005fterminal_005fis_005fexpected"></a>Function: <em>int</em> <strong>marpa_r_terminal_is_expected</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID <var>symbol_id</var>)</em></dt>
<dd>
<p>Return values on success:
If <var>symbol_id</var> is the
ID of a valid terminal symbol that is expected at
the current earleme,
a number greater than zero.
If <var>symbol_id</var> is the
ID of a valid terminal symbol that is
<strong>not</strong> expected at
the current earleme, or
if <var>symbol_id</var> is the ID of a valid symbol
that is not a terminal, zero.
</p>
<p>Failure cases:
Returns -2 on failure.
It is a failure
if <var>symbol_id</var> is not the ID of a valid
symbol.
</p></dd></dl>
<hr>
<a name="Progress-reports"></a>
<div class="header">
<p>
Next: <a href="#Bocage-methods" accesskey="n" rel="next">Bocage methods</a>, Previous: <a href="#Recognizer-methods" accesskey="p" rel="prev">Recognizer methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Progress-reports-1"></a>
<h2 class="chapter">15 Progress reports</h2>
<p>An important advantage of the Marpa algorithm is the ability
to easily get full information about the state of the parse.
</p>
<p>To start a progress report,
use the
<code>marpa_r_progress_report_start()</code>
command.
Only one progress report can be in use at any one time.
</p>
<p>To get the information in a progress report,
it is necessary to step through the progress report
items.
To get the data for the current progress report item,
and advance to the next one,
use the
<code>marpa_r_progress_item()</code>
method.
</p>
<p>To destroy a progress report,
freeing the memory it uses,
call the
<code>marpa_r_progress_report_finish()</code>
method.
</p>
<a name="marpa_005fr_005fprogress_005freport_005freset"></a><dl>
<dt><a name="index-marpa_005fr_005fprogress_005freport_005freset"></a>Function: <em>int</em> <strong>marpa_r_progress_report_reset</strong> <em>( Marpa_Recognizer <var>r</var>)</em></dt>
<dd><p>Resets the progress report.
Assumes a report of the progress has already been initialized
at some Earley set
for recognizer <var>r</var>,
with
<code>marpa_r_progress_report_start()</code>.
The reset progress report will
be positioned before its first item.
</p>
<p>Return value: On success, a non-negative value.
On failure, -2.
</p></dd></dl>
<a name="marpa_005fr_005fprogress_005freport_005fstart"></a><dl>
<dt><a name="index-marpa_005fr_005fprogress_005freport_005fstart"></a>Function: <em>int</em> <strong>marpa_r_progress_report_start</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Earley_Set_ID <var>set_id</var>)</em></dt>
<dd><p>Initializes a report of the progress at Earley set <var>set_id</var>
for recognizer <var>r</var>.
If a progress report already exists, it is destroyed and its
memory is freed.
Initially,
the progress report is positioned before its first item.
</p>
<p>If no Earley set with ID
<var>set_id</var> exists,
<code>marpa_r_progress_report_start()</code>
fails.
The error code is <code>MARPA_ERR_INVALID_LOCATION</code> if <var>set_id</var>
is negative.
The error code is <code>MARPA_ERR_NO_EARLEY_SET_AT_LOCATION</code>
if <var>set_id</var> is greater than the ID of
the latest Earley set.
</p>
<p>Return value: On success, the number of report items available.
If the recognizer has not been started;
if <var>set_id</var> does not exist;
or on other failure, -2.
</p></dd></dl>
<a name="marpa_005fr_005fprogress_005freport_005ffinish"></a><dl>
<dt><a name="index-marpa_005fr_005fprogress_005freport_005ffinish"></a>Function: <em>int</em> <strong>marpa_r_progress_report_finish</strong> <em>( Marpa_Recognizer <var>r</var> )</em></dt>
<dd><p>Destroys the report of the progress at Earley set <var>set_id</var>
for recognizer <var>r</var>,
freeing the memory and other resources.
It is often not necessary to call this method.
Any previously existing progress report
is destroyed automatically
whenever a new progress report is started,
and when the recognizer is destroyed.
</p>
<p>Return value: -2 if no progress report has been started,
or on other failure.
On success, a non-negative value.
</p></dd></dl>
<a name="marpa_005fr_005fprogress_005fitem"></a><dl>
<dt><a name="index-marpa_005fr_005fprogress_005fitem"></a>Function: <em>Marpa_Rule_ID</em> <strong>marpa_r_progress_item</strong> <em>( Marpa_Recognizer <var>r</var>, int* <var>position</var>, Marpa_Earley_Set_ID* <var>origin</var> )</em></dt>
<dd><p>This method allows access to the data
for the next item of a
progress report.
If there are no more progress report items,
it returns -1 as a termination indicator
and sets the error code to <code>MARPA_ERR_PROGRESS_REPORT_EXHAUSTED</code>.
Either the termination indicator,
or the item count returned by
<code>marpa_r_progress_report_start()</code>,
can be used to determine when the last
item has been seen.
</p>
<p>On success,
the dot position is returned in the location
pointed to by the <var>position</var> argument,
and the origin is returned in the location
pointed to by the <var>origin</var> argument.
On failure, the locations pointed to by
the <var>position</var> and <var>origin</var>
arguments are unchanged.
</p>
<p>Return value: On success, the rule ID of
the next progress report item.
If there are no more progress report items, -1.
If either the <var>position</var> or the <var>origin</var>
argument is <code>NULL</code>,
or on other failure, -2.
</p></dd></dl>
<hr>
<a name="Bocage-methods"></a>
<div class="header">
<p>
Next: <a href="#Ordering-methods" accesskey="n" rel="next">Ordering methods</a>, Previous: <a href="#Progress-reports" accesskey="p" rel="prev">Progress reports</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Bocage-methods-1"></a>
<h2 class="chapter">16 Bocage methods</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Bocage-overview" accesskey="1">Bocage overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-constructor" accesskey="2">Bocage constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-reference-counting" accesskey="3">Bocage reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Bocage-accessor" accesskey="4">Bocage accessor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Bocage-overview"></a>
<div class="header">
<p>
Next: <a href="#Bocage-constructor" accesskey="n" rel="next">Bocage constructor</a>, Previous: <a href="#Bocage-methods" accesskey="p" rel="prev">Bocage methods</a>, Up: <a href="#Bocage-methods" accesskey="u" rel="up">Bocage methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Overview-1"></a>
<h3 class="section">16.1 Overview</h3>
<p>A bocage is structure containing the full set of parses found
by processing the input according to the grammar.
The bocage structure is new with Libmarpa, but is very similar
in purpose to the more familar parse forests.
</p>
<p>To create a bocage, use the
<code>marpa_b_new()</code>
method.
</p>
<p>When a bocage is no longer in use, its memory can be freed
using the
<code>marpa_b_unref()</code>
method.
</p>
<hr>
<a name="Bocage-constructor"></a>
<div class="header">
<p>
Next: <a href="#Bocage-reference-counting" accesskey="n" rel="next">Bocage reference counting</a>, Previous: <a href="#Bocage-overview" accesskey="p" rel="prev">Bocage overview</a>, Up: <a href="#Bocage-methods" accesskey="u" rel="up">Bocage methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Creating-a-new-bocage"></a>
<h3 class="section">16.2 Creating a new bocage</h3>
<a name="marpa_005fb_005fnew"></a><dl>
<dt><a name="index-marpa_005fb_005fnew"></a>Function: <em>Marpa_Bocage</em> <strong>marpa_b_new</strong> <em>(Marpa_Recognizer <var>r</var>, Marpa_Earley_Set_ID <var>earley_set_ID</var>)</em></dt>
<dd>
<p>Creates a new bocage object, with a reference count of 1.
The reference count of its parent recognizer object, <var>r</var>,
is increased by 1.
If <var>earley_set_ID</var> is -1,
the Earley set at the current earleme is used,
if there is one.
</p>
<p>If <var>earley_set_ID</var> is -1
and there is no Earley set at the current earleme;
or if <var>earley_set_ID</var> is -1
and there is no parse ending at Earley set <var>earley_set_ID</var>,
<code>marpa_b_new()</code>
fails
and the error code is set to
<code>MARPA_ERR_NO_PARSE</code>.
</p>
<p>Success return value: On success, the new bocage object.
On failure, <code>NULL</code>.
</p></dd></dl>
<hr>
<a name="Bocage-reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Bocage-accessor" accesskey="n" rel="next">Bocage accessor</a>, Previous: <a href="#Bocage-constructor" accesskey="p" rel="prev">Bocage constructor</a>, Up: <a href="#Bocage-methods" accesskey="u" rel="up">Bocage methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reference-counting-2"></a>
<h3 class="section">16.3 Reference counting</h3>
<a name="marpa_005fb_005fref"></a><dl>
<dt><a name="index-marpa_005fb_005fref"></a>Function: <em>Marpa_Bocage</em> <strong>marpa_b_ref</strong> <em>(Marpa_Bocage <var>b</var>)</em></dt>
<dd><p>Increases the reference count by 1.
Not needed by most applications.
</p>
<p>Return value:
On success, <var>b</var>.
On failure, <code>NULL</code>.
</p></dd></dl>
<a name="marpa_005fb_005funref"></a><dl>
<dt><a name="index-marpa_005fb_005funref"></a>Function: <em>void</em> <strong>marpa_b_unref</strong> <em>(Marpa_Bocage <var>b</var>)</em></dt>
<dd><p>Decreases the reference count by 1,
destroying <var>b</var> once the reference count reaches
zero.
When <var>b</var> is destroyed, the reference count
of its parent recognizer is decreased by 1.
If this takes the reference count of the parent recognizer
to zero, it too is destroyed.
If the parent recognizer is destroyed, the reference count
of its base grammar is decreased by 1.
If this takes the reference count of the base grammar
to zero, it too is destroyed.
</p>
</dd></dl>
<hr>
<a name="Bocage-accessor"></a>
<div class="header">
<p>
Previous: <a href="#Bocage-reference-counting" accesskey="p" rel="prev">Bocage reference counting</a>, Up: <a href="#Bocage-methods" accesskey="u" rel="up">Bocage methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Accessors"></a>
<h3 class="section">16.4 Accessors</h3>
<a name="marpa_005fb_005fambiguity_005fmetric"></a><dl>
<dt><a name="index-marpa_005fb_005fambiguity_005fmetric"></a>Function: <em>int</em> <strong>marpa_b_ambiguity_metric</strong> <em>(Marpa_Bocage <var>b</var>)</em></dt>
<dd><p>Returns an ambiguity metric.
The metric is 1 is the parse is unambiguous.
If the metric is 2 or greater,
the parse is ambiguous.
It was originally intended to have values greater
than 2 be an cheaply computed
estimate of the degree of ambiguity,
but a satisfactory scheme for this
has yet to be implemented.
</p>
<p>Return value on success:
1 if the bocage is not for an ambiguous parse;
2 or greater if the bocage is for an ambiguous parse.
</p>
<p>Failures: On failure, -2.
</p>
</dd></dl>
<a name="marpa_005fb_005fis_005fnull"></a><dl>
<dt><a name="index-marpa_005fb_005fis_005fnull"></a>Function: <em>int</em> <strong>marpa_b_is_null</strong> <em>(Marpa_Bocage <var>b</var>)</em></dt>
<dd><p>Return value on success:
A number greater than or equal to 1 if the bocage is for a null parse;
otherwise, 0.
</p>
<p>Failures: On failure, -2.
</p>
</dd></dl>
<hr>
<a name="Ordering-methods"></a>
<div class="header">
<p>
Next: <a href="#Tree-methods" accesskey="n" rel="next">Tree methods</a>, Previous: <a href="#Bocage-methods" accesskey="p" rel="prev">Bocage methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Ordering-methods-1"></a>
<h2 class="chapter">17 Ordering methods</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Ordering-overview" accesskey="1">Ordering overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ordering-constructor" accesskey="2">Ordering constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Ordering-reference-counting" accesskey="3">Ordering reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Order-accessor" accesskey="4">Order accessor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Non_002ddefault-ordering" accesskey="5">Non-default ordering</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Ordering-overview"></a>
<div class="header">
<p>
Next: <a href="#Ordering-constructor" accesskey="n" rel="next">Ordering constructor</a>, Previous: <a href="#Ordering-methods" accesskey="p" rel="prev">Ordering methods</a>, Up: <a href="#Ordering-methods" accesskey="u" rel="up">Ordering methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Overview-2"></a>
<h3 class="section">17.1 Overview</h3>
<p>Before iterating the parses in the bocage,
they must be ordered.
To create an ordering, use the
<code>marpa_o_new()</code>
method.
When an ordering is no longer in use, its memory can be freed
using the
<code>marpa_o_unref()</code>
method.
</p>
<p>An ordering is
<a name="index-frozen-ordering"></a>
<a name="index-ordering_002c-frozen"></a>
<em>frozen</em>
once the first
tree iterator is created
using it.
A frozen ordering cannot be changed.
</p>
<p>As of this writing, the only methods to order parses
are internal and undocumented.
This is expected to change.
</p>
<hr>
<a name="Ordering-constructor"></a>
<div class="header">
<p>
Next: <a href="#Ordering-reference-counting" accesskey="n" rel="next">Ordering reference counting</a>, Previous: <a href="#Ordering-overview" accesskey="p" rel="prev">Ordering overview</a>, Up: <a href="#Ordering-methods" accesskey="u" rel="up">Ordering methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Creating-an-ordering"></a>
<h3 class="section">17.2 Creating an ordering</h3>
<a name="marpa_005fo_005fnew"></a><dl>
<dt><a name="index-marpa_005fo_005fnew"></a>Function: <em>Marpa_Order</em> <strong>marpa_o_new</strong> <em>( Marpa_Bocage <var>b</var>)</em></dt>
<dd><p>Creates a new ordering object, with a reference count of 1.
The reference count of its parent bocage object, <var>b</var>,
is increased by 1.
</p>
<p>Return value: On success, the new ordering object.
On failure, <code>NULL</code>.
</p></dd></dl>
<hr>
<a name="Ordering-reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Order-accessor" accesskey="n" rel="next">Order accessor</a>, Previous: <a href="#Ordering-constructor" accesskey="p" rel="prev">Ordering constructor</a>, Up: <a href="#Ordering-methods" accesskey="u" rel="up">Ordering methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reference-counting-3"></a>
<h3 class="section">17.3 Reference counting</h3>
<a name="marpa_005fo_005fref"></a><dl>
<dt><a name="index-marpa_005fo_005fref"></a>Function: <em>Marpa_Order</em> <strong>marpa_o_ref</strong> <em>( Marpa_Order <var>o</var>)</em></dt>
<dd><p>Increases the reference count by 1.
Not needed by most applications.
</p>
<p>Return value:
On success, <var>o</var>.
On failure, <code>NULL</code>.
</p></dd></dl>
<a name="marpa_005fo_005funref"></a><dl>
<dt><a name="index-marpa_005fo_005funref"></a>Function: <em>void</em> <strong>marpa_o_unref</strong> <em>( Marpa_Order <var>o</var>)</em></dt>
<dd><p>Decreases the reference count by 1,
destroying <var>o</var> once the reference count reaches
zero.
Beginning with <var>o</var>’s parent bocage,
Libmarpa then proceeds up the chain of parent objects.
Every time a child is destroyed, the
reference count of its parent is decreased by 1.
Every time the reference count of an object
is decreased by 1,
if that reference count is now zero,
that object is destroyed.
Libmarpa follows this chain of decrements
and destructions as required,
all the way back to the
base grammar, if necessary.
</p>
</dd></dl>
<hr>
<a name="Order-accessor"></a>
<div class="header">
<p>
Next: <a href="#Non_002ddefault-ordering" accesskey="n" rel="next">Non-default ordering</a>, Previous: <a href="#Ordering-reference-counting" accesskey="p" rel="prev">Ordering reference counting</a>, Up: <a href="#Ordering-methods" accesskey="u" rel="up">Ordering methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Accessors-1"></a>
<h3 class="section">17.4 Accessors</h3>
<a name="marpa_005fo_005fambiguity_005fmetric"></a><dl>
<dt><a name="index-marpa_005fo_005fambiguity_005fmetric"></a>Function: <em>int</em> <strong>marpa_o_ambiguity_metric</strong> <em>(Marpa_Order <var>o</var>)</em></dt>
<dd><p>Returns an ambiguity metric.
The metric is 1 is the parse is unambiguous.
If the metric is 2 or greater,
the parse is ambiguous.
It was originally intended to have values greater
than 2 be an cheaply computed
estimate of the degree of ambiguity,
but a satisfactory scheme for this
has yet to be implemented.
</p>
<p>If the ordering is not already frozen,
it will be frozen on return from
<code>marpa_o_ambiguity_metric()</code>.
<code>marpa_o_ambiguity_metric()</code>
is considered an “accessor”,
because it is assumed that the ordering is frozen
when
<code>marpa_o_ambiguity_metric()</code>
is called.
</p>
<p>Return value on success:
1 if the ordering is not for an ambiguous parse;
2 or greater if the ordering is for an ambiguous parse.
</p>
<p>Failures: On failure, -2.
</p>
</dd></dl>
<a name="marpa_005fo_005fis_005fnull"></a><dl>
<dt><a name="index-marpa_005fo_005fis_005fnull"></a>Function: <em>int</em> <strong>marpa_o_is_null</strong> <em>(Marpa_Order <var>o</var>)</em></dt>
<dd><p>Return value on success:
A number greater than or equal to 1 if the ordering is for a null parse;
otherwise, 0.
</p>
<p>Failures: On failure, -2.
</p>
</dd></dl>
<hr>
<a name="Non_002ddefault-ordering"></a>
<div class="header">
<p>
Previous: <a href="#Order-accessor" accesskey="p" rel="prev">Order accessor</a>, Up: <a href="#Ordering-methods" accesskey="u" rel="up">Ordering methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Non_002ddefault-ordering-1"></a>
<h3 class="section">17.5 Non-default ordering</h3>
<a name="marpa_005fo_005fhigh_005frank_005fonly_005fset"></a><dl>
<dt><a name="index-marpa_005fo_005fhigh_005frank_005fonly_005fset"></a>Function: <em>int</em> <strong>marpa_o_high_rank_only_set</strong> <em>( Marpa_Order <var>o</var>, int <var>flag</var>)</em></dt>
<dd><a name="marpa_005fo_005fhigh_005frank_005fonly"></a></dd><dt><a name="index-marpa_005fo_005fhigh_005frank_005fonly"></a>Function: <em>int</em> <strong>marpa_o_high_rank_only</strong> <em>( Marpa_Order <var>o</var>)</em></dt>
<dd><p>These methods, respectively, set and query
the “high rank only” flag of ordering <var>o</var>.
A <var>flag</var> of 1 indicates that, when ranking,
all choices should be discarded except those of the
highest rank.
A <var>flag</var> of 0 indicates that
no choices should be discarded on the
basis of their rank.
</p>
<p>A value of 1 is the default.
The value of the “high rank only” flag has no effect
unless ranking has been turned on using the
<code>marpa_o_rank()</code>
method.
</p>
<p>Return value: On success, the value of the
“high rank only” flag <strong>after</strong>
the call.
On failure, -2.
</p></dd></dl>
<a name="marpa_005fo_005frank"></a><dl>
<dt><a name="index-marpa_005fo_005frank"></a>Function: <em>int</em> <strong>marpa_o_rank</strong> <em>( Marpa_Order <var>o</var> )</em></dt>
<dd><p>By default, the ordering of parse trees is arbitrary.
This method causes the ordering to be ranked
according to the ranks of symbols and rules,
the “null ranks high” flags of the rules,
and the “high rank only” flag of the ordering.
Once this method returns, the ordering is frozen.
</p>
<p>Return value: On success, a non-negative value.
On failure, -2.
</p>
</dd></dl>
<hr>
<a name="Tree-methods"></a>
<div class="header">
<p>
Next: <a href="#Value-methods" accesskey="n" rel="next">Value methods</a>, Previous: <a href="#Ordering-methods" accesskey="p" rel="prev">Ordering methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Tree-methods-1"></a>
<h2 class="chapter">18 Tree methods</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Tree-overview" accesskey="1">Tree overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-constructor" accesskey="2">Tree constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-reference-counting" accesskey="3">Tree reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Tree-iteration" accesskey="4">Tree iteration</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Tree-overview"></a>
<div class="header">
<p>
Next: <a href="#Tree-constructor" accesskey="n" rel="next">Tree constructor</a>, Previous: <a href="#Tree-methods" accesskey="p" rel="prev">Tree methods</a>, Up: <a href="#Tree-methods" accesskey="u" rel="up">Tree methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Overview-3"></a>
<h3 class="section">18.1 Overview</h3>
<p>Once the bocage has an ordering, the parses trees can be iterated.
Marpa’s
<a name="index-parse-tree-iterator"></a>
<a name="index-iterator_002c-parse-tree"></a>
<a name="index-parse-tree"></a>
<a name="index-tree"></a>
<em>parse tree iterators</em>
iterate the parse trees contained
in a bocage object.
In Libmarpa,
“parse tree iterators” are usually just called
<em>trees</em>.
</p>
<p>To create a tree, use the
<code>marpa_t_new()</code>
method.
A newly created tree iterator is positioned before the first parse tree.
When a tree iterator is no longer in use, its memory can be freed
using the
<code>marpa_t_unref()</code>
method.
</p>
<p>To position a newly created tree iterator at the first parse tree,
use the
<code>marpa_t_next()</code>
method.
Once the tree iterator is positioned at a parse tree,
the same
<code>marpa_t_next()</code>
method is used
to position it to the next parse tree.
</p>
<hr>
<a name="Tree-constructor"></a>
<div class="header">
<p>
Next: <a href="#Tree-reference-counting" accesskey="n" rel="next">Tree reference counting</a>, Previous: <a href="#Tree-overview" accesskey="p" rel="prev">Tree overview</a>, Up: <a href="#Tree-methods" accesskey="u" rel="up">Tree methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Creating-a-new-tree-iterator"></a>
<h3 class="section">18.2 Creating a new tree iterator</h3>
<a name="marpa_005ft_005fnew"></a><dl>
<dt><a name="index-marpa_005ft_005fnew"></a>Function: <em>Marpa_Tree</em> <strong>marpa_t_new</strong> <em>(Marpa_Order <var>o</var>)</em></dt>
<dd><p>Creates a new tree iterator, with a reference count of 1.
The reference count of its parent ordering object, <var>o</var>,
is increased by 1.
</p>
<p>When initialized, a tree iterator is positioned
before the first parse tree.
To position the tree iterator to the first parse,
the application must call
<code>marpa_t_next()</code>.
</p>
<p>Return value: On success, a newly created tree.
On failure, <code>NULL</code>.
</p></dd></dl>
<hr>
<a name="Tree-reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Tree-iteration" accesskey="n" rel="next">Tree iteration</a>, Previous: <a href="#Tree-constructor" accesskey="p" rel="prev">Tree constructor</a>, Up: <a href="#Tree-methods" accesskey="u" rel="up">Tree methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reference-counting-4"></a>
<h3 class="section">18.3 Reference counting</h3>
<a name="marpa_005ft_005fref"></a><dl>
<dt><a name="index-marpa_005ft_005fref"></a>Function: <em>Marpa_Tree</em> <strong>marpa_t_ref</strong> <em>(Marpa_Tree <var>t</var>)</em></dt>
<dd><p>Increases the reference count by 1.
Not needed by most applications.
</p>
<p>Return value:
On success, <var>t</var>.
On failure, <code>NULL</code>.
</p></dd></dl>
<a name="marpa_005ft_005funref"></a><dl>
<dt><a name="index-marpa_005ft_005funref"></a>Function: <em>void</em> <strong>marpa_t_unref</strong> <em>(Marpa_Tree <var>t</var>)</em></dt>
<dd><p>Decreases the reference count by 1,
destroying <var>t</var> once the reference count reaches
zero.
Beginning with <var>t</var>’s parent ordering,
Libmarpa then proceeds up the chain of parent objects.
Every time a child is destroyed, the
reference count of its parent is decreased by 1.
Every time the reference count of an object
is decreased by 1,
if that reference count is now zero,
that object is destroyed.
Libmarpa follows this chain of decrements
and destructions as required,
all the way back to the
base grammar, if necessary.
</p>
</dd></dl>
<hr>
<a name="Tree-iteration"></a>
<div class="header">
<p>
Previous: <a href="#Tree-reference-counting" accesskey="p" rel="prev">Tree reference counting</a>, Up: <a href="#Tree-methods" accesskey="u" rel="up">Tree methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Iterating-through-the-trees"></a>
<h3 class="section">18.4 Iterating through the trees</h3>
<a name="marpa_005ft_005fnext"></a><dl>
<dt><a name="index-marpa_005ft_005fnext"></a>Function: <em>int</em> <strong>marpa_t_next</strong> <em>( Marpa_Tree <var>t</var>)</em></dt>
<dd><p>Positions <var>t</var> at the next parse tree
in the iteration.
Tree iterators are initialized to the position
before the first parse tree,
so this method must be called before creating a valuator
from a tree.
</p>
<p>If a tree iterator is positioned after the last parse,
the tree is said to be “exhausted”.
A tree iterator for a bocage with no parse trees
is considered to be “exhausted” when initialized.
If the tree iterator is exhausted,
<code>marpa_t_next()</code>
returns -1 as a termination indicator,
and sets the error code to
<code>MARPA_ERR_TREE_EXHAUSTED</code>.
</p>
<p>Return value: On success, a non-negative value.
If the tree iterator is exhausted, -1.
On failure, -2.
</p></dd></dl>
<a name="marpa_005ft_005fparse_005fcount"></a><dl>
<dt><a name="index-marpa_005ft_005fparse_005fcount"></a>Function: <em>int</em> <strong>marpa_t_parse_count</strong> <em>( Marpa_Tree <var>t</var>)</em></dt>
<dd><p>The parse counter counts the number of parse trees
traversed so far.
The count includes the current iteration of the
tree, so that a value of 0 indicates that the tree iterator
is at its initialized position,
before the first parse tree.
</p>
<p>Return value: The number of parses traversed so far.
Always succeeds.
</p></dd></dl>
<hr>
<a name="Value-methods"></a>
<div class="header">
<p>
Next: <a href="#Events" accesskey="n" rel="next">Events</a>, Previous: <a href="#Tree-methods" accesskey="p" rel="prev">Tree methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Value-methods-1"></a>
<h2 class="chapter">19 Value methods</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Value-overview" accesskey="1">Value overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#How-to-use-the-valuator" accesskey="2">How to use the valuator</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Advantages-of-step_002ddriven-valuation" accesskey="3">Advantages of step-driven valuation</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Maintaining-the-stack" accesskey="4">Maintaining the stack</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Valuator-constructor" accesskey="5">Valuator constructor</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Valuator-reference-counting" accesskey="6">Valuator reference counting</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Stepping-through-the-valuator" accesskey="7">Stepping through the valuator</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Valuator-steps-by-type" accesskey="8">Valuator steps by type</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Basic-step-accessors" accesskey="9">Basic step accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Other-step-accessors">Other step accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Value-overview"></a>
<div class="header">
<p>
Next: <a href="#How-to-use-the-valuator" accesskey="n" rel="next">How to use the valuator</a>, Previous: <a href="#Value-methods" accesskey="p" rel="prev">Value methods</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Overview-4"></a>
<h3 class="section">19.1 Overview</h3>
<p>The archetypal application needs
a value object (or
<a name="index-valuator"></a>
<em>valuator</em>) to produce
the value of the parse.
To create a valuator, use the
<code>marpa_v_new()</code>
method.
When a valuator is no longer in use, its memory can be freed
using the
<code>marpa_v_unref()</code>
method.
</p>
<p>The application is required to maintain the stack,
and the application is also required to implement
most of the semantics, including the evaluation
of rules.
Libmarpa’s valuator provides instructions to
the application on how to manipulate the stack.
To iterate through this series of instructions,
use the
<code>marpa_v_step()</code>
method.
</p>
<p>When successful, <code>marpa_v_step()</code>
returns the type
of step.
Most step types have values associated with them.
To access these values use the methods
described in the section <a href="#Basic-step-accessors">Basic step accessors</a>.
How to perform the steps is described in
the sections
<a href="#How-to-use-the-valuator">How to use the valuator</a>
and <a href="#Stepping-through-the-valuator">Stepping through the valuator</a>.
</p>
<hr>
<a name="How-to-use-the-valuator"></a>
<div class="header">
<p>
Next: <a href="#Advantages-of-step_002ddriven-valuation" accesskey="n" rel="next">Advantages of step-driven valuation</a>, Previous: <a href="#Value-overview" accesskey="p" rel="prev">Value overview</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-to-use-the-valuator-1"></a>
<h3 class="section">19.2 How to use the valuator</h3>
<p>Libmarpa’s valuator provides the application with
“steps”, which are
instructions for stack manipulation.
Libmarpa itself does not maintain a stack.
This leaves the upper layer in total control of the
stack and the values which are placed on it.
</p>
<p>As example may make this clearer.
Suppose the evalution is at a place in the parse tree
where an addition is being performed.
Libmarpa does not know that the operation
is an addition.
It will tell the application that rule number <var>R</var>
is to be applied to the arguments at stack locations
<var>N</var> and <var>N</var>+1, and that the result is to placed in
stack location <var>N</var>.
</p>
<p>In this system
the application keeps track of the semantics for all
rules, so it looks up rule <var>R</var> and determines that it
is an addition.
The application can do this by using <var>R</var> as an index
into an array of callbacks, or by any other method
it chooses.
Let’s assume a callback implements the semantics
for rule <var>R</var>.
Libmarpa has told the application that two arguments
are available for this operation, and that they are
at locations <var>N</var> and <var>N</var>+1 in the stack.
They might be the numbers 42 and 711.
So the callback is called with its two arguments,
and produces a return value, let’s say, 753.
Libmarpa has told the application that the result
belongs at location <var>N</var> in the stack,
so the application writes 753 to location <var>N</var>.
</p>
<p>Since Libmarpa knows nothing about the semantics,
the operation for rule R could be string concatenation
instead of addition.
Or, if it is addition, it could allow for its arguments
to be floating point or complex numbers.
Since the application maintains the stack, it is up
to the application whether the stack contains integers,
strings, complex numbers, or polymorphic objects which are
capable of being any of these things and more.
</p>
<hr>
<a name="Advantages-of-step_002ddriven-valuation"></a>
<div class="header">
<p>
Next: <a href="#Maintaining-the-stack" accesskey="n" rel="next">Maintaining the stack</a>, Previous: <a href="#How-to-use-the-valuator" accesskey="p" rel="prev">How to use the valuator</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Advantages-of-step_002ddriven-valuation-1"></a>
<h3 class="section">19.3 Advantages of step-driven valuation</h3>
<p>Step-driven valuation
hides Libmarpa’s grammar rewrites from the application,
and is quite efficient.
Libmarpa knows which rules are sequences.
Libmarpa optimizes stack manipulations based on this knowledge.
Long sequences
are very common in practical grammars.
For these,
the stack manipulations suggested by Libmarpa’s
step-driven valuator
will be significantly faster than the
traditional stack evaluation algorithm.
</p>
<p>Step-driven evalution has another advantage.
To illustrate this,
consider what is a very common case:
The semantics are implemented in a higher-level language,
using callbacks.
If Libmarpa did not use step-driven valuation,
it would need to provide for this case.
But for generality,
Libmarpa would have to deal in C callbacks.
Therefore, a middle layer would have to create C language wrappers
for the callbacks in the higher level language.
</p>
<p>The implementation that results is this:
The higher level language would need to wrap each callback in C.
When calling Libmarpa, it would pass the wrappered callback.
Libmarpa would then need to call the C language “wrappered” callback.
Next, the wrapper would call the higher-level language callback.
The return value,
which would be data native to the higher-level language,
would need to be passed to the C language wrapper,
which will need to make arrangements for it to be based
back to the higher-level language when appropriate.
</p>
<p>A setup like this is not terribly efficient.
And exception handling across language boundaries would be
very tricky.
But neither of these is the worst problem.
</p>
<p>Callbacks are hard to debug.
Wrappered callbacks are even worse.
Calls made across language boundaries
are harder yet to debug.
In the system described above,
by the time a return value is finally consumed,
a language boundary will have been crossed four times.
</p>
<p>How do
Libmarpa users deal with difficulties like this?
Usually, by
doing the absolute minimum possible in the callbacks.
A horrific debugging enviroment can become a manageable
one if there is next to no code to be debugged.
And this can be accomplished by
doing as much as possible in pre- and post-processing.
</p>
<p>In essence, callbacks force applications to do most
of the programming
via side effects.
One need not be a functional programming purist to find
this a very undesirable style of design to force on
an application.
But the ability to debug can make the difference between
code that does work and code that does not.
Unfairly or not,
code is rarely considered well-designed when it does
not work.
</p>
<p>So, while step-driven valuation seems
a roundabout approach,
it is simpler and more direct than
the likely alternatives.
And there is something to be said for pushing
semantics up to the higher levels —
they can be expected to know more about it.
</p>
<p>These advantages of step-driven valuation
are strictly in
the context of a low-level interface.
The author is under no illusion
that direct use of Libmarpa’s valuator will be found
satisfactory by most Libmarpa users,
even those using the C language.
The author certainly avoids using step-driven valuation directly.
Libmarpa’s valuator is intended
to be used via an upper layer,
one which <strong>does</strong> know about semantics.
</p>
<hr>
<a name="Maintaining-the-stack"></a>
<div class="header">
<p>
Next: <a href="#Valuator-constructor" accesskey="n" rel="next">Valuator constructor</a>, Previous: <a href="#Advantages-of-step_002ddriven-valuation" accesskey="p" rel="prev">Advantages of step-driven valuation</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Maintaining-the-stack-1"></a>
<h3 class="section">19.4 Maintaining the stack</h3>
<p>This section discusses in detail the requirements
for maintaining the stack.
In some cases,
such as implementation using a Perl array,
fulfilling these requirements is trivial.
Perl auto-extends its arrays,
and initializes the element values,
on every read or write.
For the C programmer,
things are not quite so easy.
</p>
<p>In this section,
we will assume a C90 or C99 standard-conformant
C application.
This assumption is convenient on two grounds.
First, this will be the intended use
for many readers.
Second, standard-conformant C is
a “worst case”.
Any issue faced by a programmer of another environment
is likely to also be one that must be solved
by the C programmer.
</p>
<p>Libmarpa often
optimizes away unnecessary stack writes
to stack locations.
When it does so, it will not
necessarily optimize away all reads
to that stack location.
This means that a location’s first access,
as suggested by the Libmarpa step instructions,
may be a read.
This possibility
requires a special awareness from the C
programmer,
as discussed in
the sections
<a href="#Sizing-the-stack">Sizing the stack</a> and
<a href="#Initializing-locations-in-the-stack">Initializing locations in the stack</a>.
</p>
<p>In the discussions in this document,
stack locations are non-negative integers.
The bottom of the stack is location 0.
In moving from the bottom of the stack to the top,
the numbers increase.
Stack location <var>Y</var> is said to be “greater”
than stack location <var>X</var> if stack location
<var>Y</var> is closer to the top of stack than location <var>X</var>,
and therefore stack locations are considered greater or
lesser if the integers that represent them are
greater or lesser.
Another way to state that
a stack location <var>Y</var> is greater (lesser)
than stack location <var>X</var> is to say that
a stack location <var>Y</var> is later (earlier)
than stack location <var>X</var>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Sizing-the-stack" accesskey="1">Sizing the stack</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Initializing-locations-in-the-stack" accesskey="2">Initializing locations in the stack</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Sizing-the-stack"></a>
<div class="header">
<p>
Next: <a href="#Initializing-locations-in-the-stack" accesskey="n" rel="next">Initializing locations in the stack</a>, Previous: <a href="#Maintaining-the-stack" accesskey="p" rel="prev">Maintaining the stack</a>, Up: <a href="#Maintaining-the-stack" accesskey="u" rel="up">Maintaining the stack</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Sizing-the-stack-1"></a>
<h4 class="subsection">19.4.1 Sizing the stack</h4>
<p>If an implementation applies Libmarpa’s step
instructions literally, using a physical stack,
it must make sure the stack is large enough.
Specifically, the application must do the following
</p>
<ul>
<li> Ensure location 0 exists — in other
words that the stack is at least length 1.
</li><li> For <code>MARPA_STEP_TOKEN</code> steps,
ensure that location
<code>marpa_v_result(v)</code>
exists.
</li><li> For <code>MARPA_STEP_NULLING_SYMBOL</code> steps,
ensure that location
<code>marpa_v_result(v)</code>
exists.
</li><li> For <code>MARPA_STEP_RULE</code> steps,
ensure that stack locations from
<code>marpa_v_arg_0(v)</code>
to
<code>marpa_v_arg_n(v)</code>
exist.
</li></ul>
<p>Three aspects of these requirements deserve special mention.
First,
note that the requirement for a
<code>MARPA_STEP_RULE</code> is that the application
size the stack to include the arguments to be
read.
Because stack writes may be optimized away,
an application,
when reading,
cannot assume
that the stack was
sized appropriately by a prior write.
The first access to a new stack location may be
a read.
</p>
<p>Second,
note that there is no explicit requirement that
the application size the stack to include the
location for the result of the
<code>MARPA_STEP_RULE</code> step.
An application is allowed to assume that
result will go into one of the locations
that were read.
</p>
<p>Third, special note should be made of the requirement
that location 0 exist.
By convention, the parse result resides
in location 0 of the stack.
Because of potential optimizations,
an application cannot assume that it
will receive a Libmarpa step instruction that
either reads from or writes to location 0.
</p>
<hr>
<a name="Initializing-locations-in-the-stack"></a>
<div class="header">
<p>
Previous: <a href="#Sizing-the-stack" accesskey="p" rel="prev">Sizing the stack</a>, Up: <a href="#Maintaining-the-stack" accesskey="u" rel="up">Maintaining the stack</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Initializing-locations-in-the-stack-1"></a>
<h4 class="subsection">19.4.2 Initializing locations in the stack</h4>
<p>Write optimizations also creates issues for implementations
which require data to be initialized before reading.
Every fully standard-conforming C application is such an
implementation.
Both C90 and C99 allow “trap values”,
and therefore conforming applications must be
prepared for
an uninitialized location to contain one of those.
Reading a trap value may cause an abend.
(It is safe, in standard-conforming C, to write to a location
containing a trap value.)
</p>
<p>The requirement that locations be initialized before
reading occurs in other implementations.
Any implementation that has a “universe” of “safe” values,
may require special precautions.
The required precautions may amount to a need to initialize
“uninitialized” values.
A practical example might be an implementation that expects
all locations to contain a pointer which it can safely indirect
from.
In such implementations,
just as in standard-conformant C,
every stack location
needs to be initialized before being read.
</p>
<p>Due to write optimizations, an application
cannot rely on Libmarpa’s step instructions to
initialize every stack location before its first read.
One way to safely deal with the
initialization of stack locations,
is to do all of the following:
</p><ul>
<li> When starting evaluation, ensure that the stack contains at least location 0.
</li><li> Also, when starting evaluation, initialize every location in the stack.
</li><li> Whenever the stack is extended,
initialize every stack location added.
</li></ul>
<p>Applications which try to optimize out some of
these initializations
need to be aware that
an application can never assume that activity in
the stack is safely “beyond” an uninitialized location.
Libmarpa steps often revisit earlier sections of the stack,
and these revisits may include reads of previously
unvisited stack locations.
</p>
<hr>
<a name="Valuator-constructor"></a>
<div class="header">
<p>
Next: <a href="#Valuator-reference-counting" accesskey="n" rel="next">Valuator reference counting</a>, Previous: <a href="#Maintaining-the-stack" accesskey="p" rel="prev">Maintaining the stack</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Creating-a-new-valuator"></a>
<h3 class="section">19.5 Creating a new valuator</h3>
<a name="marpa_005fv_005fnew"></a><dl>
<dt><a name="index-marpa_005fv_005fnew"></a>Function: <em>Marpa_Value</em> <strong>marpa_v_new</strong> <em>( Marpa_Tree <var>t</var> )</em></dt>
<dd><p>Creates a new valuator.
The parent object of the new valuator
will be the tree iterator <var>t</var>,
and the reference count of the new valuator will be 1.
The reference count of <var>t</var> is increased by 1.
</p>
<p>The parent tree iterator is “paused”,
so that the tree iterator
cannot move on to a new parse tree
until the valuator is destroyed.
Many valuators of the same parse tree
can exist at once.
A tree iterator is “unpaused” when
all of the valuators of that tree iterator are destroyed.
</p>
<p>Return value: On success, the newly created valuator.
On failure, <code>NULL</code>.
</p></dd></dl>
<hr>
<a name="Valuator-reference-counting"></a>
<div class="header">
<p>
Next: <a href="#Stepping-through-the-valuator" accesskey="n" rel="next">Stepping through the valuator</a>, Previous: <a href="#Valuator-constructor" accesskey="p" rel="prev">Valuator constructor</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reference-counting-5"></a>
<h3 class="section">19.6 Reference counting</h3>
<a name="marpa_005fv_005fref"></a><dl>
<dt><a name="index-marpa_005fv_005fref"></a>Function: <em>Marpa_Value</em> <strong>marpa_v_ref</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>Increases the reference count by 1.
Not needed by most applications.
</p>
<p>Return value:
On success, <var>v</var>.
On failure, <code>NULL</code>.
</p></dd></dl>
<a name="marpa_005fv_005funref"></a><dl>
<dt><a name="index-marpa_005fv_005funref"></a>Function: <em>void</em> <strong>marpa_v_unref</strong> <em>( Marpa_Value <var>v</var>)</em></dt>
<dd><p>Decreases the reference count by 1,
destroying <var>v</var> once the reference count reaches
zero.
Beginning with <var>v</var>’s parent tree,
Libmarpa then proceeds up the chain of parent objects.
Every time a child is destroyed, the
reference count of its parent is decreased by 1.
Every time the reference count of an object
is decreased by 1,
if that reference count is now zero,
that object is destroyed.
Libmarpa follows this chain of decrements
and destructions as required,
all the way back to the
base grammar, if necessary.
</p>
</dd></dl>
<hr>
<a name="Stepping-through-the-valuator"></a>
<div class="header">
<p>
Next: <a href="#Valuator-steps-by-type" accesskey="n" rel="next">Valuator steps by type</a>, Previous: <a href="#Valuator-reference-counting" accesskey="p" rel="prev">Valuator reference counting</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Stepping-through-the-valuator-1"></a>
<h3 class="section">19.7 Stepping through the valuator</h3>
<a name="marpa_005fv_005fstep"></a><dl>
<dt><a name="index-marpa_005fv_005fstep"></a>Function: <em>Marpa_Step_Type</em> <strong>marpa_v_step</strong> <em>( Marpa_Value <var>v</var>)</em></dt>
<dd><p>This method “steps through” the valuator.
The return value is a <code>Marpa_Step_Type</code>,
an integer which indicates the type of step.
How the application is expected to act on
each step is described below
(<a href="#Valuator-steps-by-type">Valuator steps by type</a>).
When the iteration through the steps is finished,
<code>marpa_v_step()</code>
returns <code>MARPA_STEP_INACTIVE</code>.
</p>
<p>Return value: On success, a <code>Marpa_Step_Type</code>,
which always be a non-negative integer.
On failure, -2.
</p>
</dd></dl>
<hr>
<a name="Valuator-steps-by-type"></a>
<div class="header">
<p>
Next: <a href="#Basic-step-accessors" accesskey="n" rel="next">Basic step accessors</a>, Previous: <a href="#Stepping-through-the-valuator" accesskey="p" rel="prev">Stepping through the valuator</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Valuator-steps-by-type-1"></a>
<h3 class="section">19.8 Valuator steps by type</h3>
<dl>
<dt><a name="index-MARPA_005fSTEP_005fRULE"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_RULE</strong></dt>
<dd><p>The semantics of a rule should be performed.
The application can find the value of the rule’s
children in the stack locations from
<code>marpa_v_arg_0(v)</code>
to
<code>marpa_v_arg_n(v)</code>.
The semantics for the rule whose ID is
<code>marpa_v_rule(v)</code>
should be executed
on these child values,
and the result placed in
<code>marpa_v_result(v)</code>.
In the case of a <code>MARPA_STEP_RULE</code> step,
the stack location of
<code>marpa_v_result(v)</code>
is guaranteed to
be equal to
<code>marpa_v_arg_0(v)</code>.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fSTEP_005fTOKEN"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_TOKEN</strong></dt>
<dd><p>The semantics of a non-null token should be performed.
The application’s value for the token whose ID is
<code>marpa_v_token(v)</code>
should be
placed in
stack location
<code>marpa_v_result(v)</code>.
Its value according to Libmarpa will be in
<code>marpa_v_token_value(v)</code>.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fSTEP_005fNULLING_005fSYMBOL"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_NULLING_SYMBOL</strong></dt>
<dd><p>The semantics for a nulling symbol should be performed.
The ID of the symbol is
<code>marpa_v_symbol(v)</code>
and its value should
be placed in
stack location
<code>marpa_v_result(v)</code>.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fSTEP_005fINACTIVE"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_INACTIVE</strong></dt>
<dd><p>The valuator has gone through all of its steps
and is now inactive.
The value of the parse will be in stack location 0.
Because of optimizations,
it is possible for valuator to immediately
became inactive — <code>MARPA_STEP_INACTIVE</code> could
be both the first and last step.
</p>
</dd></dl>
<dl>
<dt><a name="index-MARPA_005fSTEP_005fINITIAL"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_INITIAL</strong></dt>
<dd><p>The valuator is new and has
yet to go through any steps.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fSTEP_005fINTERNAL1"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_INTERNAL1</strong></dt>
<dt><a name="index-MARPA_005fSTEP_005fINTERNAL2"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_INTERNAL2</strong></dt>
<dt><a name="index-MARPA_005fSTEP_005fTRACE"></a>Macro: <em>Marpa_Step_Type</em> <strong>MARPA_STEP_TRACE</strong></dt>
<dd><p>These step types are reserved for internal purposes.
</p></dd></dl>
<hr>
<a name="Basic-step-accessors"></a>
<div class="header">
<p>
Next: <a href="#Other-step-accessors" accesskey="n" rel="next">Other step accessors</a>, Previous: <a href="#Valuator-steps-by-type" accesskey="p" rel="prev">Valuator steps by type</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Basic-step-accessors-1"></a>
<h3 class="section">19.9 Basic step accessors</h3>
<p>The basic step accessors are so called because their information
is basic to the stack manipulation.
The basic step accessors are implemented as macros.
They always succeed.
</p>
<dl>
<dt><a name="index-marpa_005fv_005farg_005f0"></a>Macro: <em>int</em> <strong>marpa_v_arg_0</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For a <code>MARPA_STEP_RULE</code> step,
returns the stack location where the value of first child
can be found.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005farg_005fn"></a>Macro: <em>int</em> <strong>marpa_v_arg_n</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For a <code>MARPA_STEP_RULE</code> step,
returns the stack location where the value of the last child
can be found.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005fresult"></a>Macro: <em>int</em> <strong>marpa_v_result</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For <code>MARPA_STEP_RULE</code>,
<code>MARPA_STEP_TOKEN</code>,
and <code>MARPA_STEP_NULLING_SYMBOL</code> steps,
returns the stack location where the result of the semantics
should be placed.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005frule"></a>Macro: <em>Marpa_Rule_ID</em> <strong>marpa_v_rule</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For the
<code>MARPA_STEP_RULE</code> step,
returns the ID of the rule.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005fstep_005ftype"></a>Macro: <em>Marpa_Step_Type</em> <strong>marpa_v_step_type</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>Returns the current step type:
<code>MARPA_STEP_TOKEN</code>,
<code>MARPA_STEP_RULE</code>,
etc.
Usually not needed since this is also the return value of
<code>marpa_v_step()</code>.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005fsymbol"></a>Macro: <em>Marpa_Symbol_ID</em> <strong>marpa_v_symbol</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For the <code>MARPA_STEP_NULLING_SYMBOL</code> step,
returns the ID of the symbol.
The value returned is the same as that
returned by the
<code>marpa_v_token()</code>
macro.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005ftoken"></a>Macro: <em>Marpa_Symbol_ID</em> <strong>marpa_v_token</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For the <code>MARPA_STEP_TOKEN</code> step,
returns the ID of the token.
The value returned is the same as that
returned by the
<code>marpa_v_symbol()</code>
macro.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005ftoken_005fvalue"></a>Macro: <em>int</em> <strong>marpa_v_token_value</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>For the <code>MARPA_STEP_TOKEN</code> step,
returns the integer which is
(or which represents)
the value of the token.
</p></dd></dl>
<hr>
<a name="Other-step-accessors"></a>
<div class="header">
<p>
Previous: <a href="#Basic-step-accessors" accesskey="p" rel="prev">Basic step accessors</a>, Up: <a href="#Value-methods" accesskey="u" rel="up">Value methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Other-step-accessors-1"></a>
<h3 class="section">19.10 Other step accessors</h3>
<p>This section contains the step accessors that
are not basic to stack manipulation, but which provide
other useful information about the parse.
These step accessors are implemented as macros.
</p>
<p>All of these accessors always succeed, but
if called when they are irrelevant
they return an unspecified value.
In this context, an “unspecified value” is a value
that is either -1 or the ID of a valid Earley set,
but which is otherwise unpredictable.
</p>
<dl>
<dt><a name="index-marpa_005fv_005fes_005fid"></a>Macro: <em>Marpa_Earley_Set_ID</em> <strong>marpa_v_es_id</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>Return value:
If the current step type is <code>MARPA_STEP_RULE</code>,
the Earley Set ordinal where the rule ends.
If the current step type is
<code>MARPA_STEP_TOKEN</code>
or <code>MARPA_STEP_NULLING_SYMBOL</code>,
the Earley Set ordinal where the symbol ends.
If the current step type is anything else, an unspecified value.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005frule_005fstart_005fes_005fid"></a>Macro: <em>Marpa_Earley_Set_ID</em> <strong>marpa_v_rule_start_es_id</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>Return value:
If the current step type is <code>MARPA_STEP_RULE</code>,
the Earley Set ordinal where the rule begins.
If the current step type is anything else, an unspecified value.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fv_005ftoken_005fstart_005fes_005fid"></a>Macro: <em>Marpa_Earley_Set_ID</em> <strong>marpa_v_token_start_es_id</strong> <em>(Marpa_Value <var>v</var>)</em></dt>
<dd><p>Return value:
If the current step type is <code>MARPA_STEP_TOKEN</code>
or <code>MARPA_STEP_NULLING_SYMBOL</code>,
the Earley Set ordinal where the token begins.
If the current step type is anything else, an unspecified value.
</p></dd></dl>
<hr>
<a name="Events"></a>
<div class="header">
<p>
Next: <a href="#Error-methods-macros-and-codes" accesskey="n" rel="next">Error methods macros and codes</a>, Previous: <a href="#Value-methods" accesskey="p" rel="prev">Value methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Events-1"></a>
<h2 class="chapter">20 Events</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Events-overview" accesskey="1">Events overview</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Basic-event-accessors" accesskey="2">Basic event accessors</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Completion-events" accesskey="3">Completion events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Symbol-nulled-events" accesskey="4">Symbol nulled events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Prediction-events" accesskey="5">Prediction events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Symbol-expected-events" accesskey="6">Symbol expected events</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Event-codes" accesskey="7">Event codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Events-overview"></a>
<div class="header">
<p>
Next: <a href="#Basic-event-accessors" accesskey="n" rel="next">Basic event accessors</a>, Previous: <a href="#Events" accesskey="p" rel="prev">Events</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Overview-5"></a>
<h3 class="section">20.1 Overview</h3>
<p>Events are generated by the
<code>marpa_g_precompute()</code>,
<code>marpa_r_earleme_complete()</code>,
and
<code>marpa_r_start_input()</code>
methods.
The methods are called event-active.
Event-active methods always clear all previous events,
so that after an event-active method the only events
available
will be those generated by that method.
</p>
<p>Some Libmarpa methods clear the event queue.
The user is expected to query events
immediately after the method that generated them.
We note especially that events are kept in the base grammar,
so that multiple recognizers using the same base grammar
overwrite each other’s events.
</p>
<p>To find out how many events were generated by the last
event-active method,
use the
<code>marpa_g_event_count()</code>
method.
</p>
<p>To query a specific event,
use the
<code>marpa_g_event()</code>
and
<code>marpa_g_event_value()</code>
methods.
</p>
<p>In reading this chapter, we will need to be aware that it contains
a mixture of grammar and recognizer methods.
</p>
<hr>
<a name="Basic-event-accessors"></a>
<div class="header">
<p>
Next: <a href="#Completion-events" accesskey="n" rel="next">Completion events</a>, Previous: <a href="#Events-overview" accesskey="p" rel="prev">Events overview</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Basic-event-accessors-1"></a>
<h3 class="section">20.2 Basic event accessors</h3>
<a name="marpa_005fg_005fevent"></a><dl>
<dt><a name="index-marpa_005fg_005fevent"></a>Function: <em>Marpa_Event_Type</em> <strong>marpa_g_event</strong> <em>(Marpa_Grammar <var>g</var>, Marpa_Event* <var>event</var>, int <var>ix</var>)</em></dt>
<dd><p>On success,
the type of the <var>ix</var>’th event is returned
and the data for the <var>ix</var>’th event is placed
in the location pointed to by <var>event</var>.
</p>
<p>Event indexes are in sequence.
Valid events will be in the range from 0 to <var>n</var>,
where <var>n</var> is one less than the event count.
The event count
can be queried using the
<code>marpa_g_event_count()</code>
method.
</p>
<p>Return value: On success, the type of event <var>ix</var>.
If there is no <var>ix</var>’th event,
if <var>ix</var> is negative,
or on other failure, -2.
On failure,
the locations pointed to by <var>event</var>
are not changed.
</p></dd></dl>
<a name="marpa_005fg_005fevent_005fcount"></a><dl>
<dt><a name="index-marpa_005fg_005fevent_005fcount"></a>Function: <em>int</em> <strong>marpa_g_event_count</strong> <em>( Marpa_Grammar g )</em></dt>
<dd><p>Return value: On success, the number of events.
On failure, -2.
</p></dd></dl>
<dl>
<dt><a name="index-marpa_005fg_005fevent_005fvalue"></a>Macro: <em>int</em> <strong>marpa_g_event_value</strong> <em>(Marpa_Event* <var>event</var>)</em></dt>
<dd><p>This macro provides access to the “value” of the event.
The semantics of the value varies according to the type
of the event, and is described in the section on event
codes (<a href="#Event-codes">Event codes</a>).
</p></dd></dl>
<hr>
<a name="Completion-events"></a>
<div class="header">
<p>
Next: <a href="#Symbol-nulled-events" accesskey="n" rel="next">Symbol nulled events</a>, Previous: <a href="#Basic-event-accessors" accesskey="p" rel="prev">Basic event accessors</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Completion-events-1"></a>
<h3 class="section">20.3 Completion events</h3>
<a name="marpa_005fg_005fcompletion_005fsymbol_005factivate"></a><dl>
<dt><a name="index-marpa_005fg_005fcompletion_005fsymbol_005factivate"></a>Function: <em>int</em> <strong>marpa_g_completion_symbol_activate</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>reactivate</var> )</em></dt>
<dd>
<p>Allows the user to deactivate and reactivate symbol completion
events in the grammar.
When a recognizer is created,
the activation status of each of its events is initialized
to the activation status of that event in the base grammar.
If <var>reactivate</var> is zero, the event is deactivated
in the grammar.
If <var>reactivate</var> is one, the event is activated
in the grammar.
</p>
<p>Symbol completion events are active by default if
the symbol was set up for completion events in the
grammar.
If a symbol was not set up for completion events in
the grammar, symbol completion events are inactive
by default and any attempt to change that is a fatal error.
</p>
<p>The activation status of a completion event in the grammar
can only be changed if the symbol is marked as a completion event symbol
in the grammar,
and before
the grammar is precomputed.
However, if a symbol is marked as a completion event symbol in
the recognizer,
the completion event can be deactivated
and reactivated in the recognizer.
</p>
<p>Success cases:
On success,
the method returns the value of <var>reactivate</var>.
The method succeeds trivially
if the symbol is already set as indicated by
<var>reactivate</var>.
</p>
<p>Failure cases:
If the active status
of the
completion event for <var>sym_id</var>
cannot be set as indicated by <var>reactivate</var>,
the method fails.
On failure, -2 is returned.
</p></dd></dl>
<a name="marpa_005fr_005fcompletion_005fsymbol_005factivate"></a><dl>
<dt><a name="index-marpa_005fr_005fcompletion_005fsymbol_005factivate"></a>Function: <em>int</em> <strong>marpa_r_completion_symbol_activate</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>reactivate</var> )</em></dt>
<dd>
<p>Allows the user to deactivate and reactivate symbol completion
events in the recognizer.
If <var>reactivate</var> is zero, the event is deactivated.
If <var>reactivate</var> is one, the event is activated.
</p>
<p>Symbol completion events are active by default if
the symbol was set up for completion events in the
grammar.
If a symbol was not set up for completion events in
the grammar, symbol completion events are inactive
by default and any attempt to change that is a fatal error.
</p>
<p>Success cases:
On success,
the method returns the value of <var>reactivate</var>.
The method succeeds trivially
if the symbol is already set as indicated by
<var>reactivate</var>.
</p>
<p>Failure cases:
If the active status
of the
completion event for <var>sym_id</var>
cannot be set as indicated by <var>reactivate</var>,
the method fails.
On failure, -2 is returned.
</p></dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fcompletion_005fevent"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fcompletion_005fevent"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_completion_event</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd><a name="marpa_005fg_005fsymbol_005fis_005fcompletion_005fevent_005fset"></a></dd><dt><a name="index-marpa_005fg_005fsymbol_005fis_005fcompletion_005fevent_005fset"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_completion_event_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>value</var>)</em></dt>
<dd>
<p>Libmarpa can be set up to generate an
<code>MARPA_EVENT_SYMBOL_COMPLETED</code>
event whenever the symbol is completed.
A symbol is said to be <strong>completed</strong>
when a non-nulling rule with
that symbol on its LHS is completed.
</p>
<p>For completion events to occur, the symbol must be marked
as a completion event symbol.
The
<code>marpa_g_symbol_is_completion_event_set()</code>
function
marks symbol <var>sym_id</var> as a completion event symbol
if <var>value</var> is 1,
and unmarks it
it as a completion event symbol if <var>value</var> is 0.
The
<code>marpa_g_symbol_is_completion_event()</code>
method
returns the current value of the completion event marking
for symbol <var>sym_id</var>.
</p>
<p>Marking a completion event sets its activation status to on.
Unmarking a completion event sets its activation status to off.
The completion event marking cannot be changed once
the grammar is precomputed.
</p>
<p>If a completion event is marked,
its activation status can be changed using the
<code>marpa_g_completion_symbol_activate()</code>
method.
Note that, if a symbol is marked as a completion event symbol
in the recognizer,
its completion event can be deactivated
and reactivated in the recognizer.
</p>
<p>Nulled rules and symbols will never cause completion events.
Nullable symbols
may be marked as completion event symbols,
but this will have an effect only when the symbol
is not nulled.
Nulling symbols
may be marked as completion event symbols,
but no completion events will ever be generated
for a nulling symbol.
Note that this implies at no completion event will
ever be generated at earleme 0,
the start of parsing.
</p>
<p>Success: On success, 1 if symbol <var>sym_id</var>
is a completion event symbol after the
call, 0 otherwise.
</p>
<p>Failures:
If <var>sym_id</var> is well-formed, but there is no
such symbol, -1.
If the grammar <var>g</var> is precomputed;
or on other failure, -2.
</p></dd></dl>
<hr>
<a name="Symbol-nulled-events"></a>
<div class="header">
<p>
Next: <a href="#Prediction-events" accesskey="n" rel="next">Prediction events</a>, Previous: <a href="#Completion-events" accesskey="p" rel="prev">Completion events</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Symbol-nulled-events-1"></a>
<h3 class="section">20.4 Symbol nulled events</h3>
<a name="marpa_005fg_005fnulled_005fsymbol_005factivate"></a><dl>
<dt><a name="index-marpa_005fg_005fnulled_005fsymbol_005factivate"></a>Function: <em>int</em> <strong>marpa_g_nulled_symbol_activate</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>reactivate</var> )</em></dt>
<dd>
<p>Allows the user to deactivate and reactivate symbol nulled
events in the grammar.
When a recognizer is created,
the activation status of each of its events is initialized
to the activation status of that event in the base grammar.
If <var>reactivate</var> is zero, the event is deactivated
in the grammar.
If <var>reactivate</var> is one, the event is activated
in the grammar.
</p>
<p>Symbol nulled events are active by default if
the symbol was set up for nulled events in the
grammar.
If a symbol was not set up for nulled events in
the grammar, symbol nulled events are inactive
by default and any attempt to change that is a fatal error.
</p>
<p>The activation status of a nulled event in the grammar
can only be changed if the symbol is marked as a nulled event symbol
in the grammar,
and before
the grammar is precomputed.
However, if a symbol is marked as a nulled event symbol in
the recognizer,
the nulled event can be deactivated
and reactivated in the recognizer.
</p>
<p>Success cases:
On success,
the method returns the value of <var>reactivate</var>.
The method succeeds trivially
if the symbol is already set as indicated by
<var>reactivate</var>.
</p>
<p>Failure cases:
If the active status
of the
nulled event for <var>sym_id</var>
cannot be set as indicated by <var>reactivate</var>,
the method fails.
On failure, -2 is returned.
</p></dd></dl>
<a name="marpa_005fr_005fnulled_005fsymbol_005factivate"></a><dl>
<dt><a name="index-marpa_005fr_005fnulled_005fsymbol_005factivate"></a>Function: <em>int</em> <strong>marpa_r_nulled_symbol_activate</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>boolean</var> )</em></dt>
<dd>
<p>Allows the user to deactivate and reactivate symbol nulled
events in the recognizer.
If <var>boolean</var> is zero, the event is deactivated.
If <var>boolean</var> is one, the event is activated.
</p>
<p>Symbol nulled events are active by default if
the symbol was set up for nulled events in the
grammar.
If a symbol was not set up for nulled events in
the grammar, symbol nulled events are inactive
by default and any attempt to change that is a fatal error.
</p>
<p>Success cases:
On success,
the method returns the value of <var>boolean</var>.
The method succeeds trivially
if the symbol is already set as indicated by
<var>boolean</var>.
</p>
<p>Failure cases:
If the active status
of the
nulled event for <var>sym_id</var>
cannot be set as indicated by <var>boolean</var>,
the method fails.
On failure, -2 is returned.
</p></dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fnulled_005fevent"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fnulled_005fevent"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_nulled_event</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd><a name="marpa_005fg_005fsymbol_005fis_005fnulled_005fevent_005fset"></a></dd><dt><a name="index-marpa_005fg_005fsymbol_005fis_005fnulled_005fevent_005fset"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_nulled_event_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>value</var>)</em></dt>
<dd>
<p>Libmarpa can set up to generate
an <code>MARPA_EVENT_SYMBOL_NULLED</code>
event whenever the symbol is nulled.
A symbol is said to be <strong>nulled</strong>
when a zero length instance of that symbol
is recognized.
</p>
<p>For nulled events to occur, the symbol must be marked
as a nulled event symbol.
The
<code>marpa_g_symbol_is_nulled_event_set()</code>
function
marks symbol <var>sym_id</var> as a nulled event symbol
if <var>value</var> is 1,
and unmarks it
it as a nulled event symbol if <var>value</var> is 0.
The
<code>marpa_g_symbol_is_nulled_event()</code>
method
returns the current value of the nulled event marking
for symbol <var>sym_id</var>.
</p>
<p>Marking a nulled event sets its activation status to on.
Unmarking a nulled event sets its activation status to off.
The nulled event marking cannot be changed once
the grammar is precomputed.
</p>
<p>If a nulled event is marked,
its activation status can be changed using the
<code>marpa_g_nulled_symbol_activate()</code>
method.
Note that, if a symbol is marked as a nulled event symbol
in the recognizer,
its nulled event can be deactivated
and reactivated in the recognizer.
</p>
<p>As a reminder, a symbol instance is a symbol
at a specific location in the input,
and with a specific length.
Also, whenever a nulled symbol instance is
recognized at a location, it is acceptable
at that location,
and vice versa.
</p>
<p>When a symbol instance is recognized at a location,
it will generate a nulled event or a prediction event,
but never both.
A symbol instance of zero length,
when recognized at a location,
generates a nulled event at that location,
and does not generate a completion event.
A symbol instance of non-zero length,
when acceptable at a location,
generates a completion event at that location,
and does not generate a nulled event.
</p>
<p>When a symbol instance is acceptable at a location,
it will generate a nulled event or a prediction event,
but never both.
A symbol instance of zero length,
when acceptable at a location,
generates a nulled event at that location,
and does not generate a prediction event.
A symbol instance of non-zero length,
when acceptable at a location,
generates a prediction event at that location,
and does not generate a nulled event.
</p>
<p>While it is not possible for
a <strong>symbol instance</strong>
to generate both a nulled event and
a completion event at a location,
it is quite possible that
a <strong>symbol</strong> might generate
both kinds of event at that location.
This is because multiple instances
of the same symbol may be recognized at
a given location,
and these instances will have
different lengths.
If one instance is recognized at a given location
as zero length and
a second, non-zero-length,
instance is recognized at the same location,
the first will generate only nulled events,
while the second will generate only completion events.
For similar reasons,
while a <strong>symbol instance</strong> will never
generate both a null event and a prediction
event at a location,
multiple instances of the same symbol
may do so.
</p>
<p>Zero length derivations can be ambiguous.
When a zero length symbol is recognized,
all of its zero-length derivations are also considered to be
recognized.
</p>
<p>The
<code>marpa_g_symbol_is_nulled_event_set()</code>
method will
mark a symbol as a nulled event symbol,
even if the symbol is non-nullable.
This is convenient, for example,
for automatically generated grammars.
Applications which wish to treat
it as a failure if there is an
attempt to
mark a non-nullable symbol
as a nulled event symbol,
can check for this case using
the
<code>marpa_g_symbol_is_nullable()</code>
method.
</p>
<p>Success: On success, 1 if symbol <var>sym_id</var>
is a nulled event symbol after the
call, 0 otherwise.
</p>
<p>Failures:
If <var>sym_id</var> is well-formed, but there is no
such symbol, -1.
If the grammar <var>g</var> is precomputed;
or on other failure, -2.
</p></dd></dl>
<hr>
<a name="Prediction-events"></a>
<div class="header">
<p>
Next: <a href="#Symbol-expected-events" accesskey="n" rel="next">Symbol expected events</a>, Previous: <a href="#Symbol-nulled-events" accesskey="p" rel="prev">Symbol nulled events</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Prediction-events-1"></a>
<h3 class="section">20.5 Prediction events</h3>
<a name="marpa_005fg_005fprediction_005fsymbol_005factivate"></a><dl>
<dt><a name="index-marpa_005fg_005fprediction_005fsymbol_005factivate"></a>Function: <em>int</em> <strong>marpa_g_prediction_symbol_activate</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>reactivate</var> )</em></dt>
<dd>
<p>Allows the user to deactivate and reactivate symbol prediction
events in the grammar.
When a recognizer is created,
the activation status of each of its events is initialized
to the activation status of that event in the base grammar.
If <var>reactivate</var> is zero, the event is deactivated
in the grammar.
If <var>reactivate</var> is one, the event is activated
in the grammar.
</p>
<p>Symbol prediction events are active by default if
the symbol was set up for prediction events in the
grammar.
If a symbol was not set up for prediction events in
the grammar, symbol prediction events are inactive
by default and any attempt to change that is a fatal error.
</p>
<p>The activation status of a prediction event in the grammar
can only be changed if the symbol is marked as a prediction event symbol
in the grammar,
and before
the grammar is precomputed.
However, if a symbol is marked as a prediction event symbol in
the recognizer,
the prediction event can be deactivated
and reactivated in the recognizer.
</p>
<p>Success cases:
On success,
the method returns the value of <var>reactivate</var>.
The method succeeds trivially
if the symbol is already set as indicated by
<var>reactivate</var>.
</p>
<p>Failure cases:
If the active status
of the
prediction event for <var>sym_id</var>
cannot be set as indicated by <var>reactivate</var>,
the method fails.
On failure, -2 is returned.
</p></dd></dl>
<a name="marpa_005fr_005fprediction_005fsymbol_005factivate"></a><dl>
<dt><a name="index-marpa_005fr_005fprediction_005fsymbol_005factivate"></a>Function: <em>int</em> <strong>marpa_r_prediction_symbol_activate</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>boolean</var> )</em></dt>
<dd>
<p>Allows the user to deactivate and reactivate symbol prediction
events in the recognizer.
If <var>boolean</var> is zero, the event is deactivated.
If <var>boolean</var> is one, the event is activated.
</p>
<p>Symbol prediction events are active by default if
the symbol was set up for prediction events in the
grammar.
If a symbol was not set up for prediction events in
the grammar, symbol prediction events are inactive
by default and any attempt to change that is a fatal error.
</p>
<p>Success cases:
On success,
the method returns the value of <var>boolean</var>.
The method succeeds trivially
if the symbol is already set as indicated by
<var>boolean</var>.
</p>
<p>Failure cases:
If the active status
of the
prediction event for <var>sym_id</var>
cannot be set as indicated by <var>boolean</var>,
the method fails.
On failure, -2 is returned.
</p></dd></dl>
<a name="marpa_005fg_005fsymbol_005fis_005fprediction_005fevent"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fprediction_005fevent"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_prediction_event</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>)</em></dt>
<dd><a name="marpa_005fg_005fsymbol_005fis_005fprediction_005fevent_005fset"></a></dd><dt><a name="index-marpa_005fg_005fsymbol_005fis_005fprediction_005fevent_005fset"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_prediction_event_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>value</var>)</em></dt>
<dd>
<p>Libmarpa can be set up
to generate a
<code>MARPA_EVENT_SYMBOL_PREDICTED</code>
event when a non-nulled symbol is predicted.
A non-nulled symbol is said to be <strong>predicted</strong>
when a instance of it
is acceptable at the current
earleme according to the grammar.
Nulled symbols do not generate predictions.
</p>
<p>For predicted events to occur, the symbol must be marked
as a predicted event symbol.
The
<code>marpa_g_symbol_is_predicted_event_set()</code>
function
marks symbol <var>sym_id</var> as a predicted event symbol
if <var>value</var> is 1,
and unmarks it
it as a predicted event symbol if <var>value</var> is 0.
The
<code>marpa_g_symbol_is_predicted_event()</code>
method
returns the current value of the predicted event marking
for symbol <var>sym_id</var>.
</p>
<p>Marking a prediction event sets its activation status to on.
Unmarking a prediction event sets its activation status to off.
The prediction event marking cannot be changed once
the grammar is precomputed.
</p>
<p>If a prediction event is marked,
its activation status can be changed using the
<code>marpa_g_prediction_symbol_activate()</code>
method.
Note that, if a symbol is marked as a prediction event symbol
in the recognizer,
its prediction event can be deactivated
and reactivated in the recognizer.
</p>
<p>Success: On success, 1 if symbol <var>sym_id</var>
is a predicted event symbol after the
call, 0 otherwise.
</p>
<p>Failures:
If <var>sym_id</var> is well-formed, but there is no
such symbol, -1.
If the grammar <var>g</var> is precomputed;
or on other failure, -2.
</p></dd></dl>
<hr>
<a name="Symbol-expected-events"></a>
<div class="header">
<p>
Next: <a href="#Event-codes" accesskey="n" rel="next">Event codes</a>, Previous: <a href="#Prediction-events" accesskey="p" rel="prev">Prediction events</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Symbol-expected-events-1"></a>
<h3 class="section">20.6 Symbol expected events</h3>
<a name="marpa_005fr_005fexpected_005fsymbol_005fevent_005fset"></a><dl>
<dt><a name="index-marpa_005fr_005fexpected_005fsymbol_005fevent_005fset"></a>Function: <em>int</em> <strong>marpa_r_expected_symbol_event_set</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Symbol_ID <var>symbol_id</var>, int <var>value</var>)</em></dt>
<dd><p>Sets the “expected symbol event bit” for <var>symbol_id</var> to <var>value</var>.
A recognizer event is created whenever
symbol <var>symbol_id</var> is expected at the current earleme.
if and only if the expected symbol event bit
for <var>symbol_id</var> is 1.
The “expected symbol event bit” must be 1 or 0.
</p>
<p>In this context, “expected” means “expected as a terminal”.
Even if a symbol is predicted at the current earleme,
if it is not acceptable as a terminal,
it does not trigger an
“expected symbol event”.
</p>
<p>By default, the “expected symbol event bit” is 0.
It is an error to attempt to set the
“expected symbol event bit” to 1 for a nulling symbol,
an inaccessible symbol,
or an unproductive symbol.
</p>
<p>Return value:
The value of the event bit after the method call is finished.
-2 if <var>symbol_id</var> is not the ID of a valid symbol;
if it is the ID of an nulling, inaccessible for unproductive symbol;
or on other failure.
</p></dd></dl>
<hr>
<a name="Event-codes"></a>
<div class="header">
<p>
Previous: <a href="#Symbol-expected-events" accesskey="p" rel="prev">Symbol expected events</a>, Up: <a href="#Events" accesskey="u" rel="up">Events</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Event-codes-1"></a>
<h3 class="section">20.7 Event codes</h3>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fNONE"></a>Macro: <em>int</em> <strong>MARPA_EVENT_NONE</strong></dt>
<dd><p>Applications should never see this event.
Event value: Undefined.
Suggested message: "No event".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fCOUNTED_005fNULLABLE"></a>Macro: <em>int</em> <strong>MARPA_EVENT_COUNTED_NULLABLE</strong></dt>
<dd><p>A nullable symbol is either the separator
for, or the right hand side of, a sequence.
Event value: The ID of the symbol.
Suggested message: "This symbol is a counted nullable".
</p></dd></dl>
<a name="MARPA_005fEVENT_005fEARLEY_005fITEM_005fTHRESHOLD"></a><dl>
<dt><a name="index-MARPA_005fEVENT_005fEARLEY_005fITEM_005fTHRESHOLD"></a>Macro: <em>int</em> <strong>MARPA_EVENT_EARLEY_ITEM_THRESHOLD</strong></dt>
<dd><p>This event
indicates that an application-settable threshold
on the number of Earley items has been reached or exceeded.
See <a href="#marpa_005fr_005fearley_005fitem_005fwarning_005fthreshold_005fset">marpa_r_earley_item_warning_threshold_set()</a>.
</p>
<p>Event value: The current Earley item count.
Suggested message: "Too many Earley items".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fEXHAUSTED"></a>Macro: <em>int</em> <strong>MARPA_EVENT_EXHAUSTED</strong></dt>
<dd><p>The parse is exhausted.
Event value: Undefined.
Suggested message: "Recognizer is exhausted".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fLOOP_005fRULES"></a>Macro: <em>int</em> <strong>MARPA_EVENT_LOOP_RULES</strong></dt>
<dd><p>One or more rules are loop rules — rules
that are part of a cycle.
Cycles are pathological cases of recursion,
in which the same symbol string derives itself
a potentially infinite number of times.
Nonetheless, Marpa parses in the presence of these,
and it is up to the application to treat these
as fatal errors,
something they almost always will wish to do.
Event value: The count of loop rules.
Suggested message: "Grammar contains a infinite loop".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fNULLING_005fTERMINAL"></a>Macro: <em>int</em> <strong>MARPA_EVENT_NULLING_TERMINAL</strong></dt>
<dd><p>A nulling symbol is also a terminal.
Event value: The ID of the symbol.
Suggested message: "This symbol is a nulling terminal".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fSYMBOL_005fCOMPLETED"></a>Macro: <em>int</em> <strong>MARPA_EVENT_SYMBOL_COMPLETED</strong></dt>
<dd><p>The recognizer can be set to generate an event
a symbol is completed
using its
<code>marpa_g_symbol_is_completion_event_set()</code>
method.
(A symbol is "completed" if and only if any rule with that symbol
as its LHS is completed.)
This event code indicates that one of those events
occurred.
Event value: The ID of the completed symbol.
Suggested message: "Completed symbol".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fSYMBOL_005fEXPECTED"></a>Macro: <em>int</em> <strong>MARPA_EVENT_SYMBOL_EXPECTED</strong></dt>
<dd><p>The recognizer can be set to generate an event when a
symbol is expected as a terminal,
using its
<code>marpa_r_expected_symbol_event_set()</code>
method.
Note that this event only triggers if the symbol is
expected as a terminal.
Predicted symbols which are not expected as terminals
do not trigger this event.
This event code indicates that one of those events
occurred.
Event value: The ID of the expected symbol.
Suggested message: "Expecting symbol".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fSYMBOL_005fNULLED"></a>Macro: <em>int</em> <strong>MARPA_EVENT_SYMBOL_NULLED</strong></dt>
<dd><p>The recognizer can be set to generate an event when a
symbol is nulled – that is, recognized as a
zero-length symbol.
To set an nulled symbol event,
use the recognizer’s
<code>marpa_r_nulled_symbol_event_set()</code>
method.
This event code indicates that a nulled symbol event
occurred.
Event value: The ID of the nulled symbol.
Suggested message: "Symbol was nulled".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fEVENT_005fSYMBOL_005fPREDICTED"></a>Macro: <em>int</em> <strong>MARPA_EVENT_SYMBOL_PREDICTED</strong></dt>
<dd><p>The recognizer can be set to generate an event when a
symbol is predicted.
To set an predicted symbol event,
use the recognizer’s
<code>marpa_g_symbol_is_prediction_event_set()</code>
method.
Unlike the
<code>MARPA_EVENT_SYMBOL_EXPECTED</code> event,
the <code>MARPA_EVENT_SYMBOL_PREDICTED</code> event
triggers for predictions of both
non-terminals and terminals.
This event code indicates that a predicted symbol event
occurred.
Event value: The ID of the predicted symbol.
Suggested message: "Symbol was predicted".
</p></dd></dl>
<hr>
<a name="Error-methods-macros-and-codes"></a>
<div class="header">
<p>
Next: <a href="#Technical-notes" accesskey="n" rel="next">Technical notes</a>, Previous: <a href="#Events" accesskey="p" rel="prev">Events</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error-methods_002c-macros-and-codes"></a>
<h2 class="chapter">21 Error methods, macros and codes</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Error-methods" accesskey="1">Error methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Error-Macros" accesskey="2">Error Macros</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#External-error-codes" accesskey="3">External error codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Internal-error-codes" accesskey="4">Internal error codes</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Error-methods"></a>
<div class="header">
<p>
Next: <a href="#Error-Macros" accesskey="n" rel="next">Error Macros</a>, Previous: <a href="#Error-methods-macros-and-codes" accesskey="p" rel="prev">Error methods macros and codes</a>, Up: <a href="#Error-methods-macros-and-codes" accesskey="u" rel="up">Error methods macros and codes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error-methods-1"></a>
<h3 class="section">21.1 Error methods</h3>
<a name="marpa_005fg_005ferror"></a><dl>
<dt><a name="index-marpa_005fg_005ferror"></a>Function: <em>Marpa_Error_Code</em> <strong>marpa_g_error</strong> <em>( Marpa_Grammar <var>g</var>, const char** <var>p_error_string</var>)</em></dt>
<dd><p>When a method fails,
this method allows the application to read
the error code.
<var>p_error_string</var> is reserved for use by
the internals.
Applications should set it to <code>NULL</code>.
</p>
<p>Return value: The last error code from a Libmarpa method.
Always succeeds.
</p></dd></dl>
<a name="marpa_005fg_005ferror_005fclear"></a><dl>
<dt><a name="index-marpa_005fg_005ferror_005fclear"></a>Function: <em>Marpa_Error_Code</em> <strong>marpa_g_error_clear</strong> <em>( Marpa_Grammar <var>g</var> )</em></dt>
<dd>
<p>Sets the error code
to <code>MARPA_ERR_NONE</code>.
Not often used,
but now and then it can be useful
to force the error code to a known state.
</p>
<p>Return value: <code>MARPA_ERR_NONE</code>.
Always succeeds.
</p></dd></dl>
<hr>
<a name="Error-Macros"></a>
<div class="header">
<p>
Next: <a href="#External-error-codes" accesskey="n" rel="next">External error codes</a>, Previous: <a href="#Error-methods" accesskey="p" rel="prev">Error methods</a>, Up: <a href="#Error-methods-macros-and-codes" accesskey="u" rel="up">Error methods macros and codes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Error-Macros-1"></a>
<h3 class="section">21.2 Error Macros</h3>
<dl>
<dt><a name="index-MARPA_005fERRCODE_005fCOUNT"></a>Macro: <em>int</em> <strong>MARPA_ERRCODE_COUNT</strong></dt>
<dd><p>The number of error codes.
All error codes, whether internal or external,
will be integers, non-negative but
strictly less than <code>MARPA_ERRCODE_COUNT</code>.
</p></dd></dl>
<hr>
<a name="External-error-codes"></a>
<div class="header">
<p>
Next: <a href="#Internal-error-codes" accesskey="n" rel="next">Internal error codes</a>, Previous: <a href="#Error-Macros" accesskey="p" rel="prev">Error Macros</a>, Up: <a href="#Error-methods-macros-and-codes" accesskey="u" rel="up">Error methods macros and codes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="External-error-codes-1"></a>
<h3 class="section">21.3 External error codes</h3>
<p>This section lists the external error codes.
These are the only error codes that users
of the Libmarpa external interface should ever see.
Internal error codes are in their own section
(<a href="#Internal-error-codes">Internal error codes</a>).
</p>
<dl>
<dt><a name="index-MARPA_005fERR_005fNONE"></a>Macro: <em>int</em> <strong>MARPA_ERR_NONE</strong></dt>
<dd><p>No error condition.
The error code is initialized to this value.
Methods which do not result in failure
sometimes reset the error code to <code>MARPA_ERR_NONE</code>.
Numeric value: 0.
Suggested message: "No error".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fBAD_005fSEPARATOR"></a>Macro: <em>int</em> <strong>MARPA_ERR_BAD_SEPARATOR</strong></dt>
<dd><p>A separator was specified for a sequence rule,
but its ID was not that
of a valid symbol.
Numeric value: 6.
Suggested message: "Separator has invalid symbol ID".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fBEFORE_005fFIRST_005fTREE"></a>Macro: <em>int</em> <strong>MARPA_ERR_BEFORE_FIRST_TREE</strong></dt>
<dd><p>A tree iterator is positioned before the first tree,
and it was specified in a context where that is not
allowed.
A newly created tree is positioned before the first
tree.
To position a newly created tree iterator to the first tree
use the
<code>marpa_t_next()</code>
method.
Numeric value: 91.
Suggested message: "Tree iterator is before first tree".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fCOUNTED_005fNULLABLE"></a>Macro: <em>int</em> <strong>MARPA_ERR_COUNTED_NULLABLE</strong></dt>
<dd><p>A “counted” symbol was found
that is also a nullable symbol.
A “counted” symbol is one that appears on the RHS
of a sequence rule.
If a symbol is nullable,
counting its occurrences becomes difficult.
Questions of definition and
problems of implementation arise.
At a minimum, a sequence with counted nullables
would be wildly
ambigious.
</p>
<p>Sequence rules are simply an optimized shorthand
for rules that can also be written in ordinary BNF.
If the equivalent of a sequence of nullables is
really what your application needs,
nothing in Libmarpa prevents you from specifying
that sequence
with ordinary BNF rules.
</p>
<p>Numeric value: 8.
Suggested message: "Nullable symbol on RHS of a sequence rule".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fDUPLICATE_005fRULE"></a>Macro: <em>int</em> <strong>MARPA_ERR_DUPLICATE_RULE</strong></dt>
<dd><p>This error indicates an attempt to add a BNF rule which
is a duplicate of a BNF rule already in the grammar.
Two BNF rules are considered duplicates if
</p>
<ul>
<li> Both rules have the same left hand symbol, and
</li><li> Both rules have the same right hand symbols in the same order.
</li></ul>
<p>Duplication of sequence rules,
and duplication between BNF rules and sequence rules,
is dealt with by requiring that the LHS of a sequence rule
not be the LHS of any other rule.
</p>
<p>Numeric value: 11.
Suggested message: "Duplicate rule".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fDUPLICATE_005fTOKEN"></a>Macro: <em>int</em> <strong>MARPA_ERR_DUPLICATE_TOKEN</strong></dt>
<dd><p>This error indicates an attempt to add a duplicate token.
A token is a duplicate if one already read at the same
earleme has the same symbol ID and the same length.
Numeric value: 12.
Suggested message: "Duplicate token".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fYIM_005fCOUNT"></a>Macro: <em>int</em> <strong>MARPA_ERR_YIM_COUNT</strong></dt>
<dd><p>This error code indicates that
an implementation-defined limit on the
number of Earley items per Earley set
was exceedeed.
This limit is different from
the Earley item warning threshold,
an optional limit on the number
of Earley items in an Earley set,
which can be set by the application.
</p>
<p>The implementation defined-limit is very large,
at least 500,000,000 earlemes.
An application is unlikely ever to see this
error.
Libmarpa’s use of memory
would almost certainly exceed the implementation’s
limits before it occurred.
Numeric value: 13.
Suggested message: "Maximum number of Earley items exceeded".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fEVENT_005fIX_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_EVENT_IX_NEGATIVE</strong></dt>
<dd><p>A negative event index was specified.
That is not allowed.
Numeric value: 15.
Suggested message: "Negative event index".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fEVENT_005fIX_005fOOB"></a>Macro: <em>int</em> <strong>MARPA_ERR_EVENT_IX_OOB</strong></dt>
<dd><p>An non-negative event index was specified,
but there is no event at that index.
Since the events are in sequence, this means it
was too large.
Numeric value: 16.
Suggested message: "No event at that index".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fGRAMMAR_005fHAS_005fCYCLE"></a>Macro: <em>int</em> <strong>MARPA_ERR_GRAMMAR_HAS_CYCLE</strong></dt>
<dd><p>The grammar has a cycle — one or more loop
rules.
This is a recoverable error,
although most applications will want to treat
it as fatal.
For more see the description of <a href="#marpa_005fg_005fprecompute">marpa_g_precompute</a>.
Numeric value: 17.
Suggested message: "Grammar has cycle".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fHEADERS_005fDO_005fNOT_005fMATCH"></a>Macro: <em>int</em> <strong>MARPA_ERR_HEADERS_DO_NOT_MATCH</strong></dt>
<dd><p>This is an internal error, and indicates that
Libmarpa was wrongly built.
Libmarpa was compiled with headers which do not
match the rest of the code.
The solution is to find a correctly built
Libmarpa.
Numeric value: 98.
Suggested message: "Internal error: Libmarpa was built incorrectly"
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fI_005fAM_005fNOT_005fOK"></a>Macro: <em>int</em> <strong>MARPA_ERR_I_AM_NOT_OK</strong></dt>
<dd><p>The Libmarpa base grammar is in a "not ok"
state.
Currently, the only way this can happen
is if Libmarpa memory is being overwritten.
Numeric value: 29.
Suggested message: "Marpa is in a not OK state".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINACCESSIBLE_005fTOKEN"></a>Macro: <em>int</em> <strong>MARPA_ERR_INACCESSIBLE_TOKEN</strong></dt>
<dd><p>This error code indicates that
the token symbol is an inaccessible symbol — one which
cannot be reached from the start symbol.
</p>
<p>Since the inaccessibility of a symbol is a property of the grammar,
this error code typically indicates an application error.
Nevertheless, a retry at this location, using another token ID,
may succeed.
At this writing,
the author knows of no uses of this technique.
</p>
<p>Numeric value: 18.
Suggested message: "Token symbol is inaccessible".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fBOOLEAN"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_BOOLEAN</strong></dt>
<dd><p>A function was called that takes a boolean argument,
but the value of that argument was not either 0 or 1.
Numeric value: 22.
Suggested message: "Argument is not boolean".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fLOCATION"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_LOCATION</strong></dt>
<dd><p>The location (Earley set ID) is not valid.
It may be invalid for one of two reasons:
</p><ul>
<li> It is negative,
and it is being used as the argument to a method
for which that negative value does not have a special meaning.
</li><li> It is after the latest Earley set.
</li></ul>
<p>For users of input models other than the standard one,
the term “location”, as used in association
with this error code,
means Earley set ID or Earley set ordinal.
In the standard input model, this will always
be identical with Libmarpa’s other idea of
location, the earleme.
</p>
<p>Numeric value: 25.
Suggested message: "Location is not valid".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fSTART_005fSYMBOL"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_START_SYMBOL</strong></dt>
<dd><p>A start symbol was specified,
but its symbol ID is not that of a valid symbol.
Numeric value: 27.
Suggested message: "Specified start symbol is not valid".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fASSERTION_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_ASSERTION_ID</strong></dt>
<dd><p>A method was called with an invalid assertion ID.
This is a assertion ID which not only does
not exist, but cannot exist.
Currently that means its value is less than zero.
Numeric value: 96.
Suggested message: "Assertion ID is malformed".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fRULE_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_RULE_ID</strong></dt>
<dd><p>A method was called with an invalid rule ID.
This is a rule ID which not only does
not exist, but cannot exist.
Currently that means its value is less than zero.
Numeric value: 26.
Suggested message: "Rule ID is malformed".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fSYMBOL_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_SYMBOL_ID</strong></dt>
<dd><p>A method was called with an invalid symbol ID.
This is a symbol ID which not only does
not exist, but cannot exist.
Currently that means its value is less than zero.
Numeric value: 28.
Suggested message: "Symbol ID is malformed".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fMAJOR_005fVERSION_005fMISMATCH"></a>Macro: <em>int</em> <strong>MARPA_ERR_MAJOR_VERSION_MISMATCH</strong></dt>
<dd><p>There was a mismatch in the major version number
between the requested version
of libmarpa, and the actual one.
Numeric value: 30.
Suggested message: "Libmarpa major version number is a mismatch".
</p>
</dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fMICRO_005fVERSION_005fMISMATCH"></a>Macro: <em>int</em> <strong>MARPA_ERR_MICRO_VERSION_MISMATCH</strong></dt>
<dd><p>There was a mismatch in the micro version number
between the requested version
of libmarpa, and the actual one.
Numeric value: 31.
Suggested message: "Libmarpa micro version number is a mismatch".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fMINOR_005fVERSION_005fMISMATCH"></a>Macro: <em>int</em> <strong>MARPA_ERR_MINOR_VERSION_MISMATCH</strong></dt>
<dd><p>There was a mismatch in the minor version number
between the requested version
of libmarpa, and the actual one.
Numeric value: 32.
Suggested message: "Libmarpa minor version number is a mismatch".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fEARLEY_005fSET_005fAT_005fLOCATION"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_EARLEY_SET_AT_LOCATION</strong></dt>
<dd><p>A non-negative Earley set ID (also called an Earley set ordinal)
was specified,
but there is no corresponding Earley set.
Since the Earley set ordinals are in sequence,
this means that the specified ID is greater
than that of the latest Earley set.
Numeric value: 39.
Suggested message: "Earley set ID is after latest Earley set".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNOT_005fPRECOMPUTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_NOT_PRECOMPUTED</strong></dt>
<dd><p>The grammar is not precomputed,
and attempt was made to do something with it
that is not allowed for unprecomputed
grammars.
For example, a recognizer cannot be
created from a grammar until it is precomputed.
Numeric value: 34.
Suggested message: "This grammar is not precomputed".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fPARSE"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_PARSE</strong></dt>
<dd><p>The application attempted to create a bocage
from a recognizer without a parse.
Applications will often want to treat this as
a soft error.
Numeric value: 41.
Suggested message: "No parse".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fRULES"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_RULES</strong></dt>
<dd><p>A grammar which has no rules is being used
in a way that is not allowed.
Usually the problem is that the user is
trying to precompute the grammar.
Numeric value: 42.
Suggested message: "This grammar does not have any rules".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fSTART_005fSYMBOL"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_START_SYMBOL</strong></dt>
<dd><p>The grammar has no start symbol,
and an attempt was made to perform an
operation which requires one.
Usually the problem is that the user is
trying to precompute the grammar.
Numeric value: 43.
Suggested message: "This grammar has no start symbol".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fSUCH_005fASSERTION_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_SUCH_ASSERTION_ID</strong></dt>
<dd><p>A method was called with an assertion ID which is well-formed,
but the assertion does not exist.
Numeric value: 97.
Suggested message: "No assertion with this ID exists".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fSUCH_005fRULE_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_SUCH_RULE_ID</strong></dt>
<dd><p>A method was called with a rule ID which is well-formed,
but the rule does not exist.
Numeric value: 89.
Suggested message: "No rule with this ID exists".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fSUCH_005fSYMBOL_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_SUCH_SYMBOL_ID</strong></dt>
<dd><p>A method was called with a symbol ID which is well-formed,
but the symbol does not exist.
Numeric value: 90.
Suggested message: "No symbol with this ID exists".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fTOKEN_005fEXPECTED_005fHERE"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_TOKEN_EXPECTED_HERE</strong></dt>
<dd><p>This error code indicates that
no tokens at all were expected at this earleme
location.
This can only happen in alternative input models.
</p>
<p>Typically, this indicates an application programming
error.
Retrying input at this location will always fail.
But if the application is able to leave this
earleme empty, a retry at a later location,
using this or another token,
may succeed.
At this writing,
the author knows of no uses of this technique.
</p>
<p>Numeric value: 44.
Suggested message: "No token is expected at this earleme location".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNOT_005fA_005fSEQUENCE"></a>Macro: <em>int</em> <strong>MARPA_ERR_NOT_A_SEQUENCE</strong></dt>
<dd><p>This error occurs in situations where a rule
is required to be a sequence,
and indicates that the rule of interest is,
in fact,
not a sequence.
</p>
<p>Numeric value: 99.
Suggested message: "Rule is not a sequence".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNULLING_005fTERMINAL"></a>Macro: <em>int</em> <strong>MARPA_ERR_NULLING_TERMINAL</strong></dt>
<dd><p>Marpa does not allow a symbol to be both nulling
and a terminal.
Numeric value: 49.
Suggested message: "A symbol is both terminal and nulling".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fORDER_005fFROZEN"></a>Macro: <em>int</em> <strong>MARPA_ERR_ORDER_FROZEN</strong></dt>
<dd><p>The Marpa order object has been frozen.
If a Marpa order object is frozen, it cannot be
changed.
</p>
<p>Multiple tree iterators can share a Marpa order object,
but that order object is frozen after the first tree
iterator is created from it.
Applications can order an bocage in many ways,
but they must do so by creating multiple order objects.
</p>
<p>Numeric value: 50.
Suggested message: "The ordering is frozen".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPARSE_005fEXHAUSTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_PARSE_EXHAUSTED</strong></dt>
<dd><p>The parse is exhausted.
Numeric value: 53.
Suggested message: "The parse is exhausted".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPARSE_005fTOO_005fLONG"></a>Macro: <em>int</em> <strong>MARPA_ERR_PARSE_TOO_LONG</strong></dt>
<dd><p>The parse is too long.
The limit on the length of a parse is implementation
dependent, but it is very large,
at least 500,000,000 earlemes.
</p>
<p>This error code is unlikely in the standard input model.
Almost certainly memory would be exceeded
before it could occur.
If an application sees this error,
it almost certainly using one of the non-standard
input models.
</p>
<p>Most often this message will occur because
of a request to add a single extremely long token,
perhaps as a result of an application error.
But it is also possible this error condition will
occur after the input of a large number
of long tokens.
</p>
<p>Numeric value: 54.
Suggested message: "This input would make the parse too long".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPOINTER_005fARG_005fNULL"></a>Macro: <em>int</em> <strong>MARPA_ERR_POINTER_ARG_NULL</strong></dt>
<dd><p>In a method which takes pointers as arguments,
one of the pointer arguments is <code>NULL</code>,
in a case where that is not allowed.
One such method is <code>marpa_r_progress_item()</code>.
Numeric value: 56.
Suggested message: "An argument is null when it should not be".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPRECOMPUTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_PRECOMPUTED</strong></dt>
<dd><p>An attempt was made to use a precomputed grammar
in a way that is not allowed.
Often this is an attempt to change the grammar.
Nearly every change to a grammar after
precomputation invalidates the precomputation,
and is therefore not allowed.
Numeric value: 57.
Suggested message: "This grammar is precomputed".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPROGRESS_005fREPORT_005fNOT_005fSTARTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_PROGRESS_REPORT_NOT_STARTED</strong></dt>
<dd><p>No recognizer progress report is currently active,
and an action has been attempted which
is inconsistent with that.
One such action would be a
<code>marpa_r_progress_item()</code>
call.
Numeric value: 59.
Suggested message: "No progress report has been started".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPROGRESS_005fREPORT_005fEXHAUSTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_PROGRESS_REPORT_EXHAUSTED</strong></dt>
<dd><p>The progress report is “exhausted” — all its
items have been iterated through.
Numeric value: 58.
Suggested message: "The progress report is exhausted".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRANK_005fTOO_005fLOW"></a>Macro: <em>int</em> <strong>MARPA_ERR_RANK_TOO_LOW</strong></dt>
<dd><p>A symbol or rule rank was specified which
was less than an implementation-defined minimum.
Implementations will always allow at least those
ranks in the range between
-134,217,727 and 134,217,727.
Numeric value: 85.
Suggested message: "Rule or symbol rank too low".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRANK_005fTOO_005fHIGH"></a>Macro: <em>int</em> <strong>MARPA_ERR_RANK_TOO_HIGH</strong></dt>
<dd><p>A symbol or rule rank was specified which
was greater than an implementation-defined maximum.
Implementations will always allow at least those
ranks in the range between
-134,217,727 and 134,217,727.
Numeric value: 86.
Suggested message: "Rule or symbol rank too high".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRECCE_005fIS_005fINCONSISTENT"></a>Macro: <em>int</em> <strong>MARPA_ERR_RECCE_IS_INCONSISTENT</strong></dt>
<dd><p>The recognizer is “inconsistent”,
usually because the user has rejected one or
more rules or terminals,
and has not yet called
the
<code>marpa_r_consistent()</code>
method.
Numeric value: 95.
Suggested message: "The recognizer is inconsistent.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRECCE_005fNOT_005fACCEPTING_005fINPUT"></a>Macro: <em>int</em> <strong>MARPA_ERR_RECCE_NOT_ACCEPTING_INPUT</strong></dt>
<dd><p>The recognizer is not accepting input,
and the application has attempted something that
is inconsistent with that fact.
Numeric value: 60.
Suggested message: "The recognizer is not accepting input".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRECCE_005fNOT_005fSTARTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_RECCE_NOT_STARTED</strong></dt>
<dd><p>The recognizer has not been started.
and the application has attempted something that
is inconsistent with that fact.
Numeric value: 61.
Suggested message: "The recognizer has not been started".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRECCE_005fSTARTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_RECCE_STARTED</strong></dt>
<dd><p>The recognizer has been started.
and the application has attempted something that
is inconsistent with that fact.
Numeric value: 62.
Suggested message: "The recognizer has been started".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRHS_005fIX_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_RHS_IX_NEGATIVE</strong></dt>
<dd><p>The index of a RHS symbol was specified,
and it was negative.
That is not allowed.
Numeric value: 63.
Suggested message: "RHS index cannot be negative".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRHS_005fIX_005fOOB"></a>Macro: <em>int</em> <strong>MARPA_ERR_RHS_IX_OOB</strong></dt>
<dd><p>A non-negative index of RHS symbol was specified,
but there is no symbol at that index.
Since the indexes are in sequence, this means the
index was greater than or equal to the rule length.
Numeric value: 64.
Suggested message: "RHS index must be less than rule length".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fRHS_005fTOO_005fLONG"></a>Macro: <em>int</em> <strong>MARPA_ERR_RHS_TOO_LONG</strong></dt>
<dd><p>An attempt was made to add a rule with too many
right hand side symbols.
The limit on the RHS symbol count is implementation
dependent, but it is very large,
at least 500,000,000 symbols.
This is
far beyond what is required in any current practical grammar.
An application with rules of this length is almost
certain to run into memory and other limits.
Numeric value: 65.
Suggested message: "The RHS is too long".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSEQUENCE_005fLHS_005fNOT_005fUNIQUE"></a>Macro: <em>int</em> <strong>MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE</strong></dt>
<dd><p>The LHS of a
sequence rule cannot be the LHS of any other rule,
whether a sequence rule or a BNF rule.
An attempt was made to violate this restriction.
Numeric value: 66.
Suggested message: "LHS of sequence rule would not be unique".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSTART_005fNOT_005fLHS"></a>Macro: <em>int</em> <strong>MARPA_ERR_START_NOT_LHS</strong></dt>
<dd><p>The start symbol is not on the LHS on
any rule.
That means it could never match any possible input,
not even the null string.
Presumably, an error in writing the grammar.
Numeric value: 73.
Suggested message: "Start symbol not on LHS of any rule".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSYMBOL_005fIS_005fNOT_005fCOMPLETION_005fEVENT"></a>Macro: <em>int</em> <strong>MARPA_ERR_SYMBOL_IS_NOT_COMPLETION_EVENT</strong></dt>
<dd><p>An attempt was made to use a symbol in
a way that requires it to be
set up for completion events,
but the symbol was not set
set up for completion events.
The archetypal case is an attempt to activate completion
events for the symbol in the recognizer.
The archetypal case is an attempt to activate a completion
event in the recognizer for
a symbol that is not set up as a completion event.
Numeric value: 92.
Suggested message: "Symbol is not set up for completion events".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSYMBOL_005fIS_005fNOT_005fNULLED_005fEVENT"></a>Macro: <em>int</em> <strong>MARPA_ERR_SYMBOL_IS_NOT_NULLED_EVENT</strong></dt>
<dd><p>An attempt was made to use a symbol in
a way that requires it to be
set up for nulled events,
but the symbol was not set
set up for nulled events.
The archetypal case is an attempt to activate a nulled
events in the recognizer for
a symbol that is not set up as a nulled event.
Numeric value: 93.
Suggested message: "Symbol is not set up for nulled events".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSYMBOL_005fIS_005fNOT_005fPREDICTION_005fEVENT"></a>Macro: <em>int</em> <strong>MARPA_ERR_SYMBOL_IS_NOT_PREDICTION_EVENT</strong></dt>
<dd><p>An attempt was made to use a symbol in
a way that requires it to be
set up for predictino events,
but the symbol was not set
set up for predictino events.
The archetypal case is an attempt to activate a prediction
event in the recognizer for
a symbol that is not set up as a prediction event.
Numeric value: 94.
Suggested message: "Symbol is not set up for prediction events".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSYMBOL_005fVALUED_005fCONFLICT"></a>Macro: <em>int</em> <strong>MARPA_ERR_SYMBOL_VALUED_CONFLICT</strong></dt>
<dd><p>Unvalued symbols are a deprecated Marpa feature,
which may be avoided with
the
<code>marpa_g_force_valued()</code>
method.
An unvalued symbol may take on any value,
and therefore a symbol which is unvalued at some points
cannot safely to be used to contain a value at
others.
This error indicates that such an unsafe use is
being attempted.
Numeric value: 74.
Suggested message: "Symbol is treated both as valued and unvalued".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fTERMINAL_005fIS_005fLOCKED"></a>Macro: <em>int</em> <strong>MARPA_ERR_TERMINAL_IS_LOCKED</strong></dt>
<dd><p>An attempt was made to change the terminal status
of a symbol to a different value
after it was locked.
Numeric value: 75.
Suggested message: "The terminal status of the symbol is locked".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fTOKEN_005fIS_005fNOT_005fTERMINAL"></a>Macro: <em>int</em> <strong>MARPA_ERR_TOKEN_IS_NOT_TERMINAL</strong></dt>
<dd><p>A token was specified whose symbol ID is not
a terminal.
Numeric value: 76.
Suggested message: "Token symbol must be a terminal".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fTOKEN_005fLENGTH_005fLE_005fZERO"></a>Macro: <em>int</em> <strong>MARPA_ERR_TOKEN_LENGTH_LE_ZERO</strong></dt>
<dd><p>A token length was specified which is less than
or equal to zero.
Zero-length tokens are not allowed in Libmarpa.
Numeric value: 77.
Suggested message: "Token length must greater than zero".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fTOKEN_005fTOO_005fLONG"></a>Macro: <em>int</em> <strong>MARPA_ERR_TOKEN_TOO_LONG</strong></dt>
<dd><p>The token length is too long.
The limit on the length of a token
is implementation dependent, but it
is at least 500,000,000 earlemes.
An application using a token that long
is almost certain to run into some other
limit.
Numeric value: 78.
Suggested message: "Token is too long".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fTREE_005fEXHAUSTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_TREE_EXHAUSTED</strong></dt>
<dd><p>A Libmarpa parse tree iterator
is “exhausted”, that is,
it has no more parses.
Numeric value: 79.
Suggested message: "Tree iterator is exhausted".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fTREE_005fPAUSED"></a>Macro: <em>int</em> <strong>MARPA_ERR_TREE_PAUSED</strong></dt>
<dd><p>A Libmarpa tree is “paused”
and an operation was attempted which
is inconsistent with that fact.
Typically, this operation will be
a call of the
<code>marpa_t_next()</code>
method.
Numeric value: 80.
Suggested message: "Tree iterator is paused".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fUNEXPECTED_005fTOKEN_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_UNEXPECTED_TOKEN_ID</strong></dt>
<dd><p>An attempt was made to read a token
where a token with that symbol ID is not
expected.
This message can also occur when an
attempt is made to read a token
at a location where no token is expected.
Numeric value: 81.
Suggested message: "Unexpected token".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fUNPRODUCTIVE_005fSTART"></a>Macro: <em>int</em> <strong>MARPA_ERR_UNPRODUCTIVE_START</strong></dt>
<dd><p>The start symbol is unproductive.
That means it could never match any possible input,
not even the null string.
Presumably, an error in writing the grammar.
Numeric value: 82.
Suggested message: "Unproductive start symbol".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fVALUATOR_005fINACTIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_VALUATOR_INACTIVE</strong></dt>
<dd><p>The valuator is inactive in a context where that
should not be the case.
Numeric value: 83.
Suggested message: "Valuator inactive".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fVALUED_005fIS_005fLOCKED"></a>Macro: <em>int</em> <strong>MARPA_ERR_VALUED_IS_LOCKED</strong></dt>
<dd><p>Unvalued symbols are a deprecated Marpa feature,
which may be avoided with
the
<code>marpa_g_force_valued()</code>
method.
This error code
indicates that the valued status of a symbol is locked,
and an attempt was made
to change it to a status different from the
current one.
Numeric value: 84.
Suggested message: "The valued status of the symbol is locked".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSYMBOL_005fIS_005fNULLING"></a>Macro: <em>int</em> <strong>MARPA_ERR_SYMBOL_IS_NULLING</strong></dt>
<dd><p>An attempt was made to do something with a nulling
symbol that is not allowed.
For example,
the ID of a nulling symbol cannot be an argument
to
<code>marpa_r_expected_symbol_event_set()</code>
—
because it is not possible to create an “expected symbol” event
for a nulling symbol.
Numeric value: 87.
Suggested message: "Symbol is nulling".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSYMBOL_005fIS_005fUNUSED"></a>Macro: <em>int</em> <strong>MARPA_ERR_SYMBOL_IS_UNUSED</strong></dt>
<dd><p>An attempt was made to do something with an unused symbol that is not allowed.
An “unused” symbol is a inaccessible or unproductive symbol.
For example,
the ID of a unused symbol cannot be an argument
to
<code>marpa_r_expected_symbol_event_set()</code>
—
because it is not possible to create an “expected symbol” event
for an unused symbol.
Numeric value: 88.
Suggested message: "Symbol is not used".
</p></dd></dl>
<hr>
<a name="Internal-error-codes"></a>
<div class="header">
<p>
Previous: <a href="#External-error-codes" accesskey="p" rel="prev">External error codes</a>, Up: <a href="#Error-methods-macros-and-codes" accesskey="u" rel="up">Error methods macros and codes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Internal-error-codes-1"></a>
<h3 class="section">21.4 Internal error codes</h3>
<p>An internal error code may be one of two things:
First,
it can be an error code which
arises from an internal Libmarpa programming issue
(in other words, something happening in the code
that was not supposed to be able to happen.)
Second, it can be an error code which only occurs
when a method from Libmarpa’s internal interface
is used.
Both kinds of internal error message share one common
trait — users of the Libmarpa’s external interface
should never see them.
</p>
<p>Internal error messages
require someone with knowledge of the Libmarpa internals
to follow up on them.
They usually do not have descriptions or suggested messages.
</p>
<dl>
<dt><a name="index-MARPA_005fERR_005fAHFA_005fIX_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_AHFA_IX_NEGATIVE</strong></dt>
<dd><p>Numeric value: 1.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fAHFA_005fIX_005fOOB"></a>Macro: <em>int</em> <strong>MARPA_ERR_AHFA_IX_OOB</strong></dt>
<dd><p>Numeric value: 2.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fANDID_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_ANDID_NEGATIVE</strong></dt>
<dd><p>Numeric value: 3.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fANDID_005fNOT_005fIN_005fOR"></a>Macro: <em>int</em> <strong>MARPA_ERR_ANDID_NOT_IN_OR</strong></dt>
<dd><p>Numeric value: 4.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fANDIX_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_ANDIX_NEGATIVE</strong></dt>
<dd><p>Numeric value: 5.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fBOCAGE_005fITERATION_005fEXHAUSTED"></a>Macro: <em>int</em> <strong>MARPA_ERR_BOCAGE_ITERATION_EXHAUSTED</strong></dt>
<dd><p>Numeric value: 7.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fDEVELOPMENT"></a>Macro: <em>int</em> <strong>MARPA_ERR_DEVELOPMENT</strong></dt>
<dd><p>"Development" errors were used heavily during
Libmarpa’s development,
when it was not yet clear how precisely
to classify every error condition.
Unless they are using a developer’s version,
users of the external interface
should never
see development errors.
</p>
<p>Development errors have an error string
associated with them.
The error string is a
short 7-bit ASCII error string
which describes the error.
Numeric value: 9.
Suggested message: "Development error, see string".
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fDUPLICATE_005fAND_005fNODE"></a>Macro: <em>int</em> <strong>MARPA_ERR_DUPLICATE_AND_NODE</strong></dt>
<dd><p>Numeric value: 10.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fYIM_005fID_005fINVALID"></a>Macro: <em>int</em> <strong>MARPA_ERR_YIM_ID_INVALID</strong></dt>
<dd><p>Numeric value: 14.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINTERNAL"></a>Macro: <em>int</em> <strong>MARPA_ERR_INTERNAL</strong></dt>
<dd><p>A “catchall” internal error.
Numeric value: 19.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fAHFA_005fID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_AHFA_ID</strong></dt>
<dd><p>The AHFA ID was invalid. There are no AHFAs
any more, so this message should not occur.
Numeric value: 20.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fAIMID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_AIMID</strong></dt>
<dd><p>The AHM ID was invalid. The term “AIMID”
is a legacy of earlier implementations and must
be kept for backward compatibility.
Numeric value: 21.
</p>
</dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fIRLID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_IRLID</strong></dt>
<dd><p>Numeric value: 23.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fINVALID_005fNSYID"></a>Macro: <em>int</em> <strong>MARPA_ERR_INVALID_NSYID</strong></dt>
<dd><p>Numeric value: 24.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNOOKID_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_NOOKID_NEGATIVE</strong></dt>
<dd><p>Numeric value: 33.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNOT_005fTRACING_005fCOMPLETION_005fLINKS"></a>Macro: <em>int</em> <strong>MARPA_ERR_NOT_TRACING_COMPLETION_LINKS</strong></dt>
<dd><p>Numeric value: 35.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNOT_005fTRACING_005fLEO_005fLINKS"></a>Macro: <em>int</em> <strong>MARPA_ERR_NOT_TRACING_LEO_LINKS</strong></dt>
<dd><p>Numeric value: 36.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNOT_005fTRACING_005fTOKEN_005fLINKS"></a>Macro: <em>int</em> <strong>MARPA_ERR_NOT_TRACING_TOKEN_LINKS</strong></dt>
<dd><p>Numeric value: 37.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fAND_005fNODES"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_AND_NODES</strong></dt>
<dd><p>Numeric value: 38.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fOR_005fNODES"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_OR_NODES</strong></dt>
<dd><p>Numeric value: 40.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fTRACE_005fYS"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_TRACE_YS</strong></dt>
<dd><p>Numeric value: 46.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fTRACE_005fPIM"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_TRACE_PIM</strong></dt>
<dd><p>Numeric value: 47.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fTRACE_005fYIM"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_TRACE_YIM</strong></dt>
<dd><p>Numeric value: 45.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fNO_005fTRACE_005fSRCL"></a>Macro: <em>int</em> <strong>MARPA_ERR_NO_TRACE_SRCL</strong></dt>
<dd><p>Numeric value: 48.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fORID_005fNEGATIVE"></a>Macro: <em>int</em> <strong>MARPA_ERR_ORID_NEGATIVE</strong></dt>
<dd><p>Numeric value: 51.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fOR_005fALREADY_005fORDERED"></a>Macro: <em>int</em> <strong>MARPA_ERR_OR_ALREADY_ORDERED</strong></dt>
<dd><p>Numeric value: 52.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fPIM_005fIS_005fNOT_005fLIM"></a>Macro: <em>int</em> <strong>MARPA_ERR_PIM_IS_NOT_LIM</strong></dt>
<dd><p>Numeric value: 55.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSOURCE_005fTYPE_005fIS_005fNONE"></a>Macro: <em>int</em> <strong>MARPA_ERR_SOURCE_TYPE_IS_NONE</strong></dt>
<dd><p>Numeric value: 70.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSOURCE_005fTYPE_005fIS_005fTOKEN"></a>Macro: <em>int</em> <strong>MARPA_ERR_SOURCE_TYPE_IS_TOKEN</strong></dt>
<dd><p>Numeric value: 71.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSOURCE_005fTYPE_005fIS_005fCOMPLETION"></a>Macro: <em>int</em> <strong>MARPA_ERR_SOURCE_TYPE_IS_COMPLETION</strong></dt>
<dd><p>Numeric value: 68.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSOURCE_005fTYPE_005fIS_005fLEO"></a>Macro: <em>int</em> <strong>MARPA_ERR_SOURCE_TYPE_IS_LEO</strong></dt>
<dd><p>Numeric value: 69.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSOURCE_005fTYPE_005fIS_005fAMBIGUOUS"></a>Macro: <em>int</em> <strong>MARPA_ERR_SOURCE_TYPE_IS_AMBIGUOUS</strong></dt>
<dd><p>Numeric value: 67.
</p></dd></dl>
<dl>
<dt><a name="index-MARPA_005fERR_005fSOURCE_005fTYPE_005fIS_005fUNKNOWN"></a>Macro: <em>int</em> <strong>MARPA_ERR_SOURCE_TYPE_IS_UNKNOWN</strong></dt>
<dd><p>Numeric value: 72.
</p></dd></dl>
<hr>
<a name="Technical-notes"></a>
<div class="header">
<p>
Next: <a href="#Advanced-input-models" accesskey="n" rel="next">Advanced input models</a>, Previous: <a href="#Error-methods-macros-and-codes" accesskey="p" rel="prev">Error methods macros and codes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Technical-notes-1"></a>
<h2 class="chapter">22 Technical notes</h2>
<p>This section contains technical notes that are
not necessary for the main presentation,
but which may be useful or interesting.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Data-types-used-by-Libmarpa" accesskey="1">Data types used by Libmarpa</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Why-so-many-time-objects" accesskey="2">Why so many time objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Design-of-numbered-objects" accesskey="3">Design of numbered objects</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#LHS-Terminals" accesskey="4">LHS Terminals</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Data-types-used-by-Libmarpa"></a>
<div class="header">
<p>
Next: <a href="#Why-so-many-time-objects" accesskey="n" rel="next">Why so many time objects</a>, Previous: <a href="#Technical-notes" accesskey="p" rel="prev">Technical notes</a>, Up: <a href="#Technical-notes" accesskey="u" rel="up">Technical notes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Data-types-used-by-Libmarpa-1"></a>
<h3 class="section">22.1 Data types used by Libmarpa</h3>
<p>Libmarpa does not use any floating point data or strings.
All data are either integers or pointers.
</p>
<hr>
<a name="Why-so-many-time-objects"></a>
<div class="header">
<p>
Next: <a href="#Design-of-numbered-objects" accesskey="n" rel="next">Design of numbered objects</a>, Previous: <a href="#Data-types-used-by-Libmarpa" accesskey="p" rel="prev">Data types used by Libmarpa</a>, Up: <a href="#Technical-notes" accesskey="u" rel="up">Technical notes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Why-so-many-time-objects_003f"></a>
<h3 class="section">22.2 Why so many time objects?</h3>
<p>Marpa is an aggressively multi-pass algorithm.
Marpa achieves its efficiency,
not in spite of making multiple
passes over the data, but because of it.
Marpa regularly substitutes
two fast O(<var>n</var>) passes for a single
O(<var>n</var> log <var>n</var>) pass.
Marpa’s proliferation of time objects is in
keeping with its multi-pass approach.
</p>
<p>Bocage objects come at no cost,
even for unambiguous parses,
because the same pass which creates the bocage
also deals with other issues which are of major
significance for unambiguous parses.
It is the post-processing of the bocage pass
that enables Marpa to do both left-
and right-recursion in linear time.
</p>
<p>Of the various objects, the best
case for elimination is of the
ordering object.
In many cases, the ordering is trivial.
Either the parse is unambiguous, or the
application does not care about the order in
which parses are returned.
But while it would be easy to add an option
to bypass creation of an ordering object,
there is little to be gained from it.
When the ordering is trivial,
its overhead is very small —
essentially a handful of subroutine calls.
Many orderings accomplish nothing,
but these cost next to nothing.
</p>
<p>Tree objects come at minimal cost to unambiguous grammars,
because the same pass that allows iteration through multiple
parse trees does the tree traversal.
This eliminates much of the work that otherwise would
need to be done in
the valuation time object.
In the current implement, the valuation time object
needs only to step through a sequence already determined
in the tree iterator.
</p>
<hr>
<a name="Design-of-numbered-objects"></a>
<div class="header">
<p>
Next: <a href="#LHS-Terminals" accesskey="n" rel="next">LHS Terminals</a>, Previous: <a href="#Why-so-many-time-objects" accesskey="p" rel="prev">Why so many time objects</a>, Up: <a href="#Technical-notes" accesskey="u" rel="up">Technical notes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Numbered-objects-2"></a>
<h3 class="section">22.3 Numbered objects</h3>
<p>As the name suggests,
the choice was made to implement
numbered objects as integers,
and not as
pointers.
In standard-conformant C,
integers can be safely checked for validity,
while pointers cannot.
</p>
<p>There are efficiency tradeoffs between pointers and
integers but they are complicated,
and they go both ways.
Pointers can be faster, but integers can be used
as indexes into more than one data structure.
Which is actually faster depends on the design.
Integers allow for a more flexible design,
so that once the choice is settled on,
careful programming can make them a win,
possibly a very big one.
</p>
<p>The approach taken in Libmarpa was to settle,
from the outset,
on integers as the implementation for numbered
objects,
and to optimize on that basis.
The author concedes that it is
possible that
others redoing Libmarpa from scratch
might find that pointers are faster.
But the author is confident
that they will also discover,
on modern architectures,
that the lack of safe validity checking
is far too high a price to pay
for the difference in speed.
</p>
<hr>
<a name="LHS-Terminals"></a>
<div class="header">
<p>
Previous: <a href="#Design-of-numbered-objects" accesskey="p" rel="prev">Design of numbered objects</a>, Up: <a href="#Technical-notes" accesskey="u" rel="up">Technical notes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="LHS-terminals"></a>
<h3 class="section">22.4 LHS terminals</h3>
<p>Marpa’s idea
in losing the sharp division between terminals
and non-terminals is that the distinction,
while helpful for proving theorems,
is not essential in practice.
LHS symbols
in the input might be useful for
“short circuiting” the rules in which they occur.
This may
prove helpful in debugging, or have other applications.
</p>
<p>However,
it also can be useful,
for checking input validity as well as for efficiency,
to follow tradition and distinguish
non-terminals from terminals.
For this reason,
the traditional behavior is the default
in Libmarpa.
</p>
<hr>
<a name="Advanced-input-models"></a>
<div class="header">
<p>
Next: <a href="#Futures" accesskey="n" rel="next">Futures</a>, Previous: <a href="#Technical-notes" accesskey="p" rel="prev">Technical notes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Advanced-input-models-1"></a>
<h2 class="chapter">23 Advanced input models</h2>
<p>In an earlier chapter, we introduced Libmarpa’s concept of input,
and described its basic input models.
See <a href="#Input">Input</a>.
In this chapter we describe Libmarpa’s advanced models of input.
These advanced input models have attracted considerable interest.
However, they have seen little actual use so far,
and for that reason we delayed their consideration until now.
</p>
<p>A Libmarpa input model is
<a name="index-advanced-input-model"></a>
<a name="index-input-model_002c-advanced"></a>
<em>advanced</em>
if it allows tokens of length other than 1.
The advanced input models are also called
<a name="index-variable_002dlength-token-input-model"></a>
<a name="index-input-model_002c-variable_002dlength-token"></a>
<em>variable-length token models</em>
because they allow the token
length to vary from the “normal” length of 1.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#The-dense-variable_002dlength-token-model" accesskey="1">The dense variable-length token model</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#The-fully-general-input-model" accesskey="2">The fully general input model</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="The-dense-variable_002dlength-token-model"></a>
<div class="header">
<p>
Next: <a href="#The-fully-general-input-model" accesskey="n" rel="next">The fully general input model</a>, Previous: <a href="#Advanced-input-models" accesskey="p" rel="prev">Advanced input models</a>, Up: <a href="#Advanced-input-models" accesskey="u" rel="up">Advanced input models</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-dense-variable_002dlength-token-model-1"></a>
<h3 class="section">23.1 The dense variable-length token model</h3>
<p>In the
<a name="index-dense-variable_002dlength-input-model"></a>
<a name="index-variable_002dlength-input-model_002c-dense"></a>
<a name="index-input-model_002c-dense-variable_002dlength"></a>
<em>dense variable-length model of input</em>,
one or more successful
calls of
<code>marpa_r_alternative()</code>
must be immediately previous
to every call to
<code>marpa_r_earleme_complete()</code>.
Note that,
for a variable-length input model to be “dense”
according to this definition,
at least one successful call
of <code>marpa_r_alternative()</code>
must be immediately previous to each call to
<code>marpa_r_earleme_complete()</code>.
Recall that, in this document, we say that a <code>marpa_r_alternative()</code> call is
“immediately previous” to a
<code>marpa_r_earleme_complete()</code> call
iff
that <code>marpa_r_earleme_complete()</code> call is
the first
<code>marpa_r_earleme_complete()</code> call after
the <code>marpa_r_alternative()</code> call.
</p>
<p>In the dense model of input,
after a successful call of
<code>marpa_r_alternative()</code>,
the earleme variables are as follows:
</p><ul>
<li> The furthest earleme will be
<code>max(<var>old_f</var>, <var>old_c</var>+<var>length</var>)</code>,
<ul>
<li> where <var>old_f</var> is the furthest earleme
before the call to <code>marpa_r_alternative()</code>,
</li><li> <var>old_c</var> is the value of the current earleme
before the call to <code>marpa_r_alternative()</code>, and
</li><li> <var>length</var> is the length of the token read.
</li></ul>
</li><li> <code>marpa_r_alternative()</code> never changes the
latest or current earleme.
</li></ul>
<p>In the dense variable-length model of input,
the effect of the
<code>marpa_r_earleme_complete()</code>
mutator on the earleme variables
is the same as for the
basic models of input.
See <a href="#The-standard-model-of-input">The standard model of input</a>.
</p>
<p>In the dense model of input,
the latest earleme is always the same as
the current earleme.
In fact,
the latest earleme and the current earleme
are always the same,
except in the fully general model of input.
</p>
<hr>
<a name="The-fully-general-input-model"></a>
<div class="header">
<p>
Previous: <a href="#The-dense-variable_002dlength-token-model" accesskey="p" rel="prev">The dense variable-length token model</a>, Up: <a href="#Advanced-input-models" accesskey="u" rel="up">Advanced input models</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-fully-general-input-model-1"></a>
<h3 class="section">23.2 The fully general input model</h3>
<p>In the
<a name="index-sparse-variable_002dlength-input-model"></a>
<a name="index-variable_002dlength-input-model_002c-sparse"></a>
<a name="index-input-model_002c-sparse-variable_002dlength"></a>
<em>sparse variable-length model of input</em>,
zero or more successful
calls of
<code>marpa_r_alternative()</code>
must be immediately previous
to every call to
<code>marpa_r_earleme_complete()</code>.
The sparse model is the dense variable-length model,
with its only restriction lifted —
the sparse variable-length input model
allows calls to
<code>marpa_r_earleme_complete()</code>
that are not immediately preceded by calls to
<code>marpa_r_alternative()</code>.
</p>
<p>Since it is unrestricted, the sparse input model
is Libmarpa’s fully general input model.
Because of this,
it may be useful for us
specify the effect of mutators
on the earleme variables in detail,
even at the expense of some repetition.
</p>
<p>In the sparse input model,
<a name="index-empty-earleme"></a>
<a name="index-earleme_002c-empty"></a>
<em>empty earlemes</em>
are now possible.
An empty earleme is an earleme
with no tokens and no Earley set.
An empty earleme occurs iff
<code>marpa_r_earleme_complete()</code>
is called when there is no immediately previous
call to
<code>marpa_r_alternative()</code>.
The sparse model takes its name
from the fact that there may be earlemes with no
Earley set.
In the sparse model, Earley sets are “sparsely”
distributed among the earlemes.
</p>
<p>In the dense model of input,
the effect on the earleme variables of
a successful call of the
<code>marpa_r_alternative()</code> mutator
is the same as for the sparse model of input:
</p><ul>
<li> The furthest earleme will be
<code>max(<var>old_f</var>, <var>old_c</var>+<var>length</var>)</code>,
<ul>
<li> where <var>old_f</var> is the furthest earleme
before the call to <code>marpa_r_alternative()</code>,
</li><li> <var>old_c</var> is the value of the current earleme
before the call to <code>marpa_r_alternative()</code>, and
</li><li> <var>length</var> is the length of the token read.
</li></ul>
</li><li> <code>marpa_r_alternative()</code> never changes the
latest or current earleme.
</li></ul>
<p>In the sparse model,
when the earleme is not empty,
the effect of
a call to
<code>marpa_r_earleme_complete()</code>
on the earleme variables is the same as
in the dense and the basic models of input.
Specifically, the following will be true:
</p><ul>
<li> The current earleme will be advanced to <code><var>old_c</var>+1</code>,
where <var>old_c</var> is the current earleme before the call.
</li><li> The latest earleme will be <code><var>old_c</var>+1</code>, and therefore
will be equal to the current earleme.
</li><li> The value of the furthest earleme is never changed by
a call to
<code>marpa_r_earleme_complete()</code>.
</li></ul>
<p>Recall that, in the dense and basic input models,
as a matter of definition,
there are no empty earlemes.
For the sparse input model,
in the case of an empty earleme,
the effect of the
<code>marpa_r_earleme_complete()</code>
mutator on the earleme variables
is the following:
</p><ul>
<li> The current earleme will be advanced to <code><var>old_c</var>+1</code>,
where <var>old_c</var> is the current earleme before the call.
</li><li> The latest earleme will remain at <var>old_l</var>,
where the latest earleme before the call is <var>old_l</var>.
This implies that the latest earleme will be less than
the current earleme.
</li><li> The furthest earleme is never changed by a call
to
<code>marpa_r_earleme_complete()</code>.
</li></ul>
<p>After a call to <code>marpa_r_earleme_complete()</code>
for an empty earleme,
the lastest and current earlemes will have different values.
In a parse that never calls <code>marpa_r_earleme_complete()</code>
for an empty earleme,
the lastest and current earlemes will always be the same.
</p>
<hr>
<a name="Futures"></a>
<div class="header">
<p>
Next: <a href="#Deprecated-techniques-and-methods" accesskey="n" rel="next">Deprecated techniques and methods</a>, Previous: <a href="#Advanced-input-models" accesskey="p" rel="prev">Advanced input models</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Futures-1"></a>
<h2 class="chapter">24 Futures</h2>
<p>This chapter discusses features that are <strong>not</strong>
in the external interface,
but that might be added
to the external interface in the future.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Orthogonal-treatment-of-exhaustion" accesskey="1">Orthogonal treatment of exhaustion</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Furthest-earleme-values" accesskey="2">Furthest earleme values</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029" accesskey="3">Additional recoverable failures in marpa_r_alternative()</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Untested-methods" accesskey="4">Untested methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Orthogonal-treatment-of-exhaustion"></a>
<div class="header">
<p>
Next: <a href="#Furthest-earleme-values" accesskey="n" rel="next">Furthest earleme values</a>, Previous: <a href="#Futures" accesskey="p" rel="prev">Futures</a>, Up: <a href="#Futures" accesskey="u" rel="up">Futures</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Orthogonal-treatment-of-exhaustion-1"></a>
<h3 class="section">24.1 Orthogonal treatment of exhaustion</h3>
<p>The treatment of parse exhaustion is very awkward.
<code>marpa_r_start_input()</code> returns success on exhaustion,
while
<code>marpa_r_earleme_complete()</code> either returns success or
a hard failure, depending on circumstances.
See <a href="#marpa_005fr_005fearleme_005fcomplete">marpa_r_earleme_complete()</a> and
<a href="#marpa_005fr_005fstart_005finput">marpa_r_start_input()</a>.
</p>
<p>Ideally the treatment should be simpler, more intuitive
and more orthogonal.
Better, perhaps, would be to always treat parse exhaustion
as a soft failure.
</p>
<hr>
<a name="Furthest-earleme-values"></a>
<div class="header">
<p>
Next: <a href="#Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029" accesskey="n" rel="next">Additional recoverable failures in marpa_r_alternative()</a>, Previous: <a href="#Orthogonal-treatment-of-exhaustion" accesskey="p" rel="prev">Orthogonal treatment of exhaustion</a>, Up: <a href="#Futures" accesskey="u" rel="up">Futures</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Furthest-earleme-values-1"></a>
<h3 class="section">24.2 Furthest earleme values</h3>
<p><code>marpa_r_furthest_earleme</code> returns
<code>unsigned int</code> which is non-orthogonal with
<code>marpa_r_current_earleme</code>.
This leaves no room for an failure return value,
which we deal with by not checking for failures,
of which the only important one is calling
<code>marpa_r_furthest_earleme</code> before the start of input.
To consider
<code>marpa_r_furthest_earleme</code> we consider furthese earleme to have
been initialized when the recognizer was created,
which is another non-orthogonality with
<code>marpa_r_current_earleme</code>.
</p>
<p>All this might be fine, if something were gained, but in fact in the furthest
earleme, unless there is a problem, always becomes the current earleme,
and no use cases for extremely long variable-length tokens are envisioned,
so that the two should never be far apart.
Additionally, the additional values for the furthest earleme only come into
play if the parse is to large for the computer memories as of this writing.
Summarizing, <code>marpa_r_furthest_earleme</code>,
should return an <code>int</code>,
like <code>marpa_r_current_earleme</code>,
and the non-orthogonalities should be eliminated.
</p>
<hr>
<a name="Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029"></a>
<div class="header">
<p>
Next: <a href="#Untested-methods" accesskey="n" rel="next">Untested methods</a>, Previous: <a href="#Furthest-earleme-values" accesskey="p" rel="prev">Furthest earleme values</a>, Up: <a href="#Futures" accesskey="u" rel="up">Futures</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029-1"></a>
<h3 class="section">24.3 Additional recoverable failures in marpa_r_alternative()</h3>
<p>Among the hard failures that
marpa_r_alternative() returns
are the error codes
<code>MARPA_ERR_DUPLICATE_TOKEN</code>,
<code>MARPA_ERR_NO_TOKEN_EXPECTED_HERE</code>
and <code>MARPA_ERR_INACCESSIBLE_TOKEN</code>.
These are currently irrecoverable.
They may in fact be fully recoverable,
but are not documented as such because this has not been
tested.
</p>
<p>At this writing,
we know of no applications which
attempt to recover from these errors.
It is possible that
these error codes may also be useable for the
techniques similar to the Ruby Slippers,
as of this writing, we know of no proposals
to use them in this way.
</p>
<hr>
<a name="Untested-methods"></a>
<div class="header">
<p>
Previous: <a href="#Additional-recoverable-failures-in-marpa_005fr_005falternative_0028_0029" accesskey="p" rel="prev">Additional recoverable failures in marpa_r_alternative()</a>, Up: <a href="#Futures" accesskey="u" rel="up">Futures</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Untested-methods-1"></a>
<h3 class="section">24.4 Untested methods</h3>
<p>The methods of this section are not in the external interface,
because they have not been adequately tested.
Their fate is uncertain.
Users should regard these methods
as unsupported.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Ranking-methods" accesskey="1">Ranking methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Zero_002dwidth-assertion-methods" accesskey="2">Zero-width assertion methods</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Methods-for-revising-parses" accesskey="3">Methods for revising parses</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Ranking-methods"></a>
<div class="header">
<p>
Next: <a href="#Zero_002dwidth-assertion-methods" accesskey="n" rel="next">Zero-width assertion methods</a>, Previous: <a href="#Untested-methods" accesskey="p" rel="prev">Untested methods</a>, Up: <a href="#Untested-methods" accesskey="u" rel="up">Untested methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Ranking-methods-1"></a>
<h4 class="subsection">24.4.1 Ranking methods</h4>
<a name="marpa_005fg_005fdefault_005frank_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005fdefault_005frank_005fset"></a>Function: <em>Marpa_Rank</em> <strong>marpa_g_default_rank_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Rank <var>rank</var>)</em></dt>
<dd><a name="marpa_005fg_005fdefault_005frank"></a></dd><dt><a name="index-marpa_005fg_005fdefault_005frank"></a>Function: <em>Marpa_Rank</em> <strong>marpa_g_default_rank</strong> <em>( Marpa_Grammar <var>g</var>)</em></dt>
<dd>
<p>These methods, respectively, set
and query the default rank of the grammar.
When a grammar is created, the default rank is 0.
When rules and symbols are created, their rank is
the default rank of the grammar.
</p>
<p>Changing the grammar’s default rank does not affect
those
rules and symbols already created,
only those that will be created.
This means that
the grammar’s default rank can be used to,
in effect, assign ranks to groups of rules and symbols.
Applications may find this behavior useful.
</p>
<p>Return value: On success, returns
the rank <strong>after</strong>
the call,
and sets the error code to
<code>MARPA_ERR_NONE</code>.
On failure, returns -2,
and sets the error code to an appropriate
value, which will never be
<code>MARPA_ERR_NONE</code>.
Note that when the rank is -2,
the error code is the only way to distinguish
success from failure.
The error code can be determined by using the
<code>marpa_g_error()</code>
call.
</p>
</dd></dl>
<a name="marpa_005fg_005fsymbol_005frank_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005frank_005fset"></a>Function: <em>Marpa_Rank</em> <strong>marpa_g_symbol_rank_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>sym_id</var>, Marpa_Rank <var>rank</var>)</em></dt>
<dd><a name="marpa_005fg_005fsymbol_005frank"></a></dd><dt><a name="index-marpa_005fg_005fsymbol_005frank"></a>Function: <em>Marpa_Rank</em> <strong>marpa_g_symbol_rank</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID sym_id)</em></dt>
<dd>
<p>These methods, respectively, set
and query the rank of a symbol <var>sym_id</var>.
When <var>sym_id</var> is created, its rank
initialized to the default rank of the grammar.
</p>
<p>Return value: On success, returns
the rank <strong>after</strong>
the call,
and sets the error code to
<code>MARPA_ERR_NONE</code>.
On failure, returns -2,
and sets the error code to an appropriate
value, which will never be
<code>MARPA_ERR_NONE</code>.
Note that when the rank is -2,
the error code is the only way to distinguish
success from failure.
The error code can be determined by using the
<code>marpa_g_error()</code>
call.
</p>
</dd></dl>
<hr>
<a name="Zero_002dwidth-assertion-methods"></a>
<div class="header">
<p>
Next: <a href="#Methods-for-revising-parses" accesskey="n" rel="next">Methods for revising parses</a>, Previous: <a href="#Ranking-methods" accesskey="p" rel="prev">Ranking methods</a>, Up: <a href="#Untested-methods" accesskey="u" rel="up">Untested methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Zero_002dwidth-assertion-methods-1"></a>
<h4 class="subsection">24.4.2 Zero-width assertion methods</h4>
<a name="marpa_005fg_005fzwa_005fnew"></a><dl>
<dt><a name="index-marpa_005fg_005fzwa_005fnew"></a>Function: <em>Marpa_Assertion_ID</em> <strong>marpa_g_zwa_new</strong> <em>( Marpa_Grammar <var>g</var>, int <var>default_value</var>)</em></dt>
</dl>
<a name="marpa_005fg_005fzwa_005fplace"></a><dl>
<dt><a name="index-marpa_005fg_005fzwa_005fplace"></a>Function: <em>int</em> <strong>marpa_g_zwa_place</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Assertion_ID <var>zwaid</var>, Marpa_Rule_ID <var>xrl_id</var>, int <var>rhs_ix</var>)</em></dt>
</dl>
<a name="marpa_005fr_005fzwa_005fdefault"></a><dl>
<dt><a name="index-marpa_005fr_005fzwa_005fdefault"></a>Function: <em>int</em> <strong>marpa_r_zwa_default</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Assertion_ID <var>zwaid</var>)</em></dt>
<dd>
<p>On success, returns previous default value of the assertion.
</p></dd></dl>
<a name="marpa_005fr_005fzwa_005fdefault_005fset"></a><dl>
<dt><a name="index-marpa_005fr_005fzwa_005fdefault_005fset"></a>Function: <em>int</em> <strong>marpa_r_zwa_default_set</strong> <em>( Marpa_Recognizer <var>r</var>, Marpa_Assertion_ID <var>zwaid</var>, int <var>default_value</var>)</em></dt>
<dd>
<p>Changes default value to <var>default_value</var>.
On success, returns previous default value of the assertion.
</p></dd></dl>
<a name="marpa_005fg_005fhighest_005fzwa_005fid"></a><dl>
<dt><a name="index-marpa_005fg_005fhighest_005fzwa_005fid"></a>Function: <em>Marpa_Assertion_ID</em> <strong>marpa_g_highest_zwa_id</strong> <em>( Marpa_Grammar <var>g</var> )</em></dt>
</dl>
<hr>
<a name="Methods-for-revising-parses"></a>
<div class="header">
<p>
Previous: <a href="#Zero_002dwidth-assertion-methods" accesskey="p" rel="prev">Zero-width assertion methods</a>, Up: <a href="#Untested-methods" accesskey="u" rel="up">Untested methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Methods-for-revising-parses-1"></a>
<h4 class="subsection">24.4.3 Methods for revising parses</h4>
<p>Marpa allows an application to “change its mind” about a parse,
rejected rule previously recognized or predicted,
and terminals previously scanned.
The methods in this section provide that capability.
</p>
<a name="marpa_005fr_005fclean"></a><dl>
<dt><a name="index-marpa_005fr_005fclean"></a>Function: <em>Marpa_Earleme</em> <strong>marpa_r_clean</strong> <em>( Marpa_Recognizer <var>r</var>)</em></dt>
</dl>
<hr>
<a name="Deprecated-techniques-and-methods"></a>
<div class="header">
<p>
Next: <a href="#Index-of-terms" accesskey="n" rel="next">Index of terms</a>, Previous: <a href="#Futures" accesskey="p" rel="prev">Futures</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deprecated-techniques-and-methods-1"></a>
<h2 class="chapter">25 Deprecated techniques and methods</h2>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Valued-and-unvalued-symbols" accesskey="1">Valued and unvalued symbols</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Valued-and-unvalued-symbols"></a>
<div class="header">
<p>
Previous: <a href="#Deprecated-techniques-and-methods" accesskey="p" rel="prev">Deprecated techniques and methods</a>, Up: <a href="#Deprecated-techniques-and-methods" accesskey="u" rel="up">Deprecated techniques and methods</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Valued-and-unvalued-symbols-1"></a>
<h3 class="section">25.1 Valued and unvalued symbols</h3>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#What-unvalued-symbols-were" accesskey="1">What unvalued symbols were</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Grammar-methods-dealing-with-unvalued-symbols" accesskey="2">Grammar methods dealing with unvalued symbols</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="#Registering-semantics-in-the-valuator" accesskey="3">Registering semantics in the valuator</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="What-unvalued-symbols-were"></a>
<div class="header">
<p>
Next: <a href="#Grammar-methods-dealing-with-unvalued-symbols" accesskey="n" rel="next">Grammar methods dealing with unvalued symbols</a>, Previous: <a href="#Valued-and-unvalued-symbols" accesskey="p" rel="prev">Valued and unvalued symbols</a>, Up: <a href="#Valued-and-unvalued-symbols" accesskey="u" rel="up">Valued and unvalued symbols</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="What-unvalued-symbols-were-1"></a>
<h4 class="subsection">25.1.1 What unvalued symbols were</h4>
<p>Libmarpa symbols can have values,
which is the traditional way of doing semantics.
Libmarpa also allows symbols to be unvalued.
An
<a name="index-unvalued-symbol"></a>
<a name="index-symbol_002c-unvalued"></a>
<em>unvalued</em>
symbol is one whose value
is unpredictable from instance to instance.
If a symbol is unvalued, we sometimes say that it
has “whatever” semantics.
</p>
<p>Situations where the semantics can tolerate unvalued symbols
are surprisingly frequent.
For example, the top-level of many languages is a series
of major units, all of whose semantics are typically accomplished
via side effects.
The compiler is typically indifferent to the actual value produced
by these major units, and tracking them is a waste of time.
Similarly, the value of the separators in a list is typically
ignored.
</p>
<p>Rules are unvalued if and only if their LHS symbols
are unvalued.
When rules and symbols are unvalued,
Libmarpa optimizes their evaluation.
</p>
<p>It is in principle unsafe to check the value
of a symbol if it can be unvalued.
For this reason,
once a symbol has been treated as valued,
Libmarpa marks it as valued.
Similarly,
once a symbol has been treated as unvalued,
Libmarpa marks it as unvalued.
Once marked, a symbol’s valued status is
<a name="index-locked-value-status-_0028of-a-symbol_0029"></a>
<a name="index-value-status_002c-locked-_0028of-a-symbol_0029"></a>
<em>locked</em>
and cannot be changed later.
</p>
<p>The valued status of terminals is marked the first
time they are read.
The valued status of LHS symbols must be explicitly
marked by the application when initializing the
valuator — this is Libmarpa’s equivalent of
registering a callback.
</p>
<p>LHS terminals are disabled by default.
If allowed, the user should be aware that the valued
status of a LHS terminal
will be locked in the recognizer
if it is used as a terminal,
and the symbol’s use as a rule LHS
in the valuator must be
consistent with the recognizer’s marking.
</p>
<p>Marpa reports an error when a symbol’s use
conflicts with its locked valued status.
Doing so usually saves the Libmarpa user
some tricky debugging further down the road.
</p>
<hr>
<a name="Grammar-methods-dealing-with-unvalued-symbols"></a>
<div class="header">
<p>
Next: <a href="#Registering-semantics-in-the-valuator" accesskey="n" rel="next">Registering semantics in the valuator</a>, Previous: <a href="#What-unvalued-symbols-were" accesskey="p" rel="prev">What unvalued symbols were</a>, Up: <a href="#Valued-and-unvalued-symbols" accesskey="u" rel="up">Valued and unvalued symbols</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Grammar-methods-dealing-with-unvalued-symbols-1"></a>
<h4 class="subsection">25.1.2 Grammar methods dealing with unvalued symbols</h4>
<a name="marpa_005fg_005fsymbol_005fis_005fvalued_005fset"></a><dl>
<dt><a name="index-marpa_005fg_005fsymbol_005fis_005fvalued_005fset"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_valued_set</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>symbol_id</var>, int value)</em></dt>
<dd><a name="marpa_005fg_005fsymbol_005fis_005fvalued"></a></dd><dt><a name="index-marpa_005fg_005fsymbol_005fis_005fvalued"></a>Function: <em>int</em> <strong>marpa_g_symbol_is_valued</strong> <em>( Marpa_Grammar <var>g</var>, Marpa_Symbol_ID <var>symbol_id</var>)</em></dt>
<dd>
<p>These methods, respectively, set
and query the “valued status” of a symbol.
Once set to a value with the
<code>marpa_g_symbol_is_valued_set()</code>
method,
the valued status of a symbol is “locked” at that value.
It cannot thereafter be changed.
Subsequent calls to
<code>marpa_g_symbol_is_valued_set()</code>
for the same <var>sym_id</var> will fail,
leaving <var>sym_id</var>’s valued status unchanged,
unless <var>value</var> is the same as the locked-in value.
</p>
<p>Return value: On success, 1 if the symbol <var>symbol_id</var>
is valued after the call, 0 if not.
If the valued status is locked and <var>value</var>
is different from the current status, -2.
If <var>value</var> is not 0 or 1;
or on other failure, -2.
</p>
</dd></dl>
<hr>
<a name="Registering-semantics-in-the-valuator"></a>
<div class="header">
<p>
Previous: <a href="#Grammar-methods-dealing-with-unvalued-symbols" accesskey="p" rel="prev">Grammar methods dealing with unvalued symbols</a>, Up: <a href="#Valued-and-unvalued-symbols" accesskey="u" rel="up">Valued and unvalued symbols</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Registering-semantics-in-the-valuator-1"></a>
<h4 class="subsection">25.1.3 Registering semantics in the valuator</h4>
<p>By default, Libmarpa’s valuator objects
assume that
non-terminal symbols have
no semantics.
The archetypal application will need to register
symbols that contain semantics.
The primary method for doing this is
<code>marpa_v_symbol_is_valued()</code>.
Applications will typically register semantics by rule,
and these applications will find
the
<code>marpa_v_rule_is_valued()</code>
method more convenient.
</p>
<a name="marpa_005fv_005fsymbol_005fis_005fvalued_005fset"></a><dl>
<dt><a name="index-marpa_005fv_005fsymbol_005fis_005fvalued_005fset"></a>Function: <em>int</em> <strong>marpa_v_symbol_is_valued_set</strong> <em>( Marpa_Value <var>v</var>, Marpa_Symbol_ID <var>sym_id</var>, int <var>status</var> )</em></dt>
<dd><a name="marpa_005fv_005fsymbol_005fis_005fvalued"></a></dd><dt><a name="index-marpa_005fv_005fsymbol_005fis_005fvalued"></a>Function: <em>int</em> <strong>marpa_v_symbol_is_valued</strong> <em>( Marpa_Value <var>v</var>, Marpa_Symbol_ID <var>sym_id</var> )</em></dt>
<dd>
<p>These methods, respectively,
set and query
the valued status of symbol <var>sym_id</var>.
<code>marpa_v_symbol_is_valued_set()</code>
will set
the valued status to
the value of
its <var>status</var> argument.
A valued status of 1 indicates that the symbol is valued.
A valued status of 0 indicates that the symbol is unvalued.
If the valued status is locked,
an attempt to change to a status different from the
current one will fail
(error code <code>MARPA_ERR_VALUED_IS_LOCKED</code>).
</p>
<p>Return value: On success, the valued status <strong>after</strong>
the call.
If <var>value</var> is not either 0 or 1,
or on other failure, -2.
</p></dd></dl>
<a name="marpa_005fv_005frule_005fis_005fvalued_005fset"></a><dl>
<dt><a name="index-marpa_005fv_005frule_005fis_005fvalued_005fset"></a>Function: <em>int</em> <strong>marpa_v_rule_is_valued_set</strong> <em>( Marpa_Value <var>v</var>, Marpa_Rule_ID <var>rule_id</var>, int <var>status</var> )</em></dt>
<dd><a name="marpa_005fv_005frule_005fis_005fvalued"></a></dd><dt><a name="index-marpa_005fv_005frule_005fis_005fvalued"></a>Function: <em>int</em> <strong>marpa_v_rule_is_valued</strong> <em>( Marpa_Value <var>v</var>, Marpa_Rule_ID <var>rule_id</var> )</em></dt>
<dd>
<p>These methods, respectively,
set and query
the valued status
for the LHS symbol of rule <var>rule_id</var>.
<code>marpa_v_rule_is_valued_set()</code>
sets
the valued status to the value
of its <var>status</var> argument.
</p>
<p>A valued status of 1 indicates that the symbol is valued.
A valued status of 0 indicates that the symbol is unvalued.
If the valued status is locked,
an attempt to change to a status different from the
current one will fail
(error code <code>MARPA_ERR_VALUED_IS_LOCKED</code>).
</p>
<p>Rules have no valued status of their own.
The valued status of a rule
is always that of its LHS symbol.
These methods are conveniences — they
save the application the trouble of looking
up the rule’s LHS.
</p>
<p>Return value: On success, the valued status of the
rule <var>rule_id</var>’s LHS symbol <strong>after</strong>
the call.
If <var>value</var> is not either 0 or 1,
or on other failure, -2.
</p></dd></dl>
<a name="marpa_005fv_005fvalued_005fforce"></a><dl>
<dt><a name="index-marpa_005fv_005fvalued_005fforce"></a>Function: <em>int</em> <strong>marpa_v_valued_force</strong> <em>( Marpa_Value <var>v</var>)</em></dt>
<dd>
<p>This methods locks the valued status of all symbols
to 1, indicated that the symbol is valued.
If this is not possible, for example because one of
the grammar’s symbols already is locked at a valued
status of 0,
failure is returned.
</p>
<p>Return value: On success, a non-negative number.
On failure, returns -2,
and sets the error code to an appropriate
value, which will never be
<code>MARPA_ERR_NONE</code>.
</p>
</dd></dl>
<hr>
<a name="Index-of-terms"></a>
<div class="header">
<p>
Previous: <a href="#Deprecated-techniques-and-methods" accesskey="p" rel="prev">Deprecated techniques and methods</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-terms" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Index-of-terms-1"></a>
<h2 class="unnumbered">Index of terms</h2>
<p>This index is of terms that are used in a special sense in
this document.
Not every use of these terms is indexed —
only those uses which are in some way defining.
</p>
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index-of-terms_df_letter-A"><b>A</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-B"><b>B</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-C"><b>C</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-D"><b>D</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-E"><b>E</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-F"><b>F</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-H"><b>H</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-I"><b>I</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-L"><b>L</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-M"><b>M</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-N"><b>N</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-O"><b>O</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-P"><b>P</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-R"><b>R</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-S"><b>S</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-T"><b>T</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-U"><b>U</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-V"><b>V</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-W"><b>W</b></a>
</td></tr></table>
<table class="index-df" border="0">
<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-A">A</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-accessible-rule">accessible rule</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-accessible-symbol">accessible symbol</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-active-parse">active parse</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-advanced-input-model">advanced input model</a>:</td><td> </td><td valign="top"><a href="#Advanced-input-models">Advanced input models</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-advanced-models-of-input">advanced models of input</a>:</td><td> </td><td valign="top"><a href="#The-basic-models-of-input">The basic models of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-application">application</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-application-behavior">application behavior</a>:</td><td> </td><td valign="top"><a href="#Application-and-diagnostic-behavior">Application and diagnostic behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-applications_002c-exhaustion_002dhating">applications, exhaustion-hating</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-applications_002c-exhaustion_002dloving">applications, exhaustion-loving</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-archetypal-Libmarpa-application">archetypal Libmarpa application</a>:</td><td> </td><td valign="top"><a href="#About-the-overviews">About the overviews</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-B">B</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-base-grammarbase-grammar-_0028of-a-time-object_0029">base grammar (of a time object)</a>:</td><td> </td><td valign="top"><a href="#Time-objects">Time objects</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-basic-models-of-input">basic models of input</a>:</td><td> </td><td valign="top"><a href="#The-basic-models-of-input">The basic models of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-behavior_002c-application">behavior, application</a>:</td><td> </td><td valign="top"><a href="#Application-and-diagnostic-behavior">Application and diagnostic behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-behavior_002c-diagnostic">behavior, diagnostic</a>:</td><td> </td><td valign="top"><a href="#Application-and-diagnostic-behavior">Application and diagnostic behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-boolean">boolean</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-boolean-value">boolean value</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-C">C</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-child-objectchild-object-_0028of-a-time-object_0029">child object (of a time object)</a>:</td><td> </td><td valign="top"><a href="#Time-objects">Time objects</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-counted-symbol">counted symbol</a>:</td><td> </td><td valign="top"><a href="#Sequence-methods">Sequence methods</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-dense-variable_002dlength-input-model">dense variable-length input model</a>:</td><td> </td><td valign="top"><a href="#The-dense-variable_002dlength-token-model">The dense variable-length token model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-diagnostic-behavior">diagnostic behavior</a>:</td><td> </td><td valign="top"><a href="#Application-and-diagnostic-behavior">Application and diagnostic behavior</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-E">E</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-earleme">earleme</a>:</td><td> </td><td valign="top"><a href="#The-traditional-input-model">The traditional input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-earleme_002c-current">earleme, current</a>:</td><td> </td><td valign="top"><a href="#The-current-earleme">The current earleme</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-earleme_002c-empty">earleme, empty</a>:</td><td> </td><td valign="top"><a href="#The-fully-general-input-model">The fully general input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-earleme_002c-furthest">earleme, furthest</a>:</td><td> </td><td valign="top"><a href="#The-furthest-earleme">The furthest earleme</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-earleme_002c-latest">earleme, latest</a>:</td><td> </td><td valign="top"><a href="#The-latest-earleme">The latest earleme</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Earley-item-warning-threshold">Earley item warning threshold</a>:</td><td> </td><td valign="top"><a href="#Other-parse-status-methods">Other parse status methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Earley-set_002c-latest">Earley set, latest</a>:</td><td> </td><td valign="top"><a href="#The-latest-earleme">The latest earleme</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-empty-earleme">empty earleme</a>:</td><td> </td><td valign="top"><a href="#The-fully-general-input-model">The fully general input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-exhausted-parse">exhausted parse</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-exhaustion_002dhating-applications">exhaustion-hating applications</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-exhaustion_002dloving-applications">exhaustion-loving applications</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-F">F</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure">failure</a>:</td><td> </td><td valign="top"><a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-fully-recoverable-hard">failure, fully recoverable hard</a>:</td><td> </td><td valign="top"><a href="#Fully-recoverable-hard-failure">Fully recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-hard">failure, hard</a>:</td><td> </td><td valign="top"><a href="#Classifying-failure">Classifying failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-irrecoverable-hard">failure, irrecoverable hard</a>:</td><td> </td><td valign="top"><a href="#Irrecoverable-hard-failure">Irrecoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-Libmarpa-application-programming">failure, Libmarpa application programming</a>:</td><td> </td><td valign="top"><a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-library_002drecoverable-hard">failure, library-recoverable hard</a>:</td><td> </td><td valign="top"><a href="#Library_002drecoverable-hard-failure">Library-recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-memory-allocation">failure, memory allocation</a>:</td><td> </td><td valign="top"><a href="#Memory-allocation-failure">Memory allocation failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-partially-recoverable-hard">failure, partially recoverable hard</a>:</td><td> </td><td valign="top"><a href="#Partially-recoverable-hard-failure">Partially recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-soft">failure, soft</a>:</td><td> </td><td valign="top"><a href="#Classifying-failure">Classifying failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-soft-1">failure, soft</a>:</td><td> </td><td valign="top"><a href="#Soft-failure">Soft failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-failure_002c-undetected">failure, undetected</a>:</td><td> </td><td valign="top"><a href="#Undetected-failure">Undetected failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frozen-ordering">frozen ordering</a>:</td><td> </td><td valign="top"><a href="#Ordering-overview">Ordering overview</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fully-recoverable-hard-failure">fully recoverable hard failure</a>:</td><td> </td><td valign="top"><a href="#Fully-recoverable-hard-failure">Fully recoverable hard failure</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-H">H</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-hard-failure">hard failure</a>:</td><td> </td><td valign="top"><a href="#Classifying-failure">Classifying failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hard-failure_002c-fully-recoverable">hard failure, fully recoverable</a>:</td><td> </td><td valign="top"><a href="#Fully-recoverable-hard-failure">Fully recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hard-failure_002c-irrecoverable">hard failure, irrecoverable</a>:</td><td> </td><td valign="top"><a href="#Irrecoverable-hard-failure">Irrecoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hard-failure_002c-library_002drecoverable">hard failure, library-recoverable</a>:</td><td> </td><td valign="top"><a href="#Library_002drecoverable-hard-failure">Library-recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hard-failure_002c-partially-recoverable">hard failure, partially recoverable</a>:</td><td> </td><td valign="top"><a href="#Partially-recoverable-hard-failure">Partially recoverable hard failure</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-I">I</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-ID-_0028of-an-Earley-set_0029">ID (of an Earley set)</a>:</td><td> </td><td valign="top"><a href="#The-traditional-input-model">The traditional input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iff">iff</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-immediately-previous-_0028to-a-marpa_005fr_005fearleme_005fcomplete_0028_0029-call_0029">immediately previous (to a <code>marpa_r_earleme_complete()</code> call)</a>:</td><td> </td><td valign="top"><a href="#The-standard-model-of-input">The standard model of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-input-model_002c-advanced">input model, advanced</a>:</td><td> </td><td valign="top"><a href="#Advanced-input-models">Advanced input models</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-input-model_002c-dense-variable_002dlength">input model, dense variable-length</a>:</td><td> </td><td valign="top"><a href="#The-dense-variable_002dlength-token-model">The dense variable-length token model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-input-model_002c-sparse-variable_002dlength">input model, sparse variable-length</a>:</td><td> </td><td valign="top"><a href="#The-fully-general-input-model">The fully general input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-input-model_002c-variable_002dlength-token">input model, variable-length token</a>:</td><td> </td><td valign="top"><a href="#Advanced-input-models">Advanced input models</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-input_002c-advanced-models-of">input, advanced models of</a>:</td><td> </td><td valign="top"><a href="#The-basic-models-of-input">The basic models of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-input_002c-basic-models-of">input, basic models of</a>:</td><td> </td><td valign="top"><a href="#The-basic-models-of-input">The basic models of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-irrecoverable-hard-failure">irrecoverable hard failure</a>:</td><td> </td><td valign="top"><a href="#Irrecoverable-hard-failure">Irrecoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iterator_002c-parse-tree">iterator, parse tree</a>:</td><td> </td><td valign="top"><a href="#Tree-overview">Tree overview</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-L">L</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Libmarpa-application-programming-failure">Libmarpa application programming failure</a>:</td><td> </td><td valign="top"><a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Libmarpa-application-programming-success">Libmarpa application programming success</a>:</td><td> </td><td valign="top"><a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Libmarpa-application_002c-archetypal">Libmarpa application, archetypal</a>:</td><td> </td><td valign="top"><a href="#About-the-overviews">About the overviews</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-library_002drecoverable-hard-failure">library-recoverable hard failure</a>:</td><td> </td><td valign="top"><a href="#Library_002drecoverable-hard-failure">Library-recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-locked-value-status-_0028of-a-symbol_0029">locked value status (of a symbol)</a>:</td><td> </td><td valign="top"><a href="#What-unvalued-symbols-were">What unvalued symbols were</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-max_0028x_002cy_0029">max(x,y)</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-memory-allocation-failur">memory allocation failur</a>:</td><td> </td><td valign="top"><a href="#Memory-allocation-failure">Memory allocation failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-method">method</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-models-of-input_002c-advanced">models of input, advanced</a>:</td><td> </td><td valign="top"><a href="#The-basic-models-of-input">The basic models of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-models-of-input_002c-basic">models of input, basic</a>:</td><td> </td><td valign="top"><a href="#The-basic-models-of-input">The basic models of input</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-N">N</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-nullable-rule">nullable rule</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-nullable-symbol">nullable symbol</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-nulling-rule">nulling rule</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-nulling-symbol">nulling symbol</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-O">O</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-ordering_002c-frozen">ordering, frozen</a>:</td><td> </td><td valign="top"><a href="#Ordering-overview">Ordering overview</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ordinal-_0028of-an-Earley-set_0029">ordinal (of an Earley set)</a>:</td><td> </td><td valign="top"><a href="#The-traditional-input-model">The traditional input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-our">our</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-P">P</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-parent-objectparent-object-_0028of-a-time-object_0029">parent object (of a time object)</a>:</td><td> </td><td valign="top"><a href="#Time-objects">Time objects</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-parse-tree">parse tree</a>:</td><td> </td><td valign="top"><a href="#Tree-overview">Tree overview</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-parse-tree-iterator">parse tree iterator</a>:</td><td> </td><td valign="top"><a href="#Tree-overview">Tree overview</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-parse_002c-active">parse, active</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-parse_002c-exhausted">parse, exhausted</a>:</td><td> </td><td valign="top"><a href="#Exhaustion">Exhaustion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-partially-recoverable-hard-failure">partially recoverable hard failure</a>:</td><td> </td><td valign="top"><a href="#Partially-recoverable-hard-failure">Partially recoverable hard failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-previous-_0028to-a-marpa_005fr_005fearleme_005fcomplete_0028_0029-call_0029_002c-immediately">previous (to a <code>marpa_r_earleme_complete()</code> call), immediately</a>:</td><td> </td><td valign="top"><a href="#The-standard-model-of-input">The standard model of input</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-productive-rule">productive rule</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-productive-symbol">productive symbol</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-proper-separation">proper separation</a>:</td><td> </td><td valign="top"><a href="#Sequence-methods">Sequence methods</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-R">R</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Ruby-Slippers">Ruby Slippers</a>:</td><td> </td><td valign="top"><a href="#Recognizer-life-cycle-mutators">Recognizer life cycle mutators</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rule_002c-accessible">rule, accessible</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rule_002c-nullable">rule, nullable</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rule_002c-nulling">rule, nulling</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rule_002c-productive">rule, productive</a>:</td><td> </td><td valign="top"><a href="#Rule-methods">Rule methods</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-S">S</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-separation_002c-proper">separation, proper</a>:</td><td> </td><td valign="top"><a href="#Sequence-methods">Sequence methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-soft-failure">soft failure</a>:</td><td> </td><td valign="top"><a href="#Classifying-failure">Classifying failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-soft-failure-1">soft failure</a>:</td><td> </td><td valign="top"><a href="#Soft-failure">Soft failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sparse-variable_002dlength-input-model">sparse variable-length input model</a>:</td><td> </td><td valign="top"><a href="#The-fully-general-input-model">The fully general input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-success">success</a>:</td><td> </td><td valign="top"><a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-success_002c-Libmarpa-application-programming">success, Libmarpa application programming</a>:</td><td> </td><td valign="top"><a href="#User-non_002dconformity-to-specified-behavior">User non-conformity to specified behavior</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002c-accessible">symbol, accessible</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002c-counted">symbol, counted</a>:</td><td> </td><td valign="top"><a href="#Sequence-methods">Sequence methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002c-nullable">symbol, nullable</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002c-nulling">symbol, nulling</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002c-productive">symbol, productive</a>:</td><td> </td><td valign="top"><a href="#Symbol-methods">Symbol methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002c-unvalued">symbol, unvalued</a>:</td><td> </td><td valign="top"><a href="#What-unvalued-symbols-were">What unvalued symbols were</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-T">T</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-tree">tree</a>:</td><td> </td><td valign="top"><a href="#Tree-overview">Tree overview</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-U">U</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-undetected-failure">undetected failure</a>:</td><td> </td><td valign="top"><a href="#Undetected-failure">Undetected failure</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unvalued-symbol">unvalued symbol</a>:</td><td> </td><td valign="top"><a href="#What-unvalued-symbols-were">What unvalued symbols were</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-us">us</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-user">user</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-V">V</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-valuator">valuator</a>:</td><td> </td><td valign="top"><a href="#Value-overview">Value overview</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-value-status_002c-locked-_0028of-a-symbol_0029">value status, locked (of a symbol)</a>:</td><td> </td><td valign="top"><a href="#What-unvalued-symbols-were">What unvalued symbols were</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-value_002c-boolean">value, boolean</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-variable_002dlength-input-model_002c-dense">variable-length input model, dense</a>:</td><td> </td><td valign="top"><a href="#The-dense-variable_002dlength-token-model">The dense variable-length token model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-variable_002dlength-input-model_002c-sparse">variable-length input model, sparse</a>:</td><td> </td><td valign="top"><a href="#The-fully-general-input-model">The fully general input model</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-variable_002dlength-token-input-model">variable-length token input model</a>:</td><td> </td><td valign="top"><a href="#Advanced-input-models">Advanced input models</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Index-of-terms_df_letter-W">W</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-we">we</a>:</td><td> </td><td valign="top"><a href="#Terminology-and-notation">Terminology and notation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index-of-terms_df_letter-A"><b>A</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-B"><b>B</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-C"><b>C</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-D"><b>D</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-E"><b>E</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-F"><b>F</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-H"><b>H</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-I"><b>I</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-L"><b>L</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-M"><b>M</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-N"><b>N</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-O"><b>O</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-P"><b>P</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-R"><b>R</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-S"><b>S</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-T"><b>T</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-U"><b>U</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-V"><b>V</b></a>
<a class="summary-letter" href="#Index-of-terms_df_letter-W"><b>W</b></a>
</td></tr></table>
<hr>
</body>
</html>