<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:trans="http://docbook.org/ns/transclusion"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <?xxe-sn 2ahy8s1pw5c 7f?>

  <title><?xxe-sn 2ahy8s1pw5c 7g?>Modules API</title>

  <para><?xxe-sn 2ahy8s1pw5c 7h?>Modules Resolution is a process of finding
  out which modules should be preloaded for a correct compilation of a given
  module.</para>

  <para><?xxe-sn 2ahy8s1pw5c 7i?>Resolution expected to use <code><?xxe-sn 2ahy8s1pw5c 7j?>bind_module</code>,
  <code><?xxe-sn 2ahy8s1pw5c 7k?>modules_require</code> as an input and
  produce results in form of <code><?xxe-sn 2ahy8s1pw5c 7l?>modules_resolution</code>
  data table.</para>

  <section>
    <?xxe-sn 2ahy8s1pw5c 7m?>

    <title><?xxe-sn 2ahy8s1pw5c 7n?>Module Annotations: 'bind_module'</title>

    <synopsis><?xxe-sn 2ahy8s1pw5c 7o?>SYNTAX:
**bind_module**(//module-ref//, //annotation//)</synopsis>

    <itemizedlist>
      <?xxe-sn 2ahy8s1pw5c 7p?>

      <listitem>
        <?xxe-sn 2ahy8s1pw5c 7q?>

        <para><?xxe-sn 2ahy8s1pw5c 7r?><emphasis><?xxe-sn 2ahy8s1pw5c 7s?>module-ref</emphasis>
        module's path</para>
      </listitem>
    </itemizedlist>

    <para><?xxe-sn 2ahy8s1pw5c 7t?>Declares module annotations.</para>

    <para><?xxe-sn 2ahy8s1pw5c 7u?>Example:</para>

    <programlisting xml:id="ModAnn_1"><?xxe-sn 2ahy8s1pw5c 7v?>name="tests/modules.cpp: Modules_API.Doc_ModAnn_1"
module:: status(obsolete).</programlisting>

    <para><?xxe-sn 2ahy8s1pw5c 7w?>Produced fact: <code
    xml:id="Output_ModAnn_1"><?xxe-sn 2ahy8s1pw5c 7x?>bind_module("/path/to/module",status(obsolete))</code></para>
  </section>

  <section>
    <?xxe-sn 2ahy8s1pw5c 7y?>

    <title><?xxe-sn 2ahy8s1pw5c 7z?>Requesting Modules:
    'modules_require'</title>

    <synopsis><?xxe-sn 2ahy8s1pw5c 80?>SYNTAX:
**modules_require**(//module-ref//, //request//)</synopsis>

    <itemizedlist>
      <?xxe-sn 2ahy8s1pw5c 81?>

      <listitem>
        <?xxe-sn 2ahy8s1pw5c 82?>

        <para><?xxe-sn 2ahy8s1pw5c 83?><emphasis><?xxe-sn 2ahy8s1pw5c 84?>module-ref</emphasis>
        module's path</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ahy8s1pw5c 85?>

        <para><?xxe-sn 2ahy8s1pw5c 86?><emphasis><?xxe-sn 2ahy8s1pw5c 87?>request</emphasis>
        expressed by annotation</para>
      </listitem>
    </itemizedlist>

    <para><?xxe-sn 2ahy8s1pw5c 88?>Module can request other modules necessary
    for correct work. Declared requests can be processed to find a
    resolution.</para>

    <para><?xxe-sn 2ahy8s1pw5c 89?>Example:</para>

    <programlisting xml:id="ReqMod_1"><?xxe-sn 2ahy8s1pw5c 8a?>name="tests/modules.cpp: Modules_API.Doc_ReqMod_1"
module 
{
  require(logger).
}</programlisting>

    <para><?xxe-sn 2ahy8s1pw5c 8b?>Produced declaration: <code
    xml:id="Output_ReqMod_1"><?xxe-sn 2ahy8s1pw5c 8c?>modules_require("/path/to/module", logger)</code></para>
  </section>

  <section>
    <?xxe-sn 2ahy8s1pw5c 8d?>

    <title><?xxe-sn 2ahy8s1pw5c 8e?>Modules Resolution:
    'modules_resolution'</title>

    <synopsis><?xxe-sn 2ahy8s1pw5c 8f?>SYNTAX:
**modules_resolution**(//request//, //module-resolved-ref//)                         (1)
**modules_resolution**(//request//, //module-resolved-ref//, //module-context-ref//) (2)
</synopsis>

    <itemizedlist>
      <?xxe-sn 2ahy8s1pw5c 8g?>

      <listitem>
        <?xxe-sn 2ahy8s1pw5c 8h?>

        <para><?xxe-sn 2ahy8s1pw5c 8i?><emphasis><?xxe-sn 2ahy8s1pw5c 8j?>request</emphasis>
        expressed by annotation</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ahy8s1pw5c 8k?>

        <para><?xxe-sn 2ahy8s1pw5c 8l?><emphasis><?xxe-sn 2ahy8s1pw5c 8m?>module-resolved-ref</emphasis>
        resolved module's path</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ahy8s1pw5c 8n?>

        <para><?xxe-sn 2ahy8s1pw5c 8o?><emphasis><?xxe-sn 2ahy8s1pw5c 8p?>module-context-ref</emphasis>
        context module's path</para>
      </listitem>
    </itemizedlist>

    <para><?xxe-sn 2ahy8s1pw5c 8q?>Xreate uses the data table to find
    correspondent modules for each request.</para>

    <para><?xxe-sn 2ahy8s1pw5c 8r?>Form (1) assigns resolved module to a
    request and assumes that assignment is valid in all cases, i.e. whenever
    compiler encounters request it loads associated module.</para>

    <para><?xxe-sn 2ahy8s1pw5c 8s?>Form (2) assigns resolution valid only in a
    specific context. Compiler uses particular resolution only for requests
    that came from a module specified in a context. In other words, form (2)
    allows to resolve the same request differently for different modules
    depending on resolution strategy, thus implementing <emphasis><?xxe-sn 2ahy8s1pw5c 8t?>polymorphism
    on module level</emphasis>.</para>
  </section>

  <section>
    <?xxe-sn 2ahy8s1pw5c 8u?>

    <title><?xxe-sn 2ahy8s1pw5c 8v?>See Also</title>

    <para><?xxe-sn 2ahy8s1pw5c 8w?>Syntax: <link
    xlink:href="/d/syntax/modules/"><?xxe-sn 2ahy8s1pw5c 8x?>Modules</link></para>
  </section>
</chapter>
