Usage

Concept

QFace requires one or more IDL files as input file and a generator to produce output files. The IDL files are named QFace interface documents.

_images/qface_concept.jpg

To use QFace you need to write your own generator. A generator is a small python script which reads the QFace document and writes code using template files.

# gen.py
from qface.generator import FileSystem, Generator

def generate(input, output):
    # parse the interface files
    system = FileSystem.parse(input)
    # setup the generator
    generator = Generator(search_path='templates')
    # create a context object
    ctx = {'output': output, 'system': system}
    # apply the context on the template and write the output to file
    generator.write('{{output}}/modules.csv', 'modules.csv', ctx)

# call the generation function
generate('sample.qface', 'out')
python3 gen.py

Code Generation Principle

The code generation is driven by a small script which iterates over the domain model and writes files using the Python Jinja template language. Refer to http://jinja.pocoo.org and particularly the template designer documentation at http://jinja.pocoo.org/docs/dev/templates/.

from qface.generator import FileSystem, Generator

def generate(input, output):
    system = FileSystem.parse(input)
    generator = Generator(searchpath='templates')
    ctx = {'output': output, 'system': system}
    generator.write('{{output}}/modules.csv', 'modules.csv', ctx)

This script reads the input directory and returns a system object from 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 -%}
    INTERFACE, {{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 the output file. Using the generator write method generator.write(path, template, context) the output file path can be specified.