modules.xml
No OneTemporary

File Metadata

Created
Fri, Nov 20, 6:19 AM

modules.xml

<?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 26n42fz1reo 21?>
<title><?xxe-sn 26n42fz1reo 22?>Modules</title>
<para><?xxe-sn 26n42fz1reo 23?>Xreate offers <emphasis><?xxe-sn 26n42fz1reo 24?>modules</emphasis>
as a way to organize and reuse source code. For simplicity, it's implemented
as one file—one module.</para>
<para><?xxe-sn 26n42fz1reo 25?>Modules often require prior compilation of
other modules for correct work. It leads to a problem of a
<emphasis><?xxe-sn 26n42fz1reo 26?>resolution</emphasis> where required
module is located. Especially since modern software products usually have
complicated and volatile file structure depending on exact configuration and
platform to build. Common practice is to rely on build configuration tools
to provide exact path for each module.</para>
<para><?xxe-sn 26n42fz1reo 27?>For this reason Xreate interferes as little
as possible with resolution. Language does not support for module to
directly specify any path be it relative or absolute of other required
modules. Also compiler does not search modules in some predefined list of
directories and does not assume anything about project's file structure. It
expects resolution information already fully defined before
compilation.</para>
<para><?xxe-sn 26n42fz1reo 28?>However compiler has optional built-in
functionality to facilitate resolution. It is the very kind of problems the
transcend level suited excellently for. It is modeled as <emphasis><?xxe-sn 26n42fz1reo 29?>supply
and demand</emphasis> approach and lets modules to declare what they
<emphasis><?xxe-sn 26n42fz1reo 2a?>provide</emphasis> and what
<emphasis><?xxe-sn 26n42fz1reo 2b?>require</emphasis> expressed by
annotations. Compiler then tries to satisfy requirements and find a match.
Alternatively, external tools always can be used.</para>
<section>
<?xxe-sn 26n42fz1reo 2c?>
<title><?xxe-sn 26n42fz1reo 2d?>Module Headers</title>
<synopsis><?xxe-sn 26n42fz1reo 2e?>SYNTAX:
**module** [:: //annotations-list// ] (Full form)
{
//module-statement//...
}</synopsis>
<synopsis><?xxe-sn 26n42fz1reo 2f?>**module** :: //annotations-list// . (Simplified form)</synopsis>
<synopsis><?xxe-sn 26n42fz1reo 2g?>//module-statement// ::=
| **require** ( //annotation// ). (1)
| **discover** ( //path// ). (2)
| **controller** (//path//). (3)</synopsis>
<itemizedlist>
<?xxe-sn 26n42fz1reo 2h?>
<listitem>
<?xxe-sn 26n42fz1reo 2i?>
<para><?xxe-sn 26n42fz1reo 2j?><code><?xxe-sn 26n42fz1reo 2k?>annotations-list</code>
List of annotations delimited by semicolon</para>
</listitem>
<listitem>
<?xxe-sn 26n42fz1reo 2l?>
<para><?xxe-sn 26n42fz1reo 2m?><code><?xxe-sn 26n42fz1reo 2n?>annotation</code>
Any valid transcend expression</para>
</listitem>
<listitem>
<?xxe-sn 26n42fz1reo 2o?>
<para><?xxe-sn 26n42fz1reo 2p?><code><?xxe-sn 26n42fz1reo 2q?>path</code>
Absolute or relative path to controller</para>
</listitem>
</itemizedlist>
<para><?xxe-sn 26n42fz1reo 2r?>Xreate recognizes number of module
management statements. Those statements should be located in specific
section <code><?xxe-sn 26n42fz1reo 2s?>module {...}</code> of a source
code which is called <emphasis><?xxe-sn 26n42fz1reo 2t?>module
header</emphasis>. Module can have several headers. All headers gathered
from a whole file are combined into one before actual processing.</para>
<note>
<?xxe-sn 26n42fz1reo 2u?>
<para><?xxe-sn 26n42fz1reo 2v?>Modules processing happens before
compilation. It means any data produced in course of compilation is
inaccessible at this stage</para>
</note>
</section>
<section>
<?xxe-sn 26n42fz1reo 2w?>
<title><?xxe-sn 26n42fz1reo 2x?>Requesting Modules</title>
<para><?xxe-sn 26n42fz1reo 2y?>Statement <code><?xxe-sn 26n42fz1reo 2z?>require(..)</code>
expresses which modules are required for correct compilation.</para>
<programlisting xml:id="Requesting_Modules_1"><?xxe-sn 26n42fz1reo 30?>name="tests/modules.cpp: Modules.Doc_Requesting_Modules_1"
module {
require(logger).
}</programlisting>
<para><?xxe-sn 26n42fz1reo 31?>In this example module in question requires
some other module that <emphasis><?xxe-sn 26n42fz1reo 32?>provides</emphasis>
feature called <code><?xxe-sn 26n42fz1reo 33?>logger</code>. There is no
way to specify direct external module location. Instead, module expresses
requirement in abstract form as propositional expression which is later
used by resolution to find exact match.</para>
<programlisting xml:id="Requesting_Modules_2"><?xxe-sn 26n42fz1reo 34?>name="tests/modules.cpp: Modules.Doc_Requesting_Modules_2"
module{require(stringslib).}
processString = function(a:: string):: string
{
someStrFunc(a)
}
module{require(mathlib).}
processNumber = function(a:: num):: num
{
someMathFunc(a)
}</programlisting>
<para><?xxe-sn 26n42fz1reo 35?>Example above demonstrates using several
headers in one file. It's particularly useful if developer finds it
convenient to put requirements near the actual code that uses it. This way
it can be easily spotted when requirements are no more needed. After all,
code locality improves readability.</para>
</section>
<section>
<?xxe-sn 26n42fz1reo 36?>
<title><?xxe-sn 26n42fz1reo 37?>Module Annotations</title>
<para><?xxe-sn 26n42fz1reo 38?>Module can declare additional information
for various uses. This is expressed by annotations located in the header.
They are called module annotations. For instance, module annotations can
be used by module resolution to find modules that satisfy requirements of
others.</para>
<programlisting xml:id="ModuleAnnotations_1"><?xxe-sn 26n42fz1reo 39?>name="tests/modules.cpp: Modules.Doc_ModuleAnnotations_1"
module:: status(obsolete).</programlisting>
<para><?xxe-sn 26n42fz1reo 3a?>The example shows module that declares its
status. It can be used by resolution to choose most appropriate module out
of number of candidates. One way to view annotations used by resolution is
to treat them as something that module <emphasis><?xxe-sn 26n42fz1reo 3b?>provides</emphasis>.</para>
<note>
<?xxe-sn 26n42fz1reo 3c?>
<para><?xxe-sn 26n42fz1reo 3d?>There are no predefined module
annotations and developer can put arbitrary information there.</para>
</note>
</section>
<section>
<?xxe-sn 26n42fz1reo 3e?>
<title><?xxe-sn 26n42fz1reo 3f?>Modules Resolution</title>
<para><?xxe-sn 26n42fz1reo 3g?>Modules resolution is a process to find
exact modules locations that match requests. Compiler does not search
modules in predefined directories and does not assume anything about
project's file structure. In order to allow developer to determine it
themselves the compiler refers to two transcend tables</para>
<synopsis><?xxe-sn 26n42fz1reo 3h?>SYNTAX:
**modules_resolution**(//request//, //module-resolved//). (1)
**modules_resolution**(//request//, //module-resolved//, //module-context//). (2)</synopsis>
<itemizedlist>
<?xxe-sn 26n42fz1reo 3i?>
<listitem>
<?xxe-sn 26n42fz1reo 3j?>
<para><?xxe-sn 26n42fz1reo 3k?><emphasis><?xxe-sn 26n42fz1reo 3l?>request</emphasis>
annotation used in statement <code><?xxe-sn 26n42fz1reo 3m?>request(...)</code></para>
</listitem>
<listitem>
<?xxe-sn 26n42fz1reo 3n?>
<para><?xxe-sn 26n42fz1reo 3o?><emphasis><?xxe-sn 26n42fz1reo 3p?>module-resolved</emphasis>
Path or identifier of a module that matches request</para>
</listitem>
<listitem>
<?xxe-sn 26n42fz1reo 3q?>
<para><?xxe-sn 26n42fz1reo 3r?><emphasis><?xxe-sn 26n42fz1reo 3s?>module-context</emphasis>
Path or identifier of a module that requires other module</para>
</listitem>
</itemizedlist>
<para><?xxe-sn 26n42fz1reo 3t?>These tables contain resolved modules for
all possible requests. Form (1) contains requests that should always be
resolved to the same module. Form (2) contains such requests for which
resolution depends on requesting module <emphasis><?xxe-sn 26n42fz1reo 3u?>module-context</emphasis>.</para>
<programlisting xml:id="ModulesResolution_1"><?xxe-sn 26n42fz1reo 3v?>name="tests/modules.cpp: Modules.Doc_ModulesResolution_1"
modules_resolution(numlib, "/path/to/numlib").
modules_resolution(strings, "/path/to/ansi-lib", "moduleA").
modules_resolution(strings, "/path/to/utf8-lib", "moduleB"). </programlisting>
<para><?xxe-sn 26n42fz1reo 3w?>For the example above the compiler would
always resolve path to numerical lib(<code><?xxe-sn 26n42fz1reo 3x?>numlib</code>)
as "/path/to/numlib" (line 1). However <code><?xxe-sn 26n42fz1reo 3y?>strings</code>
library would be resolved as "/path/to/ansi-lib" if requested in
<code><?xxe-sn 26n42fz1reo 3z?>moduleA</code>(line 2) and as
"/path/to/utf8-lib" if requested in <code><?xxe-sn 26n42fz1reo 40?>moduleB</code>(line
3).</para>
<para><?xxe-sn 26n42fz1reo 41?>When compiler encounters module request it
looks up table <code><?xxe-sn 26n42fz1reo 42?>modules_resolution</code>
(first or second form) to find path of the requested module. Tables can be
populated by any means be it either transcend reasoning or external
tools.</para>
<note>
<?xxe-sn 26n42fz1reo 43?>
<para><?xxe-sn 26n42fz1reo 44?>There is no defined order or priority or
fall back behavior while looking into tables. If the same request occurs
in both tables they are considered to be ill-formed</para>
</note>
</section>
<section>
<?xxe-sn 26n42fz1reo 45?>
<title><?xxe-sn 26n42fz1reo 46?>Advanced Modules Resolution</title>
<para><?xxe-sn 26n42fz1reo 47?>Xreate provide additional layer, optional
helper to simplify modules management. It introduces two more built-in
statements that can be used in module header: <emphasis><?xxe-sn 26n42fz1reo 48?>Discover</emphasis>
statement and <emphasis><?xxe-sn 26n42fz1reo 49?>Controller</emphasis>
Statement.</para>
<itemizedlist>
<?xxe-sn 26n42fz1reo 4a?>
<listitem>
<?xxe-sn 26n42fz1reo 4b?>
<para><?xxe-sn 26n42fz1reo 4c?><emphasis><?xxe-sn 26n42fz1reo 4d?>Discover
Statement</emphasis> has the form <code><?xxe-sn 26n42fz1reo 4e?>discover
(<emphasis><?xxe-sn 26n42fz1reo 4f?>path</emphasis>)</code>.It allows
to specify directory where compiler would recursively search for all
xreate files and extract module header annotations. It gathers info
about all found source files.</para>
</listitem>
<listitem>
<?xxe-sn 26n42fz1reo 4g?>
<para><?xxe-sn 26n42fz1reo 4h?><emphasis><?xxe-sn 26n42fz1reo 4i?>Controller
Statement</emphasis> has the form <code><?xxe-sn 26n42fz1reo 4j?>controller
(<emphasis><?xxe-sn 26n42fz1reo 4k?>path</emphasis>)</code> and
specifies path to modules resolution controller. Controller is a file
that contains transcend rules in order to process data gathered by
discovery and populate resolution tables as its result of work.</para>
</listitem>
</itemizedlist>
<para><?xxe-sn 26n42fz1reo 4l?>Example below shows 3 modules:</para>
<programlisting xml:id="AdvModRes_1"><?xxe-sn 26n42fz1reo 4m?>name="tests/modules.cpp: Modules.Doc_AdvModRes_1"
//First Module
module::
name(testA);
provide(superService);
status(needToTestEvenMore).
//Second Module
module::
name(testB);
provide(superService);
status(needToTest).
//Third Module
module {
require(superService).
discover("/modules/path/").
controller("/path/to/controller").
}</programlisting>
<para><?xxe-sn 26n42fz1reo 4n?>Two modules offer the same feature
<code><?xxe-sn 26n42fz1reo 4o?>provide(superSerivce)</code>. Third module
requires it and specifies directory where to look up for needed files.
Controller's task is to populate resolution table if needed module is
found and choose appropriate candidate, if more than one module offer this
service.</para>
<para><?xxe-sn 26n42fz1reo 4p?>One way to decide what to choose in this
example is to look at status of both modules. Let score be assigned to
each possible status. Let's say <code><?xxe-sn 26n42fz1reo 4q?>0</code>
for <code><?xxe-sn 26n42fz1reo 4r?>status(needToTestEvenMore)</code>,
<code><?xxe-sn 26n42fz1reo 4s?>1</code> for <code><?xxe-sn 26n42fz1reo 4t?>status(needToTest)</code>.
Then controller would proceed with the best scoring module,
<code><?xxe-sn 26n42fz1reo 4u?>Second Module</code> in this case.</para>
</section>
<section>
<?xxe-sn 26n42fz1reo 4v?>
<title><?xxe-sn 26n42fz1reo 4w?>See Also</title>
<para><?xxe-sn 26n42fz1reo 4x?>Transcend: <link
xlink:href="/w/transcend/modules-api"><?xxe-sn 26n42fz1reo 4y?>Modules
API</link></para>
</section>
</chapter>
<?xxe-revisions
#2 2019-02-20T12:15:04Z pgess
#1 2018-12-12T21:49:18Z pgess
1sPEAAAB41YAZ+FRAAE8JCBzoWsThB8jBkOHeGOSBwEBUwgzKCMVEwdTI3MVgwdDlFkzGkMRUxtj
OpMLMwaTG1MxEwpjDSMEMyAziUUAoiauc4RgiDKDQJJIMacPQuWPPZUMGA8ZI0MyHaIvCpZrSB4=
?>

Event Timeline