<!--Weave of 'How To Include This Module' generated by Inweb-->
<divclass="breadcrumbs">
<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../compiler.html">Services</a></li><li><ahref="index.html">linguistics</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 linguistics 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. Meaning types</a></li><li><ahref="P-htitm.html#SP4">§4. Using callbacks</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="SP1"></a><b>§1. Status. </b>The linguistics module is 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> and
<pclass="commentary">By convention, the modules considered as "services" have no dependencies on
other modules except for <ahref="../../../inweb/docs/foundation-module/index.html"class="internal">foundation</a> and other "services" modules.
</p>
<pclass="commentary">A tool can import <ahref="index.html"class="internal">linguistics</a> only if it also imports <ahref="../../../inweb/docs/foundation-module/index.html"class="internal">foundation</a>,
<ahref="../words-module/index.html"class="internal">words</a>, <ahref="../syntax-module/index.html"class="internal">syntax</a>, <ahref="../inflections-module/index.html"class="internal">inflections</a> and <ahref="../lexicon-module/index.html"class="internal">lexicon</a>.
<pclass="commentary firstcommentary"><aid="SP2"></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">linguistics</a>,
that is, which will include its code and be able to use it. As with any
imported module,
</p>
<ulclass="items"><li>● The contents page of the parent's web must identify and locate the
<ulclass="items"><li>● The parent must call <spanclass="extract"><spanclass="extract-syntax">InflectionsModule::start()</span></span> just after it starts up, and
<spanclass="extract"><spanclass="extract-syntax">InflectionsModule::end()</span></span> just before it shuts down. (But just after, and just
before, the corresponding calls to <ahref="../../../inweb/docs/foundation-module/index.html"class="internal">foundation</a>.)
</li></ul>
<pclass="commentary firstcommentary"><aid="SP3"></a><b>§3. Meaning types. </b>This module tries to be agnostic about the actual meanings of words: it knows
about verbs, but not about what any specific verb means. The idea is that the
parent tool specifies that, with some type of its own. The constant
<spanclass="extract"><spanclass="extract-syntax">VERB_MEANING_LINGUISTICS_TYPE</span></span> should be defined to what this actually is;
it should be the name of a class of objects. (If it isn't defined, then no
meaning is attached to verbs at all.)
</p>
<pclass="commentary">For example, the <ahref="../core-module/index.html"class="internal">core</a> module sets:
<pclass="commentary">The parent may also want to define <spanclass="extract"><spanclass="extract-syntax">VERB_MEANING_UNIVERSAL</span></span>, which should be
a value of this type, and represents the "to relate" verb which can assert
<pclass="commentary firstcommentary"><aid="SP4"></a><b>§4. Using callbacks. </b>Shared modules like this one are tweaked in behaviour by defining "callback
functions". This means that the parent might provide a function of its own
which would answer a question put to it by the module, or take some action
on behalf of the module: it's a callback in the sense that the parent is
normally calling the module, but then the module calls the parent back to
ask for data or action.
</p>
<pclass="commentary">The parent must indicate which function to use by defining a constant with
a specific name as being equal to that function's name. A fictional example
<pclass="commentary">The linguistics module has many callbacks, but they are all optional. The
following alphabetical list has references to fuller explanations:
</p>
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax">ADAPTIVE_PERSON_LINGUISTICS_CALLBACK</span></span> returns the default person for adaptive
text generation; in Inform, this tends to be the value of the adaptive text viewpoint
property for the natural language of play. Similarly, <spanclass="extract"><spanclass="extract-syntax">ADAPTIVE_NUMBER_LINGUISTICS_CALLBACK</span></span>
</li><li>●<spanclass="extract"><spanclass="extract-syntax">ADJECTIVE_NAME_VETTING_LINGUISTICS_CALLBACK</span></span> should return <spanclass="extract"><spanclass="extract-syntax">TRUE</span></span> if the given
name is acceptable as an adjective, and should otherwise print some sort of
error message and return <spanclass="extract"><spanclass="extract-syntax">FALSE</span></span>. If this callback is not provided, all non-empty
</li><li>●<spanclass="extract"><spanclass="extract-syntax">ALLOW_VERB_IN_ASSERTIONS_LINGUISTICS_CALLBACK</span></span> and <spanclass="extract"><spanclass="extract-syntax">ALLOW_VERB_LINGUISTICS_CALLBACK</span></span>
give the parent control over which forms of verbs are allowed: for examole, <ahref="../core-module/index.html"class="internal">core</a>
allows them in assertions only in the third person (singular or plural), whereas
it allows them in any form in non-assertion contexts. See
</li><li>●<spanclass="extract"><spanclass="extract-syntax">ADJECTIVE_COMPILATION_LINGUISTICS_CALLBACK</span></span>, if provided, should accompany a
declaration of a structure called <spanclass="extract"><spanclass="extract-syntax">adjecttve_compilation_data</span></span>; this function should
</li><li>●<spanclass="extract"><spanclass="extract-syntax">NOUN_DISAMBIGUATION_LINGUISTICS_CALLBACK</span></span>, if provided, should accompany a
declaration of a structure called <spanclass="extract"><spanclass="extract-syntax">name_resolution_data</span></span>; this function should
decide which possible reading of the meaning of a noun makes the best sense in
</li><li>●<spanclass="extract"><spanclass="extract-syntax">TRACING_LINGUISTICS_CALLBACK</span></span>, if provided, can return <spanclass="extract"><spanclass="extract-syntax">TRUE</span></span> to allow
extensive details of verb parsing to be copied to the debugging log. See
</li><li>●<spanclass="extract"><spanclass="extract-syntax">VERB_MEANING_REVERSAL_LINGUISTICS_CALLBACK</span></span> reverses the meaning of a verb:
in the sense that the reversal of "A knows B" would be "A is known by B",