Child pages
  • System Specification of TSPHP

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

IDNameDescriptionAffectsBenefit
Anchor
SysD1
SysD1
SysD1
ANTLR v3.5 GrammarAn ANTLR v3.5 based grammar for TSPHP must be created which generates an ASTAll requirements in chapter Language Specification,
NF6 - Independence

An ANTLR v3.5 based grammar improve the portability to another language such as C, C++, C# etc. Furthremore, the AST

Anchor
SysD2
SysD2
SysD2
ANTLR v3.5 Tree GrammarAn ANTLR v3.5  based tree grammar for TSPHP must be created.
 
All requirements in chapter Language Specification,
NF6 - Independence

As well as the normal grammar an ANTLR v3 based tree grammar improve the portability to another language such as C, C++, C# etc. Furthermore ANTLR can generate a tree walker out of a tree grammar. The type checker, translater (and code optimiser in the future) should use a tree grammar.

Anchor
SysD3
SysD3
SysD3
Independent parser, typechecker, translatorAll components should be independent from the compiler and from each other (excluding tests, where integration tests might use other components). However, dependencies to the common component and ANTLR are fine.NF6 - Independence,
NF7 - Testability
Independence allows using the , the type checker as well as the translator component in another context than TSPHP. For instance, the type checker and the translator could be used in an AOP implementation for TSPHP.
Anchor
SysD4
SysD4
SysD4
Output format componentsThe different output formats shall be implemented as independent components

O5 - Output format,
O6 - Output format PHP 5.4,
NF3 - More output formats,
NF6 - Independence,
NF7 - Testability

This way the design of the compiler is forced to support different output formats, thus a well-defined interface has to be defined. This interface could be implemented by another output format component and this component could be used instead of the PHP 5.4 output format component (or amongst).
Anchor
SysD5
SysD5
SysD5
Output - directory - structure

Each output format component (SysD4) will decide how it behaves in terms of how the structure of its output directory will look like.

A good practice may be to take over the global configuration (see O3 - Output - directory - structure) and to make it configurable (NF8), so it is possible to overwrite the global configuration.

O3 - Output - directory - structureSince it is maybe not applicable for each output component to produce a hierarchy structure, it is better that each output format component decide on its own if this part of the component is configurable or not.
Anchor
SysD6
SysD6
SysD6
Output - directory - structure strategy componentsEach output directory strategy shall be implemented as independent component.

O3 - Output - directory - structure,
O4 - Output - directory - structure strategies,
NF6 - Independence,
NF7 - Testability

This way it is possible to reuse the output strategy by different output format components.
Anchor
SysD7
SysD7
SysD7
Omit comments

Each output format component (SysD4) will decide how it behaves in terms of omitting comments.

A good practice may be to take over the global configuration (see O7 - Omit comments) and to make it configurable (NF8), so it is possible to overwrite the global configuration.

