Files F3999993

modules.xml
No OneTemporary
Actions

File Metadata

Created
Thu, Jul 9, 3:27 AM

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">
<?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's sake, it is
implemented as one file — one module, with one to one correspondence.</para>
<para><?xxe-sn 26n42fz1reo 25?>Modules often require prior compilation of
other modules for correct work. This leads to a problem of
<emphasis><?xxe-sn 26n42fz1reo 26?>resolution</emphasis> where the required
module is located, determine exact module's filename, especially as modern
software products tend to incorporate a complicated and volatile file
structure depending on configuration and platform to build. The common
practice is to rely on build configuration tools to provide exact path to
each module.</para>
<remark><?xxe-sn 26r2dlt35rk pu35zrt1abya?>Не вполне понимаю смысл фразы "a
resolution where the required module is located". Принятие решения о том,
где будет располагаться какой модуль? Тогда может лучше будет так: "This
leads to a problem of resolution where to locate which module". Как в этом
примере: "Therefore tools for choosing where to locate which types of
production like this method will become increasingly useful". Или выяснение
того, где находится нужный модуль?</remark>
<para><?xxe-sn 26n42fz1reo 27?>For this reason Xreate interferes as little
as possible with the resolution. The language does not allow for a module to
specify a path directly, be it a relative or an absolute path in respect to
other required modules. Also the compiler does not search for modules in any
predefined list of directories, and does not assume anything about project's
file structure. It expects the resolution information to have been already
fully predefined before the start of the compilation process.</para>
<remark><?xxe-sn 26r2dlt35rk pu35zrt1abyb?>1. Если resolution - это процесс,
то перед словами обозначающими какой-либо процесс, как правило, артикли не
ставятся (исключение - если речь идет о каком-то конкретном процессе,
например, "Dune2: The building of a dynasty"). А неопределенный артикль
совершенно исключен в этом случае. 2. "The language does not support for a
module" - возможные варианты замены: "The language offers no instruments
allowing a module to...", "The language has no means allowing a module
to...". 3. "Does not search for modules in some..." - в вопросительных
предложениях и при отрицании употребляется местоимение "any" вместо
"some".</remark>
<para><?xxe-sn 26n42fz1reo 28?>However, the compiler features some optional
built-in functionality to facilitate resolution. It is the very type of a
problem the transcend level is excellently suited for. It is modeled after a
<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 they <emphasis><?xxe-sn 26n42fz1reo 2b?>require</emphasis>,
expressed by annotations. Compiler then tries to satisfy the requirements
and find a match. Alternatively, external tools can always 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 a number of module
management statements. Those statements should be located in a 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 single file are combined into one before actual processing.</para>
<note>
<?xxe-sn 26n42fz1reo 2u?>
<para><?xxe-sn 26n42fz1reo 2v?>Modules' processing happens before
compilation. This means that 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 a module in question
requires some other module that <emphasis><?xxe-sn 26n42fz1reo 32?>provides</emphasis>
a feature called <code><?xxe-sn 26n42fz1reo 33?>logger</code>. There is no
way to specify the direct location of the external module. Instead, the
"main" module expresses a requirement in an abstract form as a
propositional expression which is later used by the resolution to find the
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?>The above example demonstrates usage of
several headers in one file. It is particularly useful in situations where
a developer finds it convenient to place requirements beside the actual
code that uses them. This way one can easily spot the requirements that
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?>A module can declare an 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 other modules.</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 a module that declares
its status. It can be used by resolution to select the most appropriate
module out of a 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 developers can place 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 perform a
search of modules in any predefined directories, and it does not assume
anything about project's file structure. Compiler, in order to allow a
developer to determine it independently, refers to two transcend
tables:</para>
<remark><?xxe-sn 26r2dlt35rk pu35zrt1abyd?>Вот я и дошел до ответа что
такое resolution :) Оставляю предыдущие комменты для истории.</remark>
<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 regardless of where module is requested. Form
(2) contains such requests for which resolution depends on requester
<emphasis><?xxe-sn 26n42fz1reo 3u?>module-context</emphasis>. In other
words, difference between forms (1) and (2) is that form (2) takes into
account not only <emphasis><?xxe-sn 2be3ap8an7k 1?>what</emphasis>(parameter
<code><?xxe-sn 2be3ap8an7k 2?>request</code>) is requested but also
<emphasis><?xxe-sn 2be3ap8an7k 5?>where from</emphasis>(parameter
<code><?xxe-sn 2be3ap8an7k 4?>module-context</code>) it is
requested.</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?>In the above example, compiler would always
resolve a 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 a module request,
it looks up a <code><?xxe-sn 26n42fz1reo 42?>modules_resolution</code>
table (either the first or the second one) to find the path to the
requested module. Tables can be populated by any means, be it transcend
reasoning or any 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 provides an additional layer – an
optional helper, to simplify modules management. It introduces two more
built-in statements that can be used in the module's 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> is presented in the form <code><?xxe-sn 26n42fz1reo 4e?>discover
(<emphasis><?xxe-sn 26n42fz1reo 4f?>path</emphasis>)</code>. It allows
to specify a directory within which compiler would recursively search
for all Xreate files and extract module header annotations. It gathers
information 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> is presented in the form <code><?xxe-sn 26n42fz1reo 4j?>controller
(<emphasis><?xxe-sn 26n42fz1reo 4k?>path</emphasis>)</code> and
specifies a path to the modules' resolution controller. Controller is
a file that contains transcend rules in order to process data gathered
by discovery and populate resolution tables as a result of its
work.</para>
</listitem>
</itemizedlist>
<para><?xxe-sn 26n42fz1reo 4l?>The below example 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 of the modules offer the same feature
<code><?xxe-sn 26n42fz1reo 4o?>provide(superSerivce)</code>. The third
module requires it and specifies a directory in which to look for needed
files. The controller's task is to populate the resolution table if the
necessary module is found, and also to choose the 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 the status of both modules. Let a score be assigned
to each possible status, e.g. <code><?xxe-sn 26n42fz1reo 4q?>0</code> for
<code><?xxe-sn 26n42fz1reo 4r?>status(needToTestEvenMore)</code> and
<code><?xxe-sn 26n42fz1reo 4s?>1</code> for <code><?xxe-sn 26n42fz1reo 4t?>status(needToTest)</code>.
The controller would then proceed with 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="/d/transcend/modules-api/"><?xxe-sn 26n42fz1reo 4y?>Modules
API</link></para>
</section>
</chapter>
<?xxe-revisions
#5 2019-03-07T17:46:08Z pgess
#4 2019-03-07T17:15:17Z pgess
1sPEAAAB+GQAiBuBgFEAgQiED4J6LDmwvtC90YDRg9C60Ya0g7DRgLLRgyAoIri4Iikg0YPRh7Vy
Y6DQsYzQtb4s0LG70LjRhyKyuSK9s9C+0J7Qv9GMuCzRgbgggbXQvC4g0K2A0LbRgCy6hii+tbGL
j7AstLM/KWU/PiKyILggIqG+0Lmx0Yu60LLQs71mPz7QojIpMyl4b3V0cHOFFBMfryMKQzKxMwlT
BCMNUwRTBQEBUwQBA0MEAQgTBhMEAQFTB8hDBEMFEwUBATMEUwTjYwQBBlMFAQEzBDME2c2yYwUB
ATMoE4FKM4dgQ4xFsFOMLWMEM4svUywTKAEBMwYBAUMHMwRTBgECQwYTBFMFQwQzBAEDYwhTDxME
EwgBAWMHAQFTB74TBUMHMwQBBSMHAQFTBVMEsAECEw0jBVMEpCMEAQNjBQEEEwQBAoMEQwQBApMF
kwmDBGMXkwpzBYMHQwVjDSMFEwUBAmMOUwWDBMwzBgEBIwSTBRMEAQeDBWMFIwRDBXMFEwYTBAED
QwSTBXMEAQIzBIMEIwsBAUMFIwUjBgEBIwRDBTMGAQFzBJMTAQEzFyMEIwX4QwQTBa9jBnMFUwVT
BmMEQwRjBxMF4MgTCgEBgwaDBCMEMwVTBDMFAQJDCGMGgwewrwECEwxjKWObVjNJMwRDDVMhQx4T
MQEEMzpzBZMEQwZDBEMKMwQjBCMFoyMEIwS8kwQBAzMbEwQBARMKIwYBAyMIUw3NEwZjBOAzBGMF
MwyDBCMHIwRTBCMJEwqDBMBjEYMEMw1DBCMHIwQTBQECIwcBAVMEEw0zFhMHMwozG1ODNEMJYx0z
gQMzBmNdQxKDKAEFcwRjC2MGIwRDBCMEUwmTBgECMwSTBgECgydDiwEBAWOERDMFMwQBBBMGM411
AIUbn26Le4RZuAVgj05TjkWCNoc+rkeLMIoxJoxCiFKBMoo3gUCDeoQSaYYPQgEFhRk+hQ4LhhCB
bYdkryWMSow1jC+LM4l+iTuDNIRfr3+BG4tkgSKFDyOIV4NllSOTfJlXk2aCSItuiVevCWSDYxUG
i3cxgW+LKLASi26LHcWvdMlUIplQDZldkmOHVYIJi2iIdxRZgQWFALE+4JRXM4MXgluBPceWV5Uy
gQ6wrohwSYErrS6CArJ2sxYTBIE3iR2BbWyzFYIsi1azWifeiRyyQi1LI5RShSVYi3kgWQeEYVwv
AaxqxbRZc452mXKFLJt+f5EIlkNtiXWDWpk3jCGLNYJZgRbSNKBqjB6hPqITh3jhiD2LEopMolWj
Tn5qizeCXIEIgxqIKmReoRmjSCs0lEcpgjeCPiaBGUeBVKRVlkjVATGOdZhvg2STbyiSBJcFgjeD
W4MqgQpe/uyEXYMUrDCKVg+GYFStLlR1gkaLAo9djQq/ZoRT
#3 2018-12-16T14:37:25Z Acer2
1sPEAAABgYBRAEH+OwABJBYgc7ELE4obIwZDiCZjlyABAVMIMygjFRMHUyODFXMHQ5YwM4wNALFG
xDiKXIhgg2aXYTG8K0LDKz2WYg==
#2 2018-12-14T15:41:37Z Acer2
1sPEAAAB/jsAghD8cQANgRdlLGF1bEV1cCdzIHNheXPMUBMLQx9TmFZTMGMSUwxDBQEBYxAzYEMG
Q0ITClMEY4F8EwRTcTMVEwZDBVMFY21DgTtzBJMmU1tjCIMIYwtDgQ0BAWMEIwWnEwVDFVMrMwQB
AWMHMwZDBlODRYNgQyUjEFMIAQJTExMKQxeTFBMGMxAjBRMFU4ErQxxTKVMFAQZjcRMeQ1EjDFMH
Yw1DBFMTgx4zgjIAhxuZf6wupzyZB59kIgwRjhts0EB7UJlTggxykTMd0lgRdNNWgXHDN6mBYX12
gR/FGIgKn1iBQawpk3gIhw8UqWSKHYJlQe9kIYq/HyGOII5HJ4EvHhYv3XaBEoskOWiaTg32NA==
#1 2018-12-12T21:49:18Z pgess
1sPEAAAB/HIAhU7hUQAogwuCEyfigJRJdC4gRXNpbmN1c3VDTGt3aG9JdCdmdXMgbmVhaXR3aXNl
bChzhRgBARMZAQNDFBMcU04BAjMXQyNDIFMHYxMBA0MKAQQjBVMW2jMFIwQzMTMGMyUBAVNNQwRD
FYMcQ0wBAWMdIwYzBWMHEwpjBBMEYwZjDTMIQwmTB0MQgwkzEFMPUx9jBjNDUxdjDhMIMxMjCTMm
IwoTBDNJ3xMGEwQjBjMKQwZDB0MMUxQTIzOBEVM3YxljIUM9UwdTBGOJNkNOIwZTgV0BAzOBBkMo
AQITCFOECzNsYwdDUyMGYxATBlMGQwiDBjMLUxBjEDNDQxVTgjEjCGMGQw9jBFMfAQEzFwEBQyMB
AVMJEwQBBWMGUxYBAlMHEwQzBCMGQwv8MwRzDmOBUxMGYw5DcIMGMw5TdEOBL1NBEwUjBGMdU4Ia
kwczCCMEIwRDgWszMhMHgwgBAVMEUwljSjMRYxpDBM0TDTMekwljHzOIb2MGUyJjJ1OCKBMEYwQz
CVMFgw1jFUNsU4IWYziDBjMJMwxDBmM7AQFDCVMHEwUzCWMFMwdDNlMHYwgzFhMOQwozG2OZWQCF
Gh6DdYILUpUjOJIzKxaNdBAFiiaoNzCBHTEqpTkO9YU0iACTGLJogQiRJIEGinIJCBCxHesoHR2H
eCKDUSZHJJJBmW2MfYgIggCZVEODYI5tiCSgfKtKjhUVCQeEID2BFqI/USVBPQeJOq0qVoFhgQeZ
WjmEDYIxdZlXbYkDk0sTCRkNExJHhWy0NoI1Dm4WISuVMIUhoGBAgmKEX7k3mBZco0GXNucjg2SB
WxEJm1KBBnuBMY5IjGROH+SgJIhHiQuJTYFskiQJgWUclDO2cBOsG2ubfilThR2BRqcOkQSJHYNH
hQagLKxdizP+nxAXbYMNCYNoSoFeDk0Non6RaaVXkEutJgSuCD+gFYILjEtN
?>

Event Timeline

Email: pr.h7@xreate.org · 2019 Xreate.org · Powered by Phabricator