Page Menu
Home
Xreate
Search
Configure Global Search
Log In
Docs
Questions
Repository
Issues
Patches
Internal API
Files
F5336459
modules.xml
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Subscribers
None
File Metadata
Details
File Info
Storage
Attached
Created
Sat, Nov 21, 6:26 AM
Size
10 KB
Mime Type
text/xml
Expires
Mon, Nov 23, 6:26 AM (1 d, 1 h)
Engine
blob
Format
Raw Data
Handle
316576
Attached To
rXR Xreate
modules.xml
View Options
<?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">
<title>Modules</title>
<para>Xreate offers <emphasis>modules</emphasis> as a way to organize and
reuse source code. For simplicity, it's implemented as one file—one
module.</para>
<para>Modules often require prior compilation of other modules for correct
work. It leads to a problem of a <emphasis>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>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>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>supply and demand</emphasis>
approach and lets modules to declare what they <emphasis>provide</emphasis>
and what <emphasis>require</emphasis> expressed by annotations. Compiler
then tries to satisfy requirements and find a match. Alternatively, external
tools always can be used.</para>
<section>
<title>Module Headers</title>
<programlisting>SYNTAX:
module [:: //annotations-list// ] (Full form)
{
//module-statement//...
}
module :: //annotations-list// . (Simplified form)
module-statement ::=
| require ( //annotation// ). (1)
| discover ( //path// ). (2)
| controller (//path//). (3)</programlisting>
<itemizedlist>
<listitem>
<para><code>annotations-list</code> List of annotations delimited by
semicolon</para>
</listitem>
<listitem>
<para><code>annotation</code> Any valid transcend expression</para>
</listitem>
<listitem>
<para><code>path</code> Absolute or relative path to controller</para>
</listitem>
</itemizedlist>
<para>Xreate recognizes number of module management statements. Those
statements should be located in specific section <code>module {...}</code>
of a source code which is called <emphasis>module header</emphasis>.
Module can have several headers. All headers gathered from a whole file
are combined into one before actual processing.</para>
<note>
<para>Modules processing happens before compilation. It means any data
produced in course of compilation is inaccessible at this stage</para>
</note>
</section>
<section>
<title>Requesting Modules</title>
<para>Statement <code>require(..)</code> expresses which modules are
required for correct compilation.</para>
<programlisting>module {
require(logger).
}</programlisting>
<para>In this example module in question requires some other module that
<emphasis>provides</emphasis> feature called <code>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>module{require(stringslib).}
processString = function(a:: string):: string
{
someStrFunc(a)
}
module{require(mathlib).}
processNumber = function(a:: num):: num
{
someMathFunc(a)
}</programlisting>
<para>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>
<title>Module Annotations</title>
<para>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>module:: status(obsolete).</programlisting>
<para>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>provides</emphasis>.</para>
<note>
<para>There are no predefined module annotations and developer can put
arbitrary information there. </para>
</note>
</section>
<section>
<title>Modules Resolution</title>
<para>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>
<programlisting>SYNTAX:
modules_resolution(//request//, //module-resolved//). (1)
modules_resolution(//request//, //module-resolved//, //module-context//). (2)</programlisting>
<itemizedlist>
<listitem>
<para><emphasis>request</emphasis> annotation used in statement
<code>request(...)</code></para>
</listitem>
<listitem>
<para><emphasis>module-resolved</emphasis> Path or identifier of a
module that matches request</para>
</listitem>
<listitem>
<para><emphasis>module-context</emphasis> Path or identifier of a
module that requires other module</para>
</listitem>
</itemizedlist>
<para>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>module-context</emphasis>. </para>
<programlisting> modules_resolution(numlib, "/path/to/numlib").
modules_resolution(strings, "/path/to/ansi-lib", "moduleA").
modules_resolution(strings, "/path/to/utf8-lib", "moduleB"). </programlisting>
<para>For the example above the compiler would always resolve path to
numerical lib(<code>numlib</code>) as "/path/to/numlib" (line 1). However
<code>strings</code> library would be resolved as "/path/to/ansi-lib" if
requested in <code>moduleA</code>(line 2) and as "/path/to/utf8-lib" if
requested in <code>moduleB</code>(line 3). </para>
<para>When compiler encounters module request it looks up table
<code>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>
<para>There is no defined order or priority or fallback behavior while
looking into tables. If the same request occurs in both tables they are
considered to be ill-formed</para>
</note>
</section>
<section>
<title>Advanced Modules Resolution</title>
<para>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>Discover</emphasis> statement and
<emphasis>Controller</emphasis> Statement.</para>
<itemizedlist>
<listitem>
<para><emphasis>Discover Statement</emphasis> has the form
<code>discover (<emphasis>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>
<para><emphasis>Controller Statement</emphasis> has the form
<code>controller (<emphasis>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>Example below shows 3 modules:</para>
<programlisting>//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>Two modules offer the same feature
<code>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>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>0</code> for <code>status(needToTestEvenMore)</code>,
<code>1</code> for <code>status(needToTest)</code>. Then controller would
proceed with the best scoring module, <code>Second Module</code> in this
case.</para>
</section>
</chapter>
Event Timeline
Log In to Comment