Child pages
  • Customer Requirements of TSPHP
Skip to end of metadata
Go to start of metadata

Introduction

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:

Key:
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.

Functional requirements

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.

Misc

IDNameDescriptionTypePrio.Comp.RiskBenefit
M1Console ApplicationIt shall be possible to use the compiler from the command linem113The compiler can be used within an IDE and as external component in other projects.

Language specification

IDNameDescriptionTypePrio.Comp.RiskBenefit
L1procedural programmingThe language specification of TSPHP must support procedural programming.m123Procedural programming is support by PHP as well and thus the developer is already familiar with procedural programming
L2object oriented programmingThe language specification of TSPHP must support object oriented programming.m133Object oriented programming is supported by PHP as well and thus the developer is already familiar with procedural programming
L3functional programmingThe language specification of TSPHP shall support functional programming.d131Functional programming is supported by PHP as well and thus the developer is already familiar with procedural programming
L4parameters 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:

d221Backward compatibility for scalar types.

Input

IDNameDescriptionTypePrio.Comp.RiskBenefit
I1Overwrite standard configurationThe compiler must provide an interface* which allows to change properties of the standard configuration for the current execution (does not overwrite the standard configuration permanently - see NF8 Configurable).m111The developer has the possibility to use different configurations without rewriting the standard configuration each time.
I2Input streamThe compiler must provide an interface which allows to add an InputStream with an identifier to the streams which will be translated later on.m111This 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.
I3Input - fileThe 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.m113Sometimes 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.
I4Input - directoryThe 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.m212Sometimes 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.
I5Input - file setThe 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.d221This 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.

Output

IDNameDescriptionTypePrio.Comp.RiskBenefit
O1Output streamThe compiler must provide an interface which returns the translated input streams as output streams inclusive the specified identifier.m211This 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.
O2Output - directory - pathThe compiler must provide an interface* which allows to define the output directory to which the translated input streams will be written as files.m113A file can be used by a developer whereas an output stream cannot be used by a developer.
O3Output - directory - structure

It shall be configurable (NF8) how the structure of the output directory shall be look like.

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:
SysD4 - output format component, SysD5 - Output - directory - structure

and the system requirement:
SysO4 - Output - directory - structure strategies for PHP 5.4

d211

Customisation. The developer can choose between different output structures.

 

O4Output - directory - structure strategiesThe compiler shall support at least the following output directory structure strategies:
  • flat hierarchy: each file in the same folder
  • namespace hierarchy: a folder for each namespace, a subfolder for each subnamespace etc. and the files in the corresponding folders.
d221This two variants should cover the need of most developers.
O5Output formatIt must be configurable (NF8) to which output format the input will be translated.m221Portability. 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.
O6Output format PHP 5.4The standard distribution of the compiler must support PHP 5.4 as output format.m233The aim is to translate TSPHP to PHP 5.4. This requirement will change in the future of course.
O7Omit comments

It shall be configurable (NF8) whether comments are omitted in the output or not. Standard should be comments are omitted.

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:
SysD4 - output format component, SysD7 - Omit comments

and the system requirements:
SysO7 - Omit comments PHP 5.4

d211

Smaller PHP 5.4 files.

Non functional requirements

IDNameDescriptionTypePrio.Comp.RiskBenefit
NF1Exchange ANTLR v3.5The 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).m111Changes 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
NF2More ouput directory structure strategies

It shall be possible to add more structure strategies for the output directory without recompiling the compiler (see  O3 Output - directory - structure).

This requirement is obsolete, since it is the responsibility and decision of the output format component (SysD4) if a output directory structure strategy is used or not.

d321Extensibility. The developer can write an own structure strategy to fulfill his/her needs when flat and namespace hierarchy do not.
NF3More output formatsIt shall be possible to add more output format components without recompiling the compiler (see O5 Output format)d321Extensibility. The developer can write an own output format component which fulfill his/her needs without rewriting or recompiling the compiler.
NF4Expandable argument listThe 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.d331Extensibility. This would enable an easy way to provide 'configuration through arguments'  for extensions; a developer of an extension would benefit.
NF5AutomationThe 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.m122Automation
NF6IndependenceIndependent components must be developed where possible.m132Reuseability. The components can be used in other projects as well.
NF7TestabilityThe design of the compiler must consider that TTD is used in this project.m122Source code is better testable which result in better quality.
NF8ConfigurableThe compiler must comprise a standard configuration which is configurable without recompiling (see other requirements which link back to this requirement).m112Customisation. The developer can configure the compiler without recompiling the compiler
NF9Distribution of TSPHPIt shall be possible to reuse TSPHP files in other projects but without passing all the compiling steps.d131Reusability of code and faster compile process (especially in large projects with a lot of external code)
NF10Deployment without Java installationIt shall be considered that the compiler could be used in a non Java environment.d321

The compiler can be integrated into IDEs which are not Java based. For instance if TSPHP is written in Visual Studio.

NF11Additional stepsThe design of the compiler shall take into account that one might want to add additional steps such as optimisation, code weaving, obfuscation etc.d231Extensibility. Additional steps can be added with low costs.
NF12PerformanceThe design of the compiler must condiser that the compiler should achieve good performance.m322Faster compile process, happier developers.

NF13

Simplicity

The architecture of the compiler should rather aim simplicity than performance

m

3

3

2

A super performant compiler which is very complex is worse than a less complex compiler with a worse performance.

NF14

SharingTSPHP and TinsPHP have a lot in common and should share classes where possible.d121Lowers code duplication, ergo maintenance, bugs etc. Besides, they promote each other indirectly.

NF15

More input formatsIt shall be possible to use the compiler with a different input format without recompiling the compiler.m222Extensibility. A developer could also write its own parser, e.g. one which supports a TSPHP based DSL.

Constraints