white papers 2	bandm meta_tools	project struct proposal

Collected White Papers on Technical Details --3--

1          Applications and Self-Applications, a Survey
1.1          Table of Usage
1.2          Some paradigmatic data flows
2          Coding Rules

^{^ToC} 1 Applications and Self-Applications, a Survey

^{^ToC} 1.1 Table of Usage

The following table does NOT mention the usage of ops, format, message, dtd, dtm and many other smaller packages, because these are ubiquituously engaged. The intention is to point out some paradigmatic applications of the larger functional unities of ^meta_tools , which can be helpful for the uses as examples, documentation and inspiration.
A tabelaric survey is followed by some more detailed graphs of data flow.

Remarks:
(X1) metajava/the users of metajava heavily use "format", but not the front-end compiler.
(X2) tdom uses "option" after a second bootstrap cycle.
(X3) users of "muli" and "option" frequently use "d2d", after completion of the bootstrap cycle.

^{^ToC} 1.2 Some paradigmatic data flows

A very versatile pattern is the following, which happens in the complete and in a shortened form:

                         ]
                     d2d ]           tdom               javac
 <inputFormat>.ddf  -----]--> <iF>.dtd -------> <iF>.java -----> <iF.class>
                         ]

                          <input>.xml----\
                     d2d                  \                    HANDCODED
 <input>.d2d ----------------->sax---------+--> objectModel ===============> output
                                     tdom          \                   /
                                                     ----> aux Data --
                                                      HANDCODED   

The long form works as follows:
Nearly all sources are generated from an initial ".ddf" d2d-text-type definition automatically.
The input data is encoded in d2d format and directly fed into the tdom model, with a few lines of top-level code.
The "auxData" are "diagonal vertices" in the tdom graph, i.e. additional directories, maps, indexes, etc., constructed by hand coding.
In most cases this pattern is very efficient: only few additional data must be generated, the generated visitor pattern can heavily be exploited, resulting in few lines of user code.

eu,bandm.book2, de.na-berlin.meeli, eu.bandm.rezept eu.bandm.wiki work this way.

An esp. interesting case is when an XHTML model is the generated output (rezept, wiki). Here one tdom model is transformed into a different one.

(Older examples are pameca/docusoft/src/al/org/pameca/docusoft/docu_metadata.dtd and eu/bandm/tools/jul.)

The method which realizes the functionality of "data 2 tdom", callable by alle these applications, is static eu.bandm.tools.d2d2.base.Tasks.text2tdom(..) .

The most complex example is the txsl xslt interpreter: its operation is nothing more than a transformation (expansion) of the original tdom model of the xslt code.

The shortened form starts with a DTD for generating tdom.
The input data normally is an XML file, in the standard encoding.
Nevertheless, this file can also be generated by d2d parsing, controlled by the dtd.
This pipelining can happen internally, controlled by the application, or externally in the file system, controlled by "make" etc. This does not make any difference in the logical of the data flow.

In this way tools.option and tools.muli are implemented. They are used as follows

^{^ToC} 2 Coding Rules

The general rules of code design can be taken from our theoretical papers.

Here only a few of the theoretical guidelnes:
(Perhaps later more to come!?!? FIXME)

1. Normally "functional" style shall be preferred, which passes parameters explicitly and makes data-flow completely visible by one glance to the method's declaration.
2. Whenever possible, point-free formulations shall be preferred, e.g. by using the tools.ops library, etc.
3. Assumptions about the incoming state of parameters and fields should be made explicit by inserting assert ...
4. Data types shall be cleanly defined as "algebraic" and "immutable", or "object style". They must be encoded accordingly, i.e. with protected fields and restricted setter methods. Normally algebraic/immutable is preferable.

The following rules are just technical, about the details in writing. They may seem overspecified but turned out to be very sensible, esp. for maintainability.

1. Source code is written with indentation. The indentation is left to the editor (normally XEmacs) with an ident amount of two(2) spaces.
2. Variables must have talking names. Whenever appropriate the name of a "global" variable should be the name of its type, with lower case initial character.
   One-character variable names are only possible for very narrow scopes of few lines.
3. Reference type declarations of variables, fields, parameters and results must be prefixed by /*opt*/ if the normal operation includes the value null. (This corresponds to type declarations "opt()" in more precise programming languages.)
4. All parameters, fields, variables must be declared final whenever possible. (This turned out to be incredible helpful when reading third-party or older own sources!-)
5. Parameters should always be declared final and not reused as local variables.
6. While "functional style" is preferred, some types of problems are easier written using object style and global fields. There, field values can be used in the very middle of some method code. It can be very sensible to make these accesses explicit by adding comments mimicking declarations, as in ...
   public void myMethod (final int a,
   /*glo in field1, glo in out field2*/){ ...
7. Temporal trace output "instrumentation" shall be prefixed by /**/, for easy grepping and elimination.

The indentation

white papers 2	bandm meta_tools	project struct proposal

made    2018-12-30_11h03   by    lepper   on    linux-q699.site       

produced with eu.bandm.metatools.d2d    and    XSLT    FYI view page d2d source text