<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>What This Module Does</b></li></ul></div>
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Prerequisites. </b>The syntax module is a part of the Inform compiler toolset. It is
full details, but essentially: it's C without predeclarations or header files,
and where functions have names like <spanclass="extract"><spanclass="extract-syntax">Tags::add_by_name</span></span> rather than <spanclass="extract"><spanclass="extract-syntax">add_by_name</span></span>.
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. Syntax trees. </b>Most algorithms for parsing natural language involve the construction of
trees, in which the original words appear as leaves at the top of the tree,
while the grammatical functions they serve appear as the branches and trunk:
thus the word "orange", as an adjective, might be growing from a branch
which represents a noun clause ("the orange envelope"), growing in turn from
a trunk which in turn might represent a assertion sentence:
</p>
<blockquote>
<p>The card is in the orange envelope.</p>
</blockquote>
<pclass="commentary">The Inform tools represent syntax trees by <ahref="2-st.html#SP2"class="internal">parse_node_tree</a> structures
(see <ahref="2-st.html#SP2"class="internal">SyntaxTree::new</a>), but there are very few of these: the entire
source text compiled by <ahref="../inform7/index.html"class="internal">inform7</a> is just one syntax tree. When <ahref="../supervisor-module/index.html"class="internal">supervisor</a>
manages extensions, it may generate one <ahref="2-st.html#SP2"class="internal">parse_node_tree</a> object for each
extension whose text it reads. Still — there are few trees.
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. </b>The trunk of the tree can be grown in any sequence: call <ahref="2-st.html#SP3"class="internal">SyntaxTree::push_bud</a>
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. </b>Meaning is an ambiguous thing, and so the tree needs to be capable of
representing multiple interpretations of the same wording. So nodes have not
only <spanclass="extract"><spanclass="extract-syntax">next</span></span> and <spanclass="extract"><spanclass="extract-syntax">down</span></span> links to other nodes, but also <spanclass="extract"><spanclass="extract-syntax">next_alternative</span></span> links,
which — if used — fork the syntax tree into different possible readings.
</p>
<pclass="commentary">These are not added to the tree by grafting: that's only done for definite
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. </b>An extensive suite of functions is provided to make it easy to traverse
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. Nodes. </b>Syntax trees are made up of <ahref="2-pn.html#SP1"class="internal">parse_node</a> structures. While these are in
principle individual nodes, they effectively represent subtrees, because they
carry with them links to the nodes below. A <ahref="2-pn.html#SP1"class="internal">parse_node</a> object can
therefore equally represent "orange", "the orange envelope", or "now the card
is in the orange envelope".
</p>
<pclass="commentary">Each node carries three essential pieces of information with it:
</p>
<ulclass="items"><li>(1) The text giving rise to it (say, "Section Five - Fruit").
</li><li>(2) A node type ID, which in broad terms says what kind of reference is being
made (say, <spanclass="extract"><spanclass="extract-syntax">HEADING_NT</span></span>). The possible node types are stored in the C type
<spanclass="extract"><spanclass="extract-syntax">node_type_t</span></span>, which corresponds to some metadata in a <ahref="2-nt.html#SP3"class="internal">node_type_metadata</a>
object: see <ahref="2-pn.html#SP5"class="internal">Node::get_type</a> and <ahref="2-nt.html#SP7"class="internal">NodeType::get_metadata</a>.
</li><li>(3) A list of optional annotations, which are either integer or object-valued,
and which give specifics about the meaning (say, the level number in the
hierarchy of headings). See <ahref="2-na.html"class="internal">Node Annotations</a>.
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. Fussy, defensive, pedantry. </b>Safe to say that Inform includes bugs: the more defensive coding we can do,
but also strict verification tests on every tree made (see <ahref="2-tv.html"class="internal">Tree Verification</a>).
</p>
<ulclass="items"><li>(a) The only nodes allowed to exist are those for node types declared
by <ahref="2-nt.html#SP9"class="internal">NodeType::new</a>: more generally, see <ahref="2-nt.html"class="internal">Node Types</a> on metadata associated
with these.
</li><li>(b) A node of type <spanclass="extract"><spanclass="extract-syntax">A</span></span> can only be a child of a node of type <spanclass="extract"><spanclass="extract-syntax">B</span></span> if
<ahref="2-nt.html#SP13"class="internal">NodeType::parentage_allowed</a> says so, and this is (mostly) a matter
of calling <ahref="2-nt.html#SP5"class="internal">NodeType::allow_parentage_for_categories</a>— parentage depends
not on the type per se, but on the category of the type, which groups types
together.
</li><li>(c) A node of type <spanclass="extract"><spanclass="extract-syntax">A</span></span> can only have an annotation with ID <spanclass="extract"><spanclass="extract-syntax">I</span></span> if
