This page describes the customer requirements. Also have a look at the corresponding Use Cases of TSPHP.
Since this project and it's output is very technical, the following requirements may seem more technical than usually found in customer requirements specifications. However, those requirements are more or less high level and are refined in the System Specification of TSPHP.
The following key applies for all tables in all chapters:
Type: m = must requirement, d = desired requirement (nice to have but not mandatory).
Prio. = Priority; 1 - 3 whereas must requirements precede desired requirements and 1 = high priority and 3 = low priority (complete order: m1, m2, m3, d1, d2, d3).
Comp. = Complexity; 1 - 3 whereby 1 = low complexity and 3 high complexity.
Risk; 1 - 3 whereby 1 = low risk and 3 = high risk. The value indicates how bad it would be if this requirement will not be fulfilled. Logically desired requirements will always have a low risk.
For a better overview the functional requirements have been split up in different sub chapters. The tables in these sub chapters contain the functional requirements.
|M1||Console Application||It shall be possible to use the compiler from the command line||m||1||1||3||The compiler can be used within an IDE and as external component in other projects.|
|L1||procedural programming||The language specification of TSPHP must support procedural programming.||m||1||2||3||Procedural programming is support by PHP as well and thus the developer is already familiar with procedural programming|
|L2||object oriented programming||The language specification of TSPHP must support object oriented programming.||m||1||3||3||Object oriented programming is supported by PHP as well and thus the developer is already familiar with procedural programming|
|L3||functional programming||The language specification of TSPHP shall support functional programming.||d||1||3||1||Functional programming is supported by PHP as well and thus the developer is already familiar with procedural programming|
|L4||parameters and casting|
It shall be possible to define parameters which automatically cast the passed values to the corresponding types (rather than refusing it without an explicit casting). For instance:
|d||2||2||1||Backward compatibility for scalar types.|
|I1||Overwrite standard configuration||The compiler must provide an interface* which allows to change properties of the standard configuration for the current execution (does not overwrite the permanently - see NF8 Configurable).||m||1||1||1||The developer has the possibility to use different configurations without rewriting the standard configuration each time.|
|I2||Input stream||The compiler must provide an interface which allows to add an InputStream with an identifier to the streams which will be translated later on.||m||1||1||1||This way it is possible to use the compiler in other use cases than translating files. For instance translating strings from user input/from a database etc. Moreover, it makes it easier to test the compiler.|
|I3||Input - file||The compiler must provide an interface* which allows to add a path of a TSPHP file to a collection of paths. All files found by the provided paths will be translated later on.||m||1||1||3||Sometimes it is more convenient to specify a path to a file instead of doing the InputStream conversion. The compiler shall do the work. This interface is especially important if the compiler is used in an IDE or as part of an Ant task.|
|I4||Input - directory||The compiler must provide an interface* which allows to pass a path to a directory which will then be examined and each path of a TSPHP file found in this directory will be used as in requirement I3 Input - file.||m||2||1||2||Sometimes it is more convenient to add a path of a directory rather than all paths of the containing files. The compiler shall do the work.|
|I5||Input - file set||The compiler shall provide an interface* which allows to pass a file set as in Ant to specify the input files. The paths of those files will be used as in requirement I3 Input - file.||d||2||2||1||This provides more flexibility for the user/system which use the compiler since the files which shall be translated can be specified by a pattern and exclusions can be made easily.|
* Not just an interface in Java. It shall also provide this interface as argument of the console application. For instance, the interface to pass a path to a property file could be the argument
--prop in the argument list of the console application.
|O1||Output stream||The compiler must provide an interface which returns the translated input streams as output streams inclusive the specified identifier.||m||2||1||1||This way it is possible to use the compiler in other uses cases than translating files. For instance the ouptut stream shall be stored in a database instead. Furthermore, it makes it easier to test the compiler.|
|O2||Output - directory - path||The compiler must provide an interface* which allows to define the output directory to which the translated input streams will be written as files.||m||1||1||3||A file can be used by a developer whereas an output stream cannot be used by a developer.|
|O3||Output - directory - structure|
However, it is not possible to force that structure, it is more a recommendation. Have a look at the following design decisions for more information:
and the system requirement:
Customisation. The developer can choose between different output structures.
|O4||Output - directory - structure strategies||The compiler shall support at least the following output directory structure strategies:||d||2||2||1||This two variants should cover the need of most developers.|
|O5||Output format||It must be configurable (NF8) to which output format the input will be translated.||m||2||2||1||Portability. It would be possible to support other PHP versions than PHP 5.4, or the output could be in an another representation such as XML etc.|
|O6||Output format PHP 5.4||The standard distribution of the compiler must support PHP 5.4 as output format.||m||2||3||3||The aim is to translate TSPHP to PHP 5.4. This requirement will change in the future of course.|
However, it is not possible to enforce this configuration, it is more a recommendation. Have a look at the following design decisions for more information:
and the system requirements:
Smaller PHP 5.4 files.
Non functional requirements
|NF1||Exchange ANTLR v3.5||The design of the compiler must take account of an exchange (use another compiler-generator) and a change of ANTLR (a new version is available with a different interface).||m||1||1||1||Changes to the ANTLR interface in the future will not result in a big change of the compiler. Furthermore it would be easier to exchange ANTLR with another compiler-generator|
|d||3||2||1||Extensibility. The developer can write an own structure strategy to fulfill his/her needs when flat and namespace hierarchy do not.|
|NF3||More output formats||It shall be possible to add more output format components without recompiling the compiler (see O5 Output format)||d||3||2||1||Extensibility. The developer can write an own output format component which fulfill his/her needs without rewriting or recompiling the compiler.|
|NF4||Expandable argument list||The console application (M1) shall be designed to support extensibility for the argument list. The aim is to provide a way for extensions of the compiler to allow users/systems to configure them through arguments.||d||3||3||1||Extensibility. This would enable an easy way to provide 'configuration through arguments' for extensions; a developer of an extension would benefit.|
|NF5||Automation||The compiler will in all probability be used in conjunction with an IDE. But also build servers could be candidates which use the compiler. Therefore the design of the compiler must take that into account.||m||1||2||2||Automation|
|NF6||Independence||Independent components must be developed where possible.||m||1||3||2||Reuseability. The components can be used in other projects as well.|
|NF7||Testability||The design of the compiler must consider that TTD is used in this project.||m||1||2||2||Source code is better testable which result in better quality.|
|NF8||Configurable||The compiler must comprise a standard configuration which is configurable without recompiling (see other requirements which link back to this requirement).||m||1||1||2||Customisation. The developer can configure the compiler without recompiling the compiler|
|NF9||Distribution of TSPHP||It shall be possible to reuse TSPHP files in other projects but without passing all the compiling steps.||d||1||3||1||Reusability of code and faster compile process (especially in large projects with a lot of external code)|
|NF10||Deployment without Java installation||It shall be considered that the compiler could be used in a non Java environment.||d||3||2||1|
The compiler can be integrated into IDEs which are not Java based. For instance if TSPHP is written in Visual Studio.
|NF11||Additional steps||The design of the compiler shall take into account that one might want to add additional steps such as optimisation, code weaving, obfuscation etc.||d||2||3||1||Extensibility. Additional steps can be added with low costs.|
|NF12||Performance||The design of the compiler must condiser that the compiler should achieve good performance.||m||3||2||2||Faster compile process, happier developers.|
The architecture of the compiler should rather aim simplicity than performance
A super performant compiler which is very complex is worse than a less complex compiler with a worse performance.
|Sharing||TSPHP and TinsPHP have a lot in common and should share classes where possible.||d||1||2||1||Lowers code duplication, ergo maintenance, bugs etc. Besides, they promote each other indirectly.|
|More input formats||It shall be possible to use the compiler with a different input format without recompiling the compiler.||m||2||2||2||Extensibility. A developer could also write its own parser, e.g. one which supports a TSPHP based DSL.|
- The compiler shall be based on a compiler-generator. Literally on ANTLR v3.5
- The compiler does not have to be compatible with older versions than java 1.7
- See Rough Concept of the bachelor project > Scope for further constraints.