What to do to make use of the linguistics module in a new command-line tool.

§1. Status. 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 inform7 and linguistics-test.

By convention, the modules considered as "services" have no dependencies on other modules except for foundation and other "services" modules.

A tool can import linguistics only if it also imports foundation, words, syntax, inflections and lexicon.

§2. Importing the module. We'll use the term "parent" to mean the tool which is importing linguistics, that is, which will include its code and be able to use it. As with any imported module, 

Import: somepath/linguistics

§3. Meaning types. 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 VERB_MEANING_LINGUISTICS_TYPE 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.)

For example, the core module sets: 

    @d VERB_MEANING_LINGUISTICS_TYPE struct binary_predicate

The parent may also want to define VERB_MEANING_UNIVERSAL_CALCULUS_RELATION, which should be a value of this type, and represents the "to relate" verb which can assert any verb meaning — for example, "X relates to Y by R". See Verb Usages.

§4. Using callbacks. 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.

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 would be 

    @d EXPRESS_SURPRISE_LINGUISTICS_CALLBACK Emotions::gosh

    =
    void Emotions::gosh(text_stream *OUT) {
        WRITE("Good gracious!\n");
    }

The linguistics module has many callbacks, but they are all optional. The following alphabetical list has references to fuller explanations: