USAGE.md

Usage

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.

./cli.py generator --generator generator/csv --input input --output output

You can also create a YAML configuration file (e.g csv.yaml):

generator: generator/csv
input: input
output: output

And then call the client with:

./cli.py generate --runner csv.yaml

To enable auto-live reloading just use the monitor target:

./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)

module <identifier> <version>;

[import <identifier> <version>];

interface <identifier> {
    (readonly) <type> <property>;
    <type> <operation>([type name]);
    signal <signal>([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).

System
    Module
        Import
        Service
            Property
            Operation
        Enum
        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/).

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.

{% 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.