O7 - Omit commentsIt could be that for one output format component (SysD4) it is essential that comments are not omitted and another output format component cannot deal with comments etc. This way we have a more flexible solution.
Anchor
SysD8
SysD8
SysD8
AST and IWalker interfaceThe parser of the compiler will generate an TSPHPAst (TSPHP's abstract syntax tree) and there will be an simple interface IWalker with the method TSPHPAst walk(TSPHPAst ast).NF11 - Additional stepsThe well defined and simple interface IWalker will enable additional step such as code optimisation, code obfuscating, code weaving etc. which should facilitate a contribution to TSPHP
Anchor
SysD9
SysD9
SysD9
Exchange ANTLRThe compiler shall encapsulate the access to generated code from ANTRL v3NF1 - Exchange ANTLR v3.5Changes to the ANTLR interface in the future will not result in a big change of the compiler. Only the class/component which encapsulates the access has to be changed. Furthermore, it would be easier to exchange ANTLR with another compiler-generator
Anchor
SysD10
SysD10
SysD10
AST and ANTLRThe class CommonTree from ANTLR will be used as base class for our TSPHPAst representation. The downside of this decision will be, that every extension/add-on of the compiler (such as code optimiser, code obfuscator etc.) will depend on ANTLR. This goes against NF1 - Exchange ANTLR v3.5 but seems to be the better choice (see 14.01.2013 - Review meeting architecture).NF1 - Exchange ANTLR v3.5Lower maintenance, if an own implementation would be used, then we would need to fix bugs on our own if ANTLR recognise a bug in their implementation. Furthermore we would need to change our implementation every time ANTLR change something as well. This way ANTLR makes the change for us and we just need to ensure, that the tests still pass when we upgrade to a new ANTLR version.

Anchor
SysD11
SysD11
SysD11

Split type checking in several phases

Split the type checking phase in definition, reference and checking phase.

The code is easier understandable and thus easier to maintain and a contribution to the project should be facilitated as well.

...

IDNameDescriptionTypePrio.Comp.RiskAffectsBenefit
Anchor
SysI1
SysI1
SysI1
Property file as parameterThe compiler shall provide an interface* which allows to pass a path to a property file. All properties in this file shall overwrite or extend the configuration made in the compiler's property file (SysM1).m111I1 - Overwrite Standard Config, NF8 - ConfigurableThe developer has the possibility to use different configurations without rewriting or replacing the property file each time.
Anchor
SysI2
SysI2
SysI2
Ant TaskCreate an Ant task for the compiler which uses a file set as inputd221NF5 - Automation, I5 - Input - file set indirectly also I3 - Input - file and I4 - Input - directoryAutomation. Ant is a commonly known way to automate development processes.
Anchor
SysI3
SysI3
SysI3
ClasspathThe compiler shall provide an interface* which allows to 'link' pre-compiled classes and librariesd121NF9 - Distribution, NF8 - ConfigurableRe-usability and performance.
Anchor
SysI4
SysI4
SysI4
No more InputStreamsThe compiler shall provide a method which declares, that no more input streams will be added.m112

I2 - Input stream, I3 - Input - file, I4 - Input - directory, I5 - Input - file set

In the case where not the console interface is used, where every system calls equals to one compilation, it is necessary, that one can tell the compiler, that all desired input streams have been added. Otherwise it is not possible for the compiler to know when it can actually start type checking the parsed code.

...

IDNameDescriptionTypePrio.Comp.RiskAffectsBenefit
Anchor
SysO1
SysO1
SysO1
multiple output formatsIt shall be possible to compile code and translate it to multiple output formats in one rund321

O5 - Output format,
NF3 - More output formats
,
NF12 - Performance
 

Better performance. It is not necessary to run the compiler several times for different output formats.
Anchor
SysO2
SysO2
SysO2
Anchor
php5.4Configurable
php5.4Configurable
Output format PHP 5.4 - property file
The output format component (SysD4) for PHP 5.4 shall be configurable through a property file.m211O6 - Output format PHP 5.4Customisation. The developer can configure the component without recompiling.
Anchor
SysO3
SysO3
SysO3
Output - directory - path for PHP 5.4The output format component (SysD4) for PHP 5.4 shall be configurable (NF8) concerning the name of a sub directory which will hold the output of this component. Standard should be php5.4d121O2 - Output - directory - pathSince multiple output formats can be used at one run it is necessary that output format components have an own output directory folder within the global defined directory folder and that the name is configurable to solve conflicts.
Anchor
SysO4
SysO4
SysO4
Output - directory - structure strategies for PHP 5.4The output format component (SysD4) for PHP 5.4 shall be configurable (NF8) concerning the output directory structure. Standard should be the global configuration (see O3 - Output - directory - structure)d131O4 - Output - directory - structure strategiesCustomisation. The developer can choose between different output structures.
Anchor
SysO5
SysO5
SysO5
Output format(s) as parameterThe compiler shall provide an interface* which allows to set explicitly the output format(s). This definition has precedence to the configured output format.d211

O5 - Output format,
NF8 - Configurable

The output format could also be changed through Property file as parameter. However, if the output format is the only property in that file it is quite a lot overhead. An additional argument fulfills better the need of the developer.
Anchor
SysO6
SysO6
SysO6
Output format PHP 5.4The compiler shall comprise an output format component for PHP 5.4m233O6 - Output format PHP 5.4,The aim is to translate to PHP 5.4.
Anchor
SysO7
SysO7
SysO7
Omit comments PHP 5.4The output format component (SysD4) for PHP 5.4 shall be configurable (NF8) concerning omitting comments or not. Standard should be the global configurationd311O7 - Omit comments

Smaller PHP 5.4 files. However, comments can be useful if the PHP files are used in other projects which are not using TSPHP or if classes, methods etc. are annotated.

Anchor
SysO8
SysO8
SysO8
Only pre-compileIt shall be configurable (NF8) whether the full translation process shall be conducted or only the pre-compilation. Makes only sense if pre-compiled input is stored in files (SysO9) or the pre-compiled stream is retrieved by get pre-compilation (SysO10)d121NF9 - Distribution of TSPHPPerformance. For instance, if only the pre-compiled files are used it is not necessary to do the whole translation step.
Anchor
SysO9
SysO9
SysO9
pre-compiled input is stored in filesIt shall be configurable (NF8) whether the pre-compiled input shall be stored in files or not.d131NF9 - Distribution of TSPHPRe-usability and performance. The pre-compiled files can be used in other projects and do not have to be fully compiled again.
Anchor
SysO10
SysO10
SysO10
Get pre-compiliationThe compiler shall provide an interface to retrieve the pre-compilation streams including identifierd231NF9 - Distribution of TSPHPUseful if the pre-compiled streams are not stored in files but in another media (for instance in a database).

...

In reality it is a little bit more complicated than that. Not only files and streams can be used to define what data the compiler should compile. Have a look at the requirements for input above. Also the output is not necessarily only translated code. It is also possible to retrieve pre-compiled code (see SysO8, SysO9  and SysO10).

Block View

The following figure shows the block view of the compiler (please click on the image to view it in its original size).

...

The parser heavily depends on ANTLR v3 and TSPHPLexer as well as TSPHPParser are generated from the corresponding grammar file (can be found in the version control system). The parser is implemented as own component thus it can be reused in other contexts than TSPHP (see also SysD1)

Runtime View

The following figure shows an activity diagram of one compilation (please click on the image to view it in its original size).

...

There are three external interfaces. Both are shown in Block View.

  • The first one is provided for system calls. As an example, it can be used by a developer to execute the compiler through the console. The Main class is implementing this interface.
  • The second interface is provided for other Java applications. A facade is implementing the interface and is delegating the calls to the corresponding classes.
  • And the third interface is provided for extension developers and is represented by the tsphp-interface-x.x.x.jar (Have a look at Distribution View)

Scoping

Note

Unfortunately this chapter does not yet exists (see task

JIRA
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverType-safe PHP: A compile time approach
serverIdb7afdd67-93a6-3609-bfeb-dc0c848443d2
keyTSPHP-534
) Please have a look at the Bachelor Thesis - Type-Safe PHP: A compile time approach, appendix D6 in the meantime

...