<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../services.html">Services</a></li><li><ahref="index.html">syntax</a></li><li><ahref="index.html#P">Preliminaries</a></li><li><b>How To Include This Module</b></li></ul></div>
<pclass="purpose">What to do to make use of the syntax module in a new command-line tool.</p>
<ulclass="toc"><li><ahref="P-htitm.html#SP1">§1. Status</a></li><li><ahref="P-htitm.html#SP2">§2. Importing the module</a></li><li><ahref="P-htitm.html#SP3">§3. Using callbacks</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Status. </b>The syntax module provided as one of the "services" suite of modules, which means
that it was built with a view to potential incorporation in multiple tools.
It can be found, for example, in <ahref="../inform7/index.html"class="internal">inform7</a>, <ahref="../inbuild/index.html"class="internal">inbuild</a> and <ahref="../syntax-test/index.html"class="internal">syntax-test</a>,
among others. <ahref="../syntax-test/index.html"class="internal">syntax-test</a> may be useful as a minimal example of a tool
using <ahref="index.html"class="internal">syntax</a>.
<pclass="commentary">A tool can import <ahref="index.html"class="internal">syntax</a> only if it also imports <ahref="../../../inweb/foundation-module/index.html"class="internal">foundation</a> and
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. Importing the module. </b>We'll use the term "parent" to mean the tool which is importing <ahref="index.html"class="internal">syntax</a>,
<ulclass="items"><li>● The parent must call <spanclass="extract"><spanclass="extract-syntax">SyntaxModule::start()</span></span> just after it starts up, and
<spanclass="extract"><spanclass="extract-syntax">SyntaxModule::end()</span></span> just before it shuts down. (But just after, and just
<pclass="commentary">But in addition, the parent of <ahref="index.html"class="internal">syntax</a> must define some Preform grammar:
</p>
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax"><language-modifying-sentence></span></span> to recognise sentences modifying the
language which is currently being parsed;
</li><li>●<spanclass="extract"><spanclass="extract-syntax"><structural-sentence></span></span> to recognise structurally important sentences;
</li><li>●<spanclass="extract"><spanclass="extract-syntax"><dividing-sentence></span></span> to recognise sentences which divide up the text,
normally headings;
</li><li>●<spanclass="extract"><spanclass="extract-syntax"><comma-divisible-sentence></span></span> to recognise sentences where a comma plays
a role normally expected to be played by a colon.
</li></ul>
<pclass="commentary">Though compulsory, these don't need to do much: see <ahref="../syntax-test/1-ut.html"class="internal">Unit Tests (in syntax-test)</a>.
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Using callbacks. </b>Shared modules like this one are tweaked in behaviour by defining "callback
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax">AMBIGUITY_JOIN_SYNTAX_CALLBACK</span></span> can rearrange ambiguous readings as
</li><li>●<spanclass="extract"><spanclass="extract-syntax">BEGIN_OR_END_HERE_SYNTAX_CALLBACK</span></span> is called when a new extension beginning
or ending sentence is found in the source text being broken into sentences:
see <ahref="3-snt.html#SP6"class="internal">Sentences::make_node</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">IS_SENTENCE_NODE_SYNTAX_CALLBACK</span></span> is asked whether a given node represents
a regular sentence or not: see <ahref="2-nt.html#SP11"class="internal">NodeType::is_sentence</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">LANGUAGE_ELEMENT_SYNTAX_CALLBACK</span></span> is called when a sentence is found matching
the nonterminal <spanclass="extract"><spanclass="extract-syntax"><language-modifying-sentence></span></span>: see <ahref="3-snt.html#SP6"class="internal">Sentences::make_node</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">LOG_UNENUMERATED_NODE_TYPES_SYNTAX_CALLBACK</span></span> is called to log a node type
not recognised as one of the enumerated <spanclass="extract"><spanclass="extract-syntax">*_NT</span></span> values: see <ahref="2-nt.html#SP8"class="internal">NodeType::log</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">NEW_HEADING_SYNTAX_CALLBACK</span></span> is called when a new heading sentence is found
in the source text being broken into sentences: see <ahref="3-snt.html#SP6"class="internal">Sentences::make_node</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">NEW_HEADING_TREE_SYNTAX_CALLBACK</span></span> is called when a new syntax tree is being
created, and needs to be given a matching tree of headings: see <ahref="2-st.html#SP2"class="internal">SyntaxTree::new</a>.
and <spanclass="extract"><spanclass="extract-syntax">EVEN_MORE_NODE_METADATA_SETUP_SYNTAX_CALLBACK</span></span> adds new syntax tree node
types: see <ahref="2-nt.html#SP12"class="internal">NodeType::metadata_setup</a>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">PARENTAGE_EXCEPTIONS_SYNTAX_CALLBACK</span></span> allows exceptions to the rules about
which nodes in a syntax tree can be parents of which other nodes: see
</li><li>●<spanclass="extract"><spanclass="extract-syntax">NEW_NONSTRUCTURAL_SENTENCE_SYNTAX_CALLBACK</span></span> is called when a new, regular
sentence is found in the source text being broken into sentences: see
</li><li>●<spanclass="extract"><spanclass="extract-syntax">UNKNOWN_PREFORM_RESULT_SYNTAX_CALLBACK</span></span> is used only by the Preform cache:
if this isn't being used, it's sufficient to return a null pointer. See