ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-06-29 05:24:57 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/core-module/3-pc.html
Graham Nelson 7974df5af2 Tidied typos
2022-04-30 22:32:10 +01:00

766 lines
88 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Plugin Calls</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body class="commentary-font">
<nav role="navigation">
<h1><a href="../index.html">
<img src="../docs-assets/Inform.png" height=72">
</a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../indocn.html">indoc</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
<li><a href="../inrtpsn.html">inrtps</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="../../../inweb/index.html">inweb</a></li>
<li><a href="../../../intest/index.html">intest</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Plugin Calls' generated by Inweb-->
<div class="breadcrumbs">
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inform7n.html">Inform7</a></li><li><a href="index.html">core</a></li><li><a href="index.html#3">Chapter 3: Plugins</a></li><li><b>Plugin Calls</b></li></ul></div>
<p class="purpose">The interface between the main compiler and its plugins.</p>
<ul class="toc"><li><a href="3-pc.html#SP2">&#167;2. Influencing core</a></li><li><a href="3-pc.html#SP3">&#167;3. Influencing assertions</a></li><li><a href="3-pc.html#SP18">&#167;18. Influencing values</a></li><li><a href="3-pc.html#SP23">&#167;23. Influencing knowledge</a></li><li><a href="3-pc.html#SP36">&#167;36. Influencing the imperative plugin</a></li><li><a href="3-pc.html#SP41">&#167;41. Influencing the actions plugin</a></li></ul><hr class="tocbar">
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. </b>The following set of functions is an API for the main compiler to consult
with the plugins; put another way, it is also an API for the plugins to
influence the main compiler. They do so by adding plugs to the relevant rulebooks:
see <a href="3-pm.html#SP8" class="internal">PluginManager::plug</a>.
</p>
<p class="commentary">Nothing can prevent this from being a big old miscellany, so we take them by
compiler module, and within each module in alphabetical order.
</p>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. Influencing core. </b>Called from <a href="1-wtc.html#SP5" class="internal">Task::advance_stage_to</a>. This allows plugins to run additional
production-line steps in compilation, and that is done mostly at the Inter
generation stage, to add extra arrays or functions needed at run-time to
support whatever feature the plugin implements. For example, the mapping plugin
compiles an array to hold the map during stage <span class="extract"><span class="extract-syntax">INTER1_CSEQ</span></span>.
</p>
<p class="commentary">Because the following is called at the end of every main stage of compilation
except for <span class="extract"><span class="extract-syntax">FINISHED_CSEQ</span></span>, it is called about 15 times in all, so it is
essential to check <span class="extract"><span class="extract-syntax">stage</span></span> and act only on the right occasion. <span class="extract"><span class="extract-syntax">debugging</span></span> is
<span class="extract"><span class="extract-syntax">TRUE</span></span> if this is a debugging run, and allows a plugin to generate diagnostic
features if so.
</p>
<p class="commentary">A function attached to this plug should then ideally divide its work up into
major subtasks and call each one with the <span class="extract"><span class="extract-syntax">BENCH</span></span> macro, so that the time it
takes will (if appreciable) be included in the <a href="../inform7/M-pm.html" class="internal">Performance Metrics (in inform7)</a>.
</p>
<p class="commentary">See <a href="1-htc.html" class="internal">How To Compile</a> for the stages and their <span class="extract"><span class="extract-syntax">*_CSEQ</span></span> numbers.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">PRODUCTION_LINE_PLUG</span><span class="plain-syntax"> </span><span class="identifier-syntax">from</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::production_line</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">PluginCalls::production_line</span></span>:<br/>What To Compile - <a href="1-wtc.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">stage</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">debugging</span><span class="plain-syntax">, </span><span class="identifier-syntax">stopwatch_timer</span><span class="plain-syntax"> *</span><span class="identifier-syntax">timer</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">PRODUCTION_LINE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">stage</span><span class="plain-syntax">, </span><span class="identifier-syntax">debugging</span><span class="plain-syntax">, </span><span class="identifier-syntax">timer</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. Influencing assertions. </b>Called from <a href="../assertions-module/4-rpt.html" class="internal">Refine Parse Tree (in assertions)</a> to ask if this node is a noun
phrase with special significance: for example, "below" is significant to the
mapping plugin. If so, the plugin should set the subject of the node to say
what it refers to, and return <span class="extract"><span class="extract-syntax">TRUE</span></span>.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">ACT_ON_SPECIAL_NPS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::act_on_special_NPs</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">ACT_ON_SPECIAL_NPS_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>Called from <a href="../assertions-module/4-ass2.html" class="internal">Assemblies (in assertions)</a>. Body-snatching is used only by the
"player" plugin, and is explained there; it handles the consequences of sentences
like "The player is Lord Collingwood".
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">DETECT_BODYSNATCHING_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::detect_bodysnatching</span><span class="plain-syntax">(</span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> *</span><span class="identifier-syntax">body</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">snatcher</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> **</span><span class="identifier-syntax">counterpart</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">DETECT_BODYSNATCHING_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">body</span><span class="plain-syntax">, </span><span class="identifier-syntax">snatcher</span><span class="plain-syntax">, </span><span class="identifier-syntax">counterpart</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>Called from <a href="../assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> to see if any plugin wants to
intepret a sentence its own way, either taking direct action or issuing a
more nuanced problem message than the usual machinery would have issued.
If so, the plugin should return <span class="extract"><span class="extract-syntax">TRUE</span></span>, which both ensures that no other
plugin intervenes, and also tells <a href="../assertions-module/index.html" class="internal">assertions</a> not to proceed further
with the sentence.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">INTERVENE_IN_ASSERTION_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::intervene_in_assertion</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">px</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">py</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">INTERVENE_IN_ASSERTION_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">px</span><span class="plain-syntax">, </span><span class="identifier-syntax">py</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>Called from <a href="../assertions-module/4-tc.html" class="internal">The Creator (in assertions)</a> when a copular sentence may be
creating something. For example, the actions plugin needs this.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">CREATION_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::creation</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">px</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">py</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">CREATION_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">px</span><span class="plain-syntax">, </span><span class="identifier-syntax">py</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>Called from <a href="../assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> when an unfamiliar node type appears
where a property value might be expected. For example, the actions plugin
uses this to deal with setting a property to an <span class="extract"><span class="extract-syntax">ACTION_NT</span></span> node. To
intervene, set the node specification using <a href="../assertions-module/4-rpt.html" class="internal">Refine Parse Tree (in assertions)</a>
and return <span class="extract"><span class="extract-syntax">TRUE</span></span>; or return <span class="extract"><span class="extract-syntax">FALSE</span></span> to let nature take its course.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">UNUSUAL_PROPERTY_VALUE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::unusual_property_value</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">py</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">UNUSUAL_PROPERTY_VALUE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">py</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>Called from <a href="../assertions-module/4-tc.html" class="internal">The Creator (in assertions)</a> when an instance is being made in
an assembly, and its name may involve a genitive. For example, if the
assembly says "every person has a nose", then normally this would be called
something like "Mr Rogers's nose"; but the player plugin uses the following
to have "your nose" in the case of the player instance.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">IRREGULAR_GENITIVE_IN_ASSEMBLY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::irregular_genitive</span><span class="plain-syntax">(</span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">genitive</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">propriety</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">IRREGULAR_GENITIVE_IN_ASSEMBLY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">genitive</span><span class="plain-syntax">, </span><span class="identifier-syntax">propriety</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>Called from <a href="../assertions-module/2-bv.html" class="internal">Booting Verbs (in assertions)</a> to give each plugin a chance to
create any special sentence meanings it would like to. For example, the
sounds plugin defines a special form of assertion sentence this way. The
plugin should always return <span class="extract"><span class="extract-syntax">FALSE</span></span>, since otherwise it may gazump other
plugins and cause them to stop working.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">MAKE_SPECIAL_MEANINGS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::make_special_meanings</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALLV</span><span class="plain-syntax">(</span><span class="constant-syntax">MAKE_SPECIAL_MEANINGS_PLUG</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. </b>Called from <a href="../assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> when it seems that the author wants
to create a property of something with a sentence like "A container has a
number called security rating." A plugin can intervene and act on that,
returning <span class="extract"><span class="extract-syntax">TRUE</span></span> to stop the usual machinery. For example, the actions
plugin does this so that "The going action has a number called celerity"
can be intercepted to create an action variable, not a property.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">OFFERED_PROPERTY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::offered_property</span><span class="plain-syntax">(</span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">K</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">what</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">OFFERED_PROPERTY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">K</span><span class="plain-syntax">, </span><span class="identifier-syntax">owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">what</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;11. </b>Called from <a href="../assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> when the specification pseudo-variable
is about to be set for something; the plugin can then intercept this.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">OFFERED_SPECIFICATION_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::offered_specification</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">OFFERED_SPECIFICATION_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>Called from <a href="../assertions-module/4-rpt.html" class="internal">Refine Parse Tree (in assertions)</a> to ask plugins if a noun phrase
has a noun implicit within it, even though none is explicitly given. For
example, the player plugin uses this to say that "initially carried" means
"...by the player", and sets the subject of the node to be the player character
instance.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">REFINE_IMPLICIT_NOUN_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::refine_implicit_noun</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">REFINE_IMPLICIT_NOUN_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>Called from <a href="../assertions-module/2-cs.html" class="internal">Classifying Sentences (in assertions)</a> to give plugins the chance
of an early look at a newly-read assertion. For example, the map plugin uses
this to spot that a sentence will create a new direction.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_ASSERTION_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_assertion_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_ASSERTION_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">p</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. </b>Called from <a href="../assertions-module/8-terr.html" class="internal">The Equality Relation Revisited (in assertions)</a> when we have
to decide if it's valid to ask or declare that two things are the same.
Returning <span class="extract"><span class="extract-syntax">TRUE</span></span> says that it is always valid; returning <span class="extract"><span class="extract-syntax">FALSE</span></span> leaves
it to the regular machinery. This plug can therefore only be used to permit
additional usages, not to restrict existing ones.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">TYPECHECK_EQUALITY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::typecheck_equality</span><span class="plain-syntax">(</span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">K1</span><span class="plain-syntax">, </span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">K2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">TYPECHECK_EQUALITY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">K1</span><span class="plain-syntax">, </span><span class="identifier-syntax">K2</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>&#167;15. </b>Called from <a href="../assertions-module/4-ass.html" class="internal">Assertions (in assertions)</a> to warn plugins that a variable
is now being assigned a value by an explicit assertion sentence.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">VARIABLE_VALUE_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::variable_set_warning</span><span class="plain-syntax">(</span><span class="identifier-syntax">nonlocal_variable</span><span class="plain-syntax"> *</span><span class="identifier-syntax">q</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">val</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">VARIABLE_VALUE_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">q</span><span class="plain-syntax">, </span><span class="identifier-syntax">val</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>&#167;16. </b>Called from <a href="../assertions-module/5-rf.html" class="internal">Rule Family (in assertions)</a> to warn plugins that a new rule
definition has been found in the source text.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_RULE_DEFN_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_rule_defn_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">imperative_defn</span><span class="plain-syntax"> *</span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">rule_family_data</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rfd</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_RULE_DEFN_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">rfd</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>&#167;17. </b>Called from <a href="../assertions-module/5-rcd.html" class="internal">Runtime Context Data (in assertions)</a> to warn plugins that
a new set of runtime context data is being made.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_RCD_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_rcd_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">id_runtime_context_data</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rcd</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_RCD_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">rcd</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>&#167;18. Influencing values. </b>Called from <a href="../values-module/2-rvl.html" class="internal">Rvalues (in values)</a> to allow plugins to help decide whether values
of the same kind would be equal if evaluated at runtime. For example, the
"scenes" plugin uses this to determine if two <span class="extract"><span class="extract-syntax">K_scene</span></span> constants are equal.
To make a decision, set <span class="extract"><span class="extract-syntax">rv</span></span> to either <span class="extract"><span class="extract-syntax">TRUE</span></span> or <span class="extract"><span class="extract-syntax">FALSE</span></span> and return <span class="extract"><span class="extract-syntax">TRUE</span></span>.
To make no decision, return <span class="extract"><span class="extract-syntax">FALSE</span></span>.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPARE_CONSTANT_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compare_constant</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">c1</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">c2</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rv</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPARE_CONSTANT_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">c1</span><span class="plain-syntax">, </span><span class="identifier-syntax">c2</span><span class="plain-syntax">, </span><span class="identifier-syntax">rv</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>&#167;19. </b>Called from <a href="../values-module/2-rvl.html" class="internal">Rvalues (in values)</a> to allow plugins to compile rvalues in
eccentric ways of their own: not in fact just for the whimsy of it, but to
make it possible for plugins to support base kinds of their own. For example,
the "actions" plugin needs this to deal with the "stored action" kind.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPILE_CONSTANT_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compile_constant</span><span class="plain-syntax">(</span><span class="identifier-syntax">value_holster</span><span class="plain-syntax"> *</span><span class="identifier-syntax">VH</span><span class="plain-syntax">, </span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">K</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">spec</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPILE_CONSTANT_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">VH</span><span class="plain-syntax">, </span><span class="identifier-syntax">K</span><span class="plain-syntax">, </span><span class="identifier-syntax">spec</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>&#167;20. </b>Called from <a href="../values-module/2-cnd.html" class="internal">Conditions (in values)</a> to allow plugins to compile conditions in
their own way. For example, the "actions" plugin needs this to compile matches
of the current action against an action pattern.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPILE_CONDITION_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compile_condition</span><span class="plain-syntax">(</span><span class="identifier-syntax">value_holster</span><span class="plain-syntax"> *</span><span class="identifier-syntax">VH</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">spec</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPILE_CONDITION_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">VH</span><span class="plain-syntax">, </span><span class="identifier-syntax">spec</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>&#167;21. </b>Called from <a href="../values-module/2-spc.html" class="internal">Specifications (in values)</a> to ask if there is some reason why
a rule about <span class="extract"><span class="extract-syntax">I1</span></span> should be thought broader in scope than one about <span class="extract"><span class="extract-syntax">I2</span></span>. This
is used by the regions plugin when one is a sub-region of the other. This is
expected to behave as a <span class="extract"><span class="extract-syntax">strcmp</span></span>-like sorting function, with a positive
return value saying <span class="extract"><span class="extract-syntax">I1</span></span> is broader, negative <span class="extract"><span class="extract-syntax">I2</span></span>, or zero that they are equal.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">MORE_SPECIFIC_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::more_specific</span><span class="plain-syntax">(</span><span class="identifier-syntax">instance</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I1</span><span class="plain-syntax">, </span><span class="identifier-syntax">instance</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">MORE_SPECIFIC_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">I1</span><span class="plain-syntax">, </span><span class="identifier-syntax">I2</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP22" class="paragraph-anchor"></a><b>&#167;22. </b>Called from <a href="../values-module/4-cad.html" class="internal">Constants and Descriptions (in values)</a> to give plugins a chance
to parse text which might otherwise be meaningless (or mean something different)
and make it a "composite noun-quantifier" such as "everywhere" or "nothing".
The main compiler does not recognise "everywhere" because it has no concept
of space, but the spatial plugin does, and this is how.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">PARSE_COMPOSITE_NQS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::parse_composite_NQs</span><span class="plain-syntax">(</span><span class="identifier-syntax">wording</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> *</span><span class="identifier-syntax">DW</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">quantifier</span><span class="plain-syntax"> **</span><span class="identifier-syntax">quantifier_used</span><span class="plain-syntax">, </span><span class="identifier-syntax">kind</span><span class="plain-syntax"> **</span><span class="identifier-syntax">some_kind</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">PARSE_COMPOSITE_NQS_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">DW</span><span class="plain-syntax">, </span><span class="identifier-syntax">quantifier_used</span><span class="plain-syntax">, </span><span class="identifier-syntax">some_kind</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP23" class="paragraph-anchor"></a><b>&#167;23. Influencing knowledge. </b>Called from <a href="../knowledge-module/5-tmw.html" class="internal">The Model World (in knowledge)</a> to invite the plugin to participate
in stages I to V of the completion process. This may involve using contextual
reasoning to draw further inferences.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPLETE_MODEL_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::complete_model</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">stage</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPLETE_MODEL_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">stage</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP24" class="paragraph-anchor"></a><b>&#167;24. </b>Called from <a href="../knowledge-module/4-is.html" class="internal">Inference Subjects (in knowledge)</a> to invite the plugin to
create any additional inference subjects it might want to reason about. In
practice, this tends to be used to create preliminary subjects to stand in
for significant kinds before those kinds are ready to be created.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">CREATE_INFERENCE_SUBJECTS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::create_inference_subjects</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALLV</span><span class="plain-syntax">(</span><span class="constant-syntax">CREATE_INFERENCE_SUBJECTS_PLUG</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP25" class="paragraph-anchor"></a><b>&#167;25. </b>Called from <a href="../knowledge-module/5-ia.html" class="internal">Indefinite Appearance (in knowledge)</a> to ask the plugins what
inferences, if any, to draw from a double-quoted text standing as an entire
sentence. The <span class="extract"><span class="extract-syntax">infs</span></span> is the subject which was being talked about at the time
the text was quoted, and therefore presumably is what the text should describe.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">DEFAULT_APPEARANCE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::default_appearance</span><span class="plain-syntax">(</span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> *</span><span class="identifier-syntax">infs</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">txt</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">DEFAULT_APPEARANCE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">infs</span><span class="plain-syntax">, </span><span class="identifier-syntax">txt</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP26" class="paragraph-anchor"></a><b>&#167;26. </b>Called from <a href="../knowledge-module/5-inf.html" class="internal">Inferences (in knowledge)</a> when an inference is drawn about
something. This does not, of course, necessarily mean that this will actually
be the property of something: the inference might turn out to be mistaken. The
mapping plugin uses this to infer further that if something is said to be a
map connection to somewhere else, then it is probably a room.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">INFERENCE_DRAWN_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::inference_drawn</span><span class="plain-syntax">(</span><span class="identifier-syntax">inference</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> *</span><span class="identifier-syntax">subj</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">INFERENCE_DRAWN_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">subj</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP27" class="paragraph-anchor"></a><b>&#167;27. </b>Called from <a href="../knowledge-module/4-ks.html" class="internal">Kind Subjects (in knowledge)</a>. Early in the run, before some kinds
are created, placeholder inference subjects are created to stand in for them;
this call enables plugins to recognise certain texts as referring to those.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NAME_TO_EARLY_INFS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::name_to_early_infs</span><span class="plain-syntax">(</span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> **</span><span class="identifier-syntax">infs</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NAME_TO_EARLY_INFS_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">infs</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP28" class="paragraph-anchor"></a><b>&#167;28. </b>Called from <a href="../knowledge-module/4-ks.html" class="internal">Kind Subjects (in knowledge)</a> to warn plugins about a new kind,
which in practice enables them to spot from the name that it is actually a kind
they want to provide built-in support for: thus the actions plugin reacts to
the name "stored action", for example. <span class="extract"><span class="extract-syntax">K</span></span> is the newcomer, <span class="extract"><span class="extract-syntax">super</span></span> its super-kind,
if any; <span class="extract"><span class="extract-syntax">d</span></span> and <span class="extract"><span class="extract-syntax">W</span></span> are alternate forms of that name &mdash; <span class="extract"><span class="extract-syntax">d</span></span> will be useful if the
kind was created by a kit (such as "number"), <span class="extract"><span class="extract-syntax">W</span></span> if it came from Inform 7
source text (such as "container").
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_BASE_KIND_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_base_kind_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">K</span><span class="plain-syntax">, </span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">super</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">d</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_BASE_KIND_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">K</span><span class="plain-syntax">, </span><span class="identifier-syntax">d</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP29" class="paragraph-anchor"></a><b>&#167;29. </b>Called from <a href="../knowledge-module/2-ins.html" class="internal">Instances (in knowledge)</a> to warn plugins that a new instance has
been created. For example, the figures plugin needs to know this so that it
can see when a new illustration has been created.
</p>
<p class="commentary">At the time this is called, the exact kind of an instance may not be known,
if that instance is an object: so beware of relying on the kind unless you're
sure you're not dealing with an object.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_INSTANCE_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_named_instance_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">instance</span><span class="plain-syntax"> *</span><span class="identifier-syntax">nc</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_INSTANCE_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">nc</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP30" class="paragraph-anchor"></a><b>&#167;30. </b>Called from <a href="../knowledge-module/4-pp.html" class="internal">Property Permissions (in knowledge)</a> to warn plugins that a subject
has been given permission to hold a property; the parsing plugin, for example,
uses this to attach a visibility flag.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_PERMISSION_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_permission_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">property_permission</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pp</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_PERMISSION_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">pp</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP31" class="paragraph-anchor"></a><b>&#167;31. </b>Called from <a href="../knowledge-module/3-prp.html" class="internal">Properties (in knowledge)</a> to warn plugins that a property has
been created, which they can use to spot properties with special significance
to them.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_PROPERTY_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_property_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">property</span><span class="plain-syntax"> *</span><span class="identifier-syntax">prn</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_PROPERTY_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">prn</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP32" class="paragraph-anchor"></a><b>&#167;32. </b>Called from <a href="../knowledge-module/4-is.html" class="internal">Inference Subjects (in knowledge)</a> to warn plugins that a subject
has been created, which they can use to spot subjects with special significance
to them.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_SUBJECT_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_subject_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">inference_subject</span><span class="plain-syntax"> *</span><span class="identifier-syntax">subj</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_SUBJECT_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">subj</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP33" class="paragraph-anchor"></a><b>&#167;33. </b>Called from <a href="../knowledge-module/2-nv.html" class="internal">Nonlocal Variables (in knowledge)</a> to warn plugins that a new
variable has been created, which they can use to spot variables with special
significance to them.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_VARIABLE_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_variable_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">nonlocal_variable</span><span class="plain-syntax"> *</span><span class="identifier-syntax">q</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_VARIABLE_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">q</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP34" class="paragraph-anchor"></a><b>&#167;34. </b>Called from <a href="../knowledge-module/2-ins.html" class="internal">Instances (in knowledge)</a> to warn plugins that the kind of an
instance is about to be set. This happens most often when the instance is
created, but can also happen again, refining the kind to a subkind, when
the instance is an object.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">SET_KIND_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::set_kind_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">instance</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">k</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">SET_KIND_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">k</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP35" class="paragraph-anchor"></a><b>&#167;35. </b>Called from <a href="../knowledge-module/4-ks.html" class="internal">Kind Subjects (in knowledge)</a> when one kind of object is made a
subkind of another, as for example when "container" is a made a subkind of
"thing". The plugin should return <span class="extract"><span class="extract-syntax">TRUE</span></span> if it wishes to forbid this,
and if so, it had better throw a problem message, or the user will be
mystified.
</p>
<p class="commentary">This can be used to forbid certain kinds having subkinds, as for example the
regions plugin does with the "region" kind.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">SET_SUBKIND_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::set_subkind_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sub</span><span class="plain-syntax">, </span><span class="identifier-syntax">kind</span><span class="plain-syntax"> *</span><span class="identifier-syntax">super</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">SET_SUBKIND_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">sub</span><span class="plain-syntax">, </span><span class="identifier-syntax">super</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP36" class="paragraph-anchor"></a><b>&#167;36. Influencing the imperative plugin. </b>Called from <a href="../assertions-module/6-rb.html" class="internal">Rule Bookings (in assertions)</a> to give plugins a chance to move
automatically placed rules from one rulebook to another. The actions plugin
uses this to break up what would otherwise be unwieldy before and after
rulebooks into smaller ones for each action.
</p>
<p class="commentary">If making a diversion, the plugin should write the new rulebook into <span class="extract"><span class="extract-syntax">new_owner</span></span>
and return <span class="extract"><span class="extract-syntax">TRUE</span></span>; and otherwise <span class="extract"><span class="extract-syntax">FALSE</span></span>.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">PLACE_RULE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::place_rule</span><span class="plain-syntax">(</span><span class="identifier-syntax">rule</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">rulebook</span><span class="plain-syntax"> *</span><span class="identifier-syntax">original_owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">rulebook</span><span class="plain-syntax"> **</span><span class="identifier-syntax">new_owner</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">PLACE_RULE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">original_owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">new_owner</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP37" class="paragraph-anchor"></a><b>&#167;37. </b>Called from <a href="../assertions-module/6-rlb.html" class="internal">Rulebooks (in assertions)</a>. This is very similar, but runs in all cases,
and not only for automatic placement.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">RULE_PLACEMENT_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::rule_placement_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">rule</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">rulebook</span><span class="plain-syntax"> *</span><span class="identifier-syntax">original_owner</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">side</span><span class="plain-syntax">, </span><span class="identifier-syntax">rule</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ref_rule</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">RULE_PLACEMENT_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">original_owner</span><span class="plain-syntax">, </span><span class="identifier-syntax">side</span><span class="plain-syntax">, </span><span class="identifier-syntax">ref_rule</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP38" class="paragraph-anchor"></a><b>&#167;38. </b></p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPILE_TEST_HEAD_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compile_test_head</span><span class="plain-syntax">(</span><span class="identifier-syntax">id_body</span><span class="plain-syntax"> *</span><span class="identifier-syntax">idb</span><span class="plain-syntax">, </span><span class="identifier-syntax">rule</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">tests</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPILE_TEST_HEAD_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">idb</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">tests</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP39" class="paragraph-anchor"></a><b>&#167;39. </b></p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPILE_TEST_TAIL_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compile_test_tail</span><span class="plain-syntax">(</span><span class="identifier-syntax">id_body</span><span class="plain-syntax"> *</span><span class="identifier-syntax">idb</span><span class="plain-syntax">, </span><span class="identifier-syntax">rule</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPILE_TEST_TAIL_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">idb</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP40" class="paragraph-anchor"></a><b>&#167;40. </b>Called from <a href="../imperative-module/5-cii.html" class="internal">Compile Invocations Inline (in imperative)</a>, but only when an
annotation arises which the regular machinery doesn't know how to handle.
This is currently only used by <a href="../if-module/3-tr.html" class="internal">Timed Rules (in if)</a>.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">INLINE_ANNOTATION_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::nonstandard_inline_annotation</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">annot</span><span class="plain-syntax">, </span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">supplied</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">INLINE_ANNOTATION_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">annot</span><span class="plain-syntax">, </span><span class="identifier-syntax">supplied</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP41" class="paragraph-anchor"></a><b>&#167;41. Influencing the actions plugin. </b>We now have a whole run of functions called only by the actions plugin, and
therefore only when it is active.
</p>
<p class="commentary">Called from <a href="../if-module/4-ap.html" class="internal">Actions Plugin (in if)</a> to signal that a new action has been
created. For example, the going plugin uses this to spot the arrival of "going".
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_ACTION_NOTIFY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_action_notify</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">an</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_ACTION_NOTIFY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">an</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP42" class="paragraph-anchor"></a><b>&#167;42. </b>Called from <a href="../if-module/4-apc.html" class="internal">Action Pattern Clauses (in if)</a> to invite plugins to change the
action pattern clause ID associated with a given action variable. This may be
needed in order to cross-reference between multiple such clauses, as with
the going action variables.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">DIVERT_AP_CLAUSE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::divert_AP_clause_ID</span><span class="plain-syntax">(</span><span class="identifier-syntax">shared_variable</span><span class="plain-syntax"> *</span><span class="identifier-syntax">stv</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">id</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> *</span><span class="identifier-syntax">id</span><span class="plain-syntax"> = -1;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">DIVERT_AP_CLAUSE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">stv</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP43" class="paragraph-anchor"></a><b>&#167;43. </b>Called from <a href="../if-module/4-apc.html" class="internal">Action Pattern Clauses (in if)</a> to ask plugins to print a helpful
name for the debugging log for any new clause ID <span class="extract"><span class="extract-syntax">C</span></span> which they have created.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">WRITE_AP_CLAUSE_ID_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::write_AP_clause_ID</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">WRITE_AP_CLAUSE_ID_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP44" class="paragraph-anchor"></a><b>&#167;44. </b>Called from <a href="../if-module/4-apc.html" class="internal">Action Pattern Clauses (in if)</a> to ask for the <span class="extract"><span class="extract-syntax">*_APCA</span></span> aspect
for the clause ID <span class="extract"><span class="extract-syntax">C</span></span>, where <span class="extract"><span class="extract-syntax">C</span></span> is a new clause ID created by the plugin. If
this is not given, then the aspect will be <span class="extract"><span class="extract-syntax">MISC_APCA</span></span>.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">ASPECT_OF_AP_CLAUSE_ID_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::aspect_of_AP_clause_ID</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">A</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">ASPECT_OF_AP_CLAUSE_ID_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">A</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP45" class="paragraph-anchor"></a><b>&#167;45. </b>Called from <a href="../if-module/4-apc.html" class="internal">Action Pattern Clauses (in if)</a> to give plugins a chance to
decide which AP is more specific, on the basis of the extra clauses defined
in the plugin.
</p>
<p class="commentary">If the plugin recognises the patterns as ways to describe an action it knows
about, it can choose to take the decision, storing either 1 or -1 in
<span class="extract"><span class="extract-syntax">rv</span></span>, and returning <span class="extract"><span class="extract-syntax">TRUE</span></span>. If it instead stores 0 in <span class="extract"><span class="extract-syntax">rv</span></span>, it can also
choose to set <span class="extract"><span class="extract-syntax">ignore_in</span></span>, which tells the usual machinery not to judge on the
basis of the <span class="extract"><span class="extract-syntax">[in: ...]</span></span> clause in the pattern.
</p>
<p class="commentary">If the plugin sees nothing relevant about the patterns, it should return <span class="extract"><span class="extract-syntax">FALSE</span></span>
to let the usual machinery take its course.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPARE_AP_SPECIFICITY_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compare_AP_specificity</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ap1</span><span class="plain-syntax">, </span><span class="identifier-syntax">action_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ap2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">rv</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ignore_in</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPARE_AP_SPECIFICITY_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">ap1</span><span class="plain-syntax">, </span><span class="identifier-syntax">ap2</span><span class="plain-syntax">, </span><span class="identifier-syntax">rv</span><span class="plain-syntax">, </span><span class="identifier-syntax">ignore_in</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP46" class="paragraph-anchor"></a><b>&#167;46. </b>Called from <a href="../if-module/4-apc.html" class="internal">Action Pattern Clauses (in if)</a> to notify plugins that a clause
matching an action variable has just been added to an action pattern.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">NEW_AP_CLAUSE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::new_action_variable_clause</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ap</span><span class="plain-syntax">, </span><span class="identifier-syntax">ap_clause</span><span class="plain-syntax"> *</span><span class="identifier-syntax">apoc</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">NEW_AP_CLAUSE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">ap</span><span class="plain-syntax">, </span><span class="identifier-syntax">apoc</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP47" class="paragraph-anchor"></a><b>&#167;47. </b>Called from <a href="../if-module/4-pc.html" class="internal">Parse Clauses (in if)</a> to give plugins a chance to intervene in
the normal process of evaluating the meaning of text in an action pattern
clause: for example, in parsing "going nowhere", the going plugin uses this
to detect that the <span class="extract"><span class="extract-syntax">NOUN_AP_CLAUSE</span></span>, with text "nowhere", should not be parsed
normally. What it does it to set a bit in the bitmap <span class="extract"><span class="extract-syntax">bits</span></span>, which it will pick
up again and act upon when reacting to <span class="extract"><span class="extract-syntax">ACT_ON_ANL_ENTRY_OPTIONS_PLUG</span></span>.
</p>
<p class="commentary">If the plugin does not set a bit in <span class="extract"><span class="extract-syntax">bits</span></span>, the normal machinery parses the
text of the clause in the normal way.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">PARSE_AP_CLAUSE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::parse_AP_clause</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">an</span><span class="plain-syntax">, </span><span class="identifier-syntax">anl_clause</span><span class="plain-syntax"> *</span><span class="identifier-syntax">c</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">bits</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">PARSE_AP_CLAUSE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">an</span><span class="plain-syntax">, </span><span class="identifier-syntax">c</span><span class="plain-syntax">, </span><span class="identifier-syntax">bits</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP48" class="paragraph-anchor"></a><b>&#167;48. </b>Called from <a href="../if-module/4-pc.html" class="internal">Parse Clauses (in if)</a> to give plugins a chance to intervene in
the type-checking process for a clause. Ordinarily, this would just check that
the contents have the right kind: if matching an action variable of kind <span class="extract"><span class="extract-syntax">K</span></span>
then it must be a value compatible with <span class="extract"><span class="extract-syntax">K</span></span> or a description of such.
</p>
<p class="commentary">By returning <span class="extract"><span class="extract-syntax">TRUE</span></span>, a plugin can instead take responsibility for the decision
itself, bypassing that. The <span class="extract"><span class="extract-syntax">outcome</span></span> should then be set <span class="extract"><span class="extract-syntax">TRUE</span></span> (it's valid)
or <span class="extract"><span class="extract-syntax">FALSE</span></span> (it isn't).
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">VALIDATE_AP_CLAUSE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::validate_AP_clause</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">an</span><span class="plain-syntax">, </span><span class="identifier-syntax">anl_clause</span><span class="plain-syntax"> *</span><span class="identifier-syntax">c</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">outcome</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">VALIDATE_AP_CLAUSE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">an</span><span class="plain-syntax">, </span><span class="identifier-syntax">c</span><span class="plain-syntax">, </span><span class="identifier-syntax">outcome</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP49" class="paragraph-anchor"></a><b>&#167;49. </b>Called from <a href="../if-module/4-pc.html" class="internal">Parse Clauses (in if)</a> to deal with the options bitmap set
previously by a <span class="extract"><span class="extract-syntax">PARSE_AP_CLAUSE_PLUG</span></span> call: see above.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">ACT_ON_ANL_ENTRY_OPTIONS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::act_on_ANL_entry_options</span><span class="plain-syntax">(</span><span class="identifier-syntax">anl_entry</span><span class="plain-syntax"> *</span><span class="identifier-syntax">entry</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">entry_options</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">fail</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">ACT_ON_ANL_ENTRY_OPTIONS_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">entry</span><span class="plain-syntax">, </span><span class="identifier-syntax">entry_options</span><span class="plain-syntax">, </span><span class="identifier-syntax">fail</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP50" class="paragraph-anchor"></a><b>&#167;50. </b>Called from <a href="../imperative-module/2-map.html" class="internal">Matching Action Patterns (in imperative)</a> when assembling the requirement
clauses for compiling a mattern match; this gives plugins a chance to act
extra stipulations, which are not explicit in clauses already in the pattern.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">SET_PATTERN_MATCH_REQUIREMENTS_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::set_pattern_match_requirements</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ap</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">cpm</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">needed</span><span class="plain-syntax">[</span><span class="identifier-syntax">MAX_CPM_CLAUSES</span><span class="plain-syntax">], </span><span class="identifier-syntax">ap_clause</span><span class="plain-syntax"> *</span><span class="identifier-syntax">needed_apoc</span><span class="plain-syntax">[</span><span class="identifier-syntax">MAX_CPM_CLAUSES</span><span class="plain-syntax">]) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">SET_PATTERN_MATCH_REQUIREMENTS_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">ap</span><span class="plain-syntax">, </span><span class="identifier-syntax">cpm</span><span class="plain-syntax">, </span><span class="identifier-syntax">needed</span><span class="plain-syntax">, </span><span class="identifier-syntax">needed_apoc</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP51" class="paragraph-anchor"></a><b>&#167;51. </b>Called from <a href="../imperative-module/2-map.html" class="internal">Matching Action Patterns (in imperative)</a> when compiling any additional
requirements set by <span class="extract"><span class="extract-syntax">SET_PATTERN_MATCH_REQUIREMENTS_PLUG</span></span>.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">COMPILE_PATTERN_MATCH_CLAUSE_PLUG</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">PluginCalls::compile_pattern_match_clause</span><span class="plain-syntax">(</span><span class="identifier-syntax">action_pattern</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ap</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">cpmc</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">PLUGINS_CALL</span><span class="plain-syntax">(</span><span class="constant-syntax">COMPILE_PATTERN_MATCH_CLAUSE_PLUG</span><span class="plain-syntax">, </span><span class="identifier-syntax">ap</span><span class="plain-syntax">, </span><span class="identifier-syntax">cpmc</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="3-pm.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-cm.html">1</a></li><li class="progresschapter"><a href="2-up.html">2</a></li><li class="progresscurrentchapter">3</li><li class="progresssection"><a href="3-pm.html">pm</a></li><li class="progresscurrent">pc</li><li class="progressnextoff">&#10095;</li></ul></div>
</nav><!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink