diff --git a/config/default.json b/config/default.json index a4c45db..9ce4b3c 100644 --- a/config/default.json +++ b/config/default.json @@ -1,74 +1,74 @@ { "containers": { "id": { "implementations": "containers_impl", "linkedlist": "linkedlist" }, "impl": { "solid": "solid", "onthefly": "onthefly" } }, "logging": { "id": "logging" }, "function-entry": "entry", "transcend": { "bindings" : { "variable": "bind", "function": "bind_func", "scope": "bind_scope", "function_demand" : "bind_function_demand", "scope_decision": "bind_scope_decision" }, "context" : { "decisions":{ "dependent": "resolution_dependency" } }, "nonevalue": "nonevalue", "ret": { "symbol": "retv", "tag": "ret" } }, "tests": { "template": "troubleshooting", "templates": { - "troubleshooting":"*.Doc_*:-Latex.*", + "troubleshooting":"-Latex.*:*.Doc_*", "documentation":"Modules.Doc_*:Modules_API.Doc_*:Interpretation.Doc_*:AST.Doc_*:Loop.Doc_*:LateReasoning.Doc_*:Latex.Doc_*:Polymorphs.Doc_*:Transcend.Doc_*:ASTCorrespondence.Doc_*:Virtualization.Doc_*:Exploitation.Doc_*:Communication.Doc_*:Introduction.*", "default": "*", "ast": "AST.*", "effects": "Effects.*", "basic": "Attachments.*", "compilation": "Compilation.*", "communication": "Communication.*", "cfa": "CFA.*", "containers": "Containers.*", "dfa": "DFA.*", "diagnostic": "Diagnostic.*", "dsl": "Association.*:Interpretation.*", "exploitation": "Exploitation.*", "ExpressionSerializer": "ExpressionSerializer.*", "externc": "InterfaceExternC.*", "loops": "Loop.*", "latereasoning": "LateReasoning.*", "latex": "Latex.*", "modules": "Modules.*", "polymorphs": "Polymorphs.*", "intrinsic-query": "Types.SlaveTypes*:Association.TypedQuery*", "types": "Types.*", "virtualization": "Virtualization.*", "vendorsAPI/clang": "ClangAPI.*", "vendorsAPI/xml2": "libxml2.*" } } } diff --git a/documentation/Concepts/polymorphism.xml b/documentation/Concepts/polymorphism.xml index e757c58..ccc0819 100644 --- a/documentation/Concepts/polymorphism.xml +++ b/documentation/Concepts/polymorphism.xml @@ -1,229 +1,272 @@ <?xxe-sn 26n42fz1reo 2?>Polymorphism + See function + specializations for syntax. + Polymorphism - is an umbrella term to denote number of techniques across different - programing paradigms. They all share the same intention to provide ability - easily recombine software components in a different way with as little as - possible manual work on developer's side. It serves two major goals: - specialization, when software, - initially designed to support wide range of use cases, is configured for - concrete particular case and extension - - adapting software to an environment and conditions it was not specifically + is an umbrella term to denote a number of techniques across different + programing paradigms. They all share the same intention to provide the + ability to easily recombine software components in a different way with as + little manual work on developer's side as possible. It serves two major + goals: specialization, which + purports that software initially designed to support a wide range of use + cases is being configured for a specific case, and extension + – adapting software to an environment and conditions it was not specifically designed for. - In course of software engineering evolution, + In course of software engineering evolution, a number of polymorphism techniques was proposed and experimented with, all - suited for different use-cases. Xreate presents generalized and elegant - approach that exhaustively covers wide landscape of polymorphism + suited for different use-cases. Xreate presents a generalized and elegant + approach that exhaustively covers the wide landscape of polymorphism variations. Polymorphism in Xreate can be applied on two levels: Functions - level. Function in Xreate can have a multiple - specializations and + level. Function in Xreate can have multiple + specializations, and polymorphism is compiler's ability to decide which exactly specialization to use depending on various factors Modules level. Multiple modules can provide the same service for users. Modules Resolution is a process to decide which exactly module to - use + use. + + По поводу Modules Resolution: + кажется в предыдущем файле я внес несколько исправлений, добавив + апостроф после Modules. По грамматическим правилам это верно, но если + Modules Resolution это устоявшийся термин в твоей документации, то + возможно лучше без апострофа.
<?xxe-sn 26n42fz1reo j?>Function Level Polymorphism Basic idea is to allow developer to define several functions with the same name or, in other words, several specializations. Caller code - then invokes necessary function by its shared name but can't directly - specify particular specialization. Exact specialization to be invoked is - decided later by decision process called polymorphism + then invokes the necessary function by its shared name, but cannot specify + a particular specialization directly. The exact specialization to be + invoked is decided later by a decision process called polymorphism resolution carried out by Transcend. This indirect invocation approach gives enough flexibility to use or replace different specializations depending on various conditions during compile time as well as at runtime. - Please refer to syntax - for details about function specializations. Each specialization must have - unique guard(among all + Each specialization must have unique + guard (among all specializations with the same name) to be discernible from others. To - summarize, function invocation is a two layered process, in which client - code specifies callee function's shared name, and polymorphism resolution - specifies specialization guard if needed. - - For an example, assume that we develop - program to operate under specified time constraints. To model - implementation suitable for real time environment, one specialization of - crucialOperation is defined with - env(realtime) guard i.e. satisfies - some fixed execution time constraints. Caller main - specifies only function name crucialOperation - thus delegating decision on guard to a polymorphism resolution done - elsewhere, based on environment's constraints the code is executed - in. + summarize, function invocation is a two-layered process, where the client + code specifies the callee function's shared name, while polymorphism + resolution specifies specialization guard, if needed. + + For example, let us assume that we have been + developing a software program to operate under specified time constraints. + To model an implementation suitable for real time environment, one + specialization of crucialOperation is + defined with env(realtime) guard, + i.e. it satisfies some fixed execution time constraints. Caller + main specifies just a function name + crucialOperation thus delegating the + decision in respect of guard to polymorphism resolution done elsewhere, + based on the environment's constraints the code is executed in. name="tests/polymorph.cpp: Polymorphs.Doc_FnLvlPoly_1" guard:: env(realtime) { crucialOperation = function:: int { 0 } } main = function:: int; entry { crucialOperation() }
<?xxe-sn 26n42fz1reo x?>Polymorphism Resolution SYNTAX: **dfa_callguard**(//call-site-ref//, //guard//) call-site-ref reference to a call site in AST guard resolved function specialization guard When compiler encounters function - invocation that has several specialization it refers to the table + invocation that has several specializations it refers to the table dfa_callguard to find out which - specialization to call. It must have entry with appropriate + specialization to call. It must have an entry with appropriate guard for every invocation site call-site-ref of a polymorphic function. Polymorphism resolution is a process of filling out - dfa_callguard for a compiler based + dfa_callguard for the compiler based on custom Transcend rules reflecting one or another polymorphism strategy.
<?xxe-sn 26n42fz1reo 1c?>Late Polymorphism Late Polymorphism is an extension to allow polymorphism resolution to be based on data known only at runtime, i.e. resolve function specializations dynamically. The Idea is to use Late Transcend to access runtime data. See Late Transcend for details. Example below demonstrates test invoking polymorphic function compute: name="tests/polymorph.cpp: Polymorphs.Doc_LatePoly_1" Strategy = type variant {fast, precise}. guard:: fast { compute = function:: int {0} } guard:: precise { compute = function:: int {1} } test = function(s:: Strategy; alias(strategy)):: int; entry { switch late (s):: int { compute():: int; guardalias(strategy) } } Function compute has two specializations, fast and precise. We see that test gets parameter s that dictates exact - strategy to use. Clearly, resolution should work dynamically to cope with - cases like this, for value of parameter s - not only is unknown at compile time, but it can change with each + strategy to use. Clearly, resolution should work dynamically to deal with + cases like this, for not only the value of the parameter s + is unknown at the compile time, but also it can change with each test execution. - Operation Switch Late is compiled into - several branches, two in this case, each branch executing appropriate - compute specialization. Correct - branch executed depending on current s + Operation switch late + is compiled into several branches, two in this case, each branch executing + appropriate compute specialization. + The correct branch is executed depending on the current s value. Custom annotations alias(Alias) - and guardalias(Alias) used to assign - an alias in order to specify which parameter to use for as basis for - resolution + and guardalias(Alias) are used to + assign an alias in order to specify which parameter to use as basis for + resolution.
<?xxe-sn 26n42fz1reo 1x?>Auto Expansion of Late Parameters - In previous example, switch late operation - was used to facilitate calling of polymorphic function with late - polymorphism resolution. It's not that convenient to wrap each invocation - by switch late whenever there is need to call late polymorphic function. - Specifically to handle cases like this, compiler uses late parameter auto - expansion technique. + In the previous example, operation + switch late was used to facilitate + calling of a polymorphic function with late polymorphism resolution. It is + not that convenient to wrap each invocation using switch + late whenever we need to call a late polymorphic function. Compiler + uses the late parameter auto expansion technique in order to specifically + handle cases like this. If compiler discovers that late(dfa_callguard()) - entry exists for current invocation and it does not have enclosing switch - late already, compiler automatically generates different branches that - invoke relevant specializations and transfers control to a branch - depending on late parameter value. In other words invocation implicitly - wrapped into switch late instruction if needed. + entry exists for current invocation, and it does not have enclosing + switch late already, compiler + automatically generates different branches that invoke relevant + specializations and transfers control to a branch depending on the late + parameter's value. In other words, invocation is implicitly wrapped into + switch late if needed.
\ No newline at end of file diff --git a/documentation/Syntax/modules.xml b/documentation/Syntax/modules.xml index 649dfa8..6fee31f 100644 --- a/documentation/Syntax/modules.xml +++ b/documentation/Syntax/modules.xml @@ -1,335 +1,408 @@ <?xxe-sn 26n42fz1reo 22?>Modules Xreate offers modules - as a way to organize and reuse source code. For simplicity, it's implemented - as one file—one module. + 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. Modules often require prior compilation of - other modules for correct work. It leads to a problem of a - resolution 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. + other modules for correct work. This leads to a problem of + resolution 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. + + Не вполне понимаю смысл фразы "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". Или выяснение + того, где находится нужный модуль? 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. - - 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 supply - and demand approach and lets modules to declare what they - provide and what - require expressed by - annotations. Compiler then tries to satisfy requirements and find a match. - Alternatively, external tools always can be used. + 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. + + 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". + + 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 + supply and demand approach and + lets modules to declare what they provide + and what they require, + expressed by annotations. Compiler then tries to satisfy the requirements + and find a match. Alternatively, external tools can always be used.
<?xxe-sn 26n42fz1reo 2d?>Module Headers SYNTAX: **module** [:: //annotations-list// ] (Full form) { //module-statement//... } **module** :: //annotations-list// . (Simplified form) //module-statement// ::= | **require** ( //annotation// ). (1) | **discover** ( //path// ). (2) | **controller** (//path//). (3) annotations-list List of annotations delimited by semicolon annotation Any valid transcend expression path Absolute or relative path to controller - Xreate recognizes number of module - management statements. Those statements should be located in specific + Xreate recognizes a number of module + management statements. Those statements should be located in a specific section module {...} of a source code which is called module header. Module can have several headers. All headers gathered - from a whole file are combined into one before actual processing. + from a single file are combined into one before actual processing. - Modules processing happens before - compilation. It means any data produced in course of compilation is - inaccessible at this stage + Modules' processing happens before + compilation. This means that any data produced in course of compilation + is inaccessible at this stage
<?xxe-sn 26n42fz1reo 2x?>Requesting Modules Statement require(..) expresses which modules are required for correct compilation. name="tests/modules.cpp: Modules.Doc_Requesting_Modules_1" module { require(logger). } - In this example module in question requires - some other module that provides - feature called logger. 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. + In this example a module in question + requires some other module that provides + a feature called logger. 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. 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) } - 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. + 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.
<?xxe-sn 26n42fz1reo 37?>Module Annotations - 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. + 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. name="tests/modules.cpp: Modules.Doc_ModuleAnnotations_1" module:: status(obsolete). - 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 provides. + 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 provides. There are no predefined module - annotations and developer can put arbitrary information there. + annotations, and developers can place arbitrary information + there.
<?xxe-sn 26n42fz1reo 3f?>Modules Resolution 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 + 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: + + Вот я и дошел до ответа что + такое resolution :) Оставляю предыдущие комменты для истории. SYNTAX: **modules_resolution**(//request//, //module-resolved//). (1) **modules_resolution**(//request//, //module-resolved//, //module-context//). (2) request annotation used in statement request(...) module-resolved Path or identifier of a module that matches request module-context Path or identifier of a module that requires other module 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 module-context. + resolved to the same module regardless of where module is requested. Form + (2) contains such requests for which resolution depends on requester + module-context. In other + words, difference between forms (1) and (2) is that form (2) takes into + account not only what(parameter + request) is requested but also + where from(parameter + module-context) it is + requested. 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"). - For the example above the compiler would - always resolve path to numerical lib(numlib) - as "/path/to/numlib" (line 1). However strings + In the above example, compiler would always + resolve a path to numerical lib(numlib) + as "/path/to/numlib" (line 1). However, strings library would be resolved as "/path/to/ansi-lib" if requested in - moduleA(line 2) and as - "/path/to/utf8-lib" if requested in moduleB(line - 3). + moduleA (line 2) and as + "/path/to/utf8-lib" if requested in moduleB + (line 3). - When compiler encounters module request it - looks up table modules_resolution - (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. + When compiler encounters a module request, + it looks up a modules_resolution + 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. 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
- <?xxe-sn 26n42fz1reo 46?>Advanced Modules Resolution + <?xxe-sn 26n42fz1reo 46?>Advanced Modules' Resolution - Xreate provide additional layer, optional - helper to simplify modules management. It introduces two more built-in - statements that can be used in module header: Discover - statement and Controller - Statement. + 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: + Discover Statement and + Controller Statement. Discover - Statement has the form discover - (path).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. + Statement is presented in the form discover + (path). 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. Controller - Statement has the form controller + Statement is presented in the form controller (path) 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. + 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. - Example below shows 3 modules: + The below example shows 3 modules: name="tests/modules.cpp: Modules.Doc_AdvModRes_1" - //First Module module:: - name(testA); - provide(superService); - status(needToTestEvenMore). + name(testA); + provide(superService); + status(needToTestEvenMore). //Second Module module:: - name(testB); - provide(superService); - status(needToTest). + name(testB); + provide(superService); + status(needToTest). //Third Module module { - require(superService). - discover("/modules/path/"). - controller("/path/to/controller"). + require(superService). + discover("/modules/path/"). + controller("/path/to/controller"). } - Two modules offer the same feature - provide(superSerivce). 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. + Two of the modules offer the same feature + provide(superSerivce). 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. 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 0 - for status(needToTestEvenMore), + example is to look at the status of both modules. Let a score be assigned + to each possible status, e.g. 0 for + status(needToTestEvenMore) and 1 for status(needToTest). - Then controller would proceed with the best scoring module, + The controller would then proceed with best scoring module – Second Module in this case.
<?xxe-sn 26n42fz1reo 4w?>See Also Transcend: Modules API
\ No newline at end of file