1 files changed, 96 insertions, 0 deletions
diff --git a/USAGE.md b/USAGE.md
new file mode 100644
index 0000000..00cf2b9
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,96 @@
+# 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]);
+        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).
+
+    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.