diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api.md | 20 | ||||
| -rw-r--r-- | docs/builtin.md | 58 | ||||
| -rw-r--r-- | docs/domain.md | 5 | ||||
| -rw-r--r-- | docs/extending.md | 1 | ||||
| -rw-r--r-- | docs/grammar.md | 106 | ||||
| -rw-r--r-- | docs/qface_concept.png | bin | 0 -> 24584 bytes | |||
| -rw-r--r-- | docs/usage.md | 117 | ||||
| -rw-r--r-- | docs/welcome.md | 11 |
8 files changed, 318 insertions, 0 deletions
diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..647e3a3 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,20 @@ +# API + +The API mostly consist of two helper classes and the domain model. For the domain model, see the domain documentation. + +## qface.generator.FileSystem + +* FileSystem.parse_document(path: str, system: System = None) +* FileSystem.parse_dir(path, identifier: str = None, clear_cache=True) +* FileSystem.find_files(path, glob='*.qdl') + +## qface.generator.Generator + +* Generator(searchpath) + Manages the templates and applies your context data +* generator.get_template(self, name: str) + Retrievs a single template file from the template loader +* generator.render(self, name: str, context: dict) +* generator.apply(self, template: Template, context: dict) +* generator.write(self, fileTemplate: str, template: str, context: dict) +* generator.register_filter(self, name, callback)
\ No newline at end of file diff --git a/docs/builtin.md b/docs/builtin.md new file mode 100644 index 0000000..fd04109 --- /dev/null +++ b/docs/builtin.md @@ -0,0 +1,58 @@ +# Builtin Generators + +## QtCPP Generator + +This is one of the buit-in generators to generate a QtCPP API to be exported into QML. +The structs/enums/flags are defined in an own Module Qbject which acts as a namespace and can not be instantiated. + +Each interface is generated into a QObject with proper properties, signals and invokables. + +For example an QDL like this: + +```js +module sample 1.0 + +interface Heater { + real temperature; + Status status; + void increaseTemperature(qreal step); + void decreaseTemperature(qreal step); + event void error(string message); +} + +enum Status { + Null, + Ready, + Error +} +``` + +The QTCPP generator will generate all CPP code including the plugin code and project files. Additional it will generate an empy simulation stub. + +In QML you would now be able to write the following code. + +```qml + import sample 1.0 + + Item { + Heater { + id: heater + onStatusChanged: { + if(status === SampleModule.Ready) { + console.log('ready ...') + } + } + onError: console.log(message) + } + Text { + anchors.centerIn: parent + text: heater.temperature + } + MouseArea { + anchors.fill: parent + onClicked: { + heater.increaseTemperature(0.5) + } + } + } +```
\ No newline at end of file diff --git a/docs/domain.md b/docs/domain.md new file mode 100644 index 0000000..7d68413 --- /dev/null +++ b/docs/domain.md @@ -0,0 +1,5 @@ +# Domain Model + +The domain model resembles the structure of our system as objects. It is build by the parser and is the input into the generator. + +It is important to understand the domain model as it is the main input for the template generation.
\ No newline at end of file diff --git a/docs/extending.md b/docs/extending.md new file mode 100644 index 0000000..217634c --- /dev/null +++ b/docs/extending.md @@ -0,0 +1 @@ +# Extending QFace diff --git a/docs/grammar.md b/docs/grammar.md new file mode 100644 index 0000000..a60aded --- /dev/null +++ b/docs/grammar.md @@ -0,0 +1,106 @@ +# QDL grammar + +QDL (Qt definnition language) is an IDL to define an interface. In general it is modeled to define an interface between Qt QML and C++. The QDL syntax is flexible enough also to be used in other context. + +```html +module <module> <version> +import <module> <version> + +interface <Identifier> { + <type> <identifier> + <type> <operation>(<parameter>*) + event <type> <event>(<parameter>*) +} + +struct <Identifier> { + <type> <identifier>; +} + +enum <Identifier> { + <name> = <value>, +} + +flag <Identifier> { + <name> = <value>, +} +``` + +A QDL document always describes one module. Each document can contain one or more interfaces, structs, flags or enums. Each document can import other modules using the import statement. + + +## Module + +A module is identified name. A module should be normally a URI where all parts are lowercase (e.g. `entertainment.tuner`). A module can import other modules. This is used to ensure that dependencies are declared inside the QDL file. + +## Types + +Types are either local and can be references simply by its name, or they are from external module in this case they need to be referenced with the fully qualified name (`module + '.' + name`). A type can be an interface, struct, enum or flag. + +A module consist of either one or more interfaces, structs and enums/flags. They can come in any number or combination. The interface is the only type which can contain operations and events. The struct is merely a container to transport structured data. An enum/flag allows the user to encode information used inside the struct or interface as datatype. + +The QDL does not allow to extend interfaces. It is by design kept simple. + +Below is an example of a QDL file. + +```java +module entertainment.tuner 1.0; + +import common 1.0 + +/*! Service Tuner */ +interface Tuner { + /*! property currentStation */ + readonly Station currentStation; + /*! operation nextStation */ + void nextStation(); + /*! operation previousStation */ + void previousStation(); + /*! operation updateCurrentStation */ + void updateCurrentStation(int stationId); + + list<int> primitiveList; + list<Station> complexList; + model<int> primitiveModel; + model<Station> complexModel; +} + +/*! enum State */ +enum State { + /*! value State.Null */ + Null=0, + /*! value State.Loading */ + Loading=1, + /*! value State.Ready */ + Ready=2, + /*! value State.Error */ + Error=3 +} + +/*! enum Waveband */ +enum Waveband { + /*! value Waveband.FM */ + FM=0, + /*! value Waveband.AM */ + AM=1 +} + +flag Features { + Mono = 0x1, + Stereo = 0x2, +} + +/*! struct Station */ +struct Station { + /*! member stationId */ + int stationId; + /*! member name */ + string name; + /*! last time modified */ + common.TimeStamp modified; +} +``` + + + + + diff --git a/docs/qface_concept.png b/docs/qface_concept.png Binary files differnew file mode 100644 index 0000000..eb31dbd --- /dev/null +++ b/docs/qface_concept.png diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..d45669d --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,117 @@ +# Usage + +QFace requires one or more IDL files as input file and a generator to produce output files. The IDL files are named QDL (Qt definition language). + +There is a central client to interface the commands for generation, called cli. + +To use an existing generator just provide the path to the generator script. + + + +```sh +./cli.py generator --generator generator/csv --input input --output output +``` + +You can also create a YAML configuration file (e.g csv.yaml): + +```yaml +generator: generator/csv +input: input +output: output +``` + +And then call the client with: + +```sh +./cli.py generate --runner csv.yaml +``` + +To enable auto-live reloading just use the monitor target: + + +```sh +./cli.py generator_monitor --runner csv.yaml +``` + +This will observe the generator folder and the input folder for changes and re-run the generator. + +## Grammar + +The IDL grammar is described in the grammar file (see qface/parser/idl/T.g4) + +```html + module <identifier> <version>; + + [import <identifier> <version>]; + + interface <identifier> { + (readonly) <type> <property>; + <type> <operation>([type name]); + event <type> <operation>([type name]); + list<type> <property>; + model<type> <property>; + } + + enum <identifier> { + <name> = <value> + } + + flag <identifier> { + <name> = <value> + } + + struct <identifier> { + <type> <name>; + } +``` + +## Domain Model + +The IDL is converted into an in memory domain model (see qface/idl/domain.py). + +```yaml + - System + - Module + - Import + - Service + - Property + - Operation + - Event + - Enum + - Flag + - Struct +``` + +The domain model is the base for the code generation. + +## Code Generation + +The code generation is driven by a small script which iterates over the domain model and writes files using a template language (see http://jinja.pocoo.org) and espcially the template designer documentation (http://jinja.pocoo.org/docs/dev/templates/). + +```python +from qface.generator import FileSystem, Generator + +def generate(input, output): + system = FileSystem.parse_dir(input) + generator = Generator(searchpath='templates') + ctx = {'output': output, 'system': system} + generator.write('{{output}}/modules.csv', 'modules.csv', ctx) +``` + +This script reads the input directory returns a system object form the domain model. This is used as the root object for the code generation inside the template language. + +```jinja + {% for module in system.modules %} + {%- for interface in module.interfaces -%} + SERVICE, {{module}}.{{interface}} + {% endfor -%} + {%- for struct in module.structs -%} + STRUCT , {{module}}.{{struct}} + {% endfor -%} + {%- for enum in module.enums -%} + ENUM , {{module}}.{{enum}} + {% endfor -%} + {% endfor %} +``` + +The template iterates over the domain objects and generates text which is written into a file. The file name is also adjustable using the same template language. diff --git a/docs/welcome.md b/docs/welcome.md new file mode 100644 index 0000000..aee804c --- /dev/null +++ b/docs/welcome.md @@ -0,0 +1,11 @@ +# Welcome + +QFace is a flexible Qt API generator. It uses a common IDL format (called qdl) to define an API. QFace comes with a set of predefined generators to generate QML Plugins. QFace can be easily extended with your own generator. + + +* [API](api.md) +* [Domain](domain.md) +* [Extending](extending.md) +* [Grammar](grammar.md) +* [Usage](usage.md) +* [Builtin](builtin.md)
\ No newline at end of file |
