diff --git a/README.md b/README.md index 52d60c0..b578245 100644 --- a/README.md +++ b/README.md @@ -161,32 +161,37 @@ generation. ## The gen() function -The gen() function has a short name to be convenient in templates. +The `gen()` function has a short name to be convenient in templates. -You can call the gen() function from within a template to delegate the -required work for generating a certain node type within a larger generation. -(See Template example). Thus the templates can effectively "call" each other, -without the need for template-include or template-inheritance features, but -those features in jinja2 are still available if they are needed. +You can call the `gen()` function from within a template to delegate the +required work for generating a certain node type to a separate template file. +(See Template example later). Thus the templates can effectively "call" each +other, without the need for template-include or template-inheritance features +that jinja2 provides (but those features are of course still possible to use). -gen() can be called with just the node (evaluating the passed parameter type at run-time) -or by explicitly stating a template: +`gen()` can be called with (1) just the node (evaluating the passed parameter type at run-time) +or (2) by explicitly stating a template: -1. Providing the node reference only. +1. Providing the node reference only: ``` def gen(node : AST) +``` example use: +``` gen(node) - ``` + This variant will dynamically determine the node type (a subclass of AST) -and generate using the predetermined template for that node type. +and generate using the predetermined template for that node type. (See +`default_templates` variable). -2. Providing the node and a specific template. The default template for the - node type is not used. The specified template is used instead. +2. Providing the node and a specific template. The specified template is + used regardless of the node type: ``` def gen(node : AST, templatename : str) +``` example use: +``` gen(node, 'My-alternative-method-template.tpl') ``` @@ -209,7 +214,8 @@ template with useful information here. * **suffix** should try to mimic the normal suffix for the file format that is being generated. For example, if the templates aims to generate a HTML document, name the template with .html. If it is generating a programming -language, use an appropriate suffix for the file, etc. +language, use an appropriate suffix for the file, etc. If there is no obvious +type, we use ".tpl". Examples: @@ -225,25 +231,30 @@ Service-rust.rs ### Variable use in templates * The standard functions in vsc_generator.py will pass in only a single node -of AST type to the template generation framework. The node will be of a -particular type, depending on what type of template is being rendered -(or more correctly, what was specified when the generation function was called - -- either a top level function like render_ast_with_template_file() - or a call to gen() with the node in question as parameter.) +of AST type to the template generation framework. (If you define your own +custom generator, it could choose to do something different). + +The passed node and will have a particular node type (subclass to AST). The +type depends on what type of template is being rendered (or more correctly, +what was specified when the generation function was called -- either a top +level function like render_ast_with_template_file() or a call to gen() with +the node in question as parameter.) * When using the provided generator convenience functions, the node that is "passed to the template" (roughly speaking) will always be named **item** -* Since the class members are public, they can be walked directly through -dot-notation in code that is embedded in the template. For example, if the -passed item is a Service the template can get to the namespaces list by -just referencing it: `item.namespaces` +* The class member variables (referring to the children of a node) in +all AST nodes are public. This means they can be referenced directly through +dot-notation inside code that is embedded in the jinja template. For example, +if the passed `item` is a Service the template can get to the _list_ of +namespaces in the service by just referencing it: `item.namespaces` + +This of course means that dot-notation could also be chained: +`item.namespaces[1].methods[0].description` - the description of th efirst +method name in the second namespace. -Dot notation can be chained as needed: -`item.namespaces[1].methods[0].description` - the first method name in the -second namespace. -...but of course it is more likely to use loop constructs to iterate over -lists than to address specific indexes like that: +It is however more likely to use loop constructs to iterate over lists than to +address specific indexes like that: ``` {% for i in item.namespaces %} @@ -253,15 +264,15 @@ lists than to address specific indexes like that: # Advanced features -jinja2 is a very capable templating language. Advanced generators can of -course make use of any features in python or jinja2 to create an advanced -generator. Any features that might be applicable in more than one place would -however be best generalized and introduced into the vsc_generator.py helper -modules, for better reuse. +jinja2 is a very capable templating language. Generators can make use of any +features in python or jinja2 to create an advanced generator. Any features +that might be applicable in more than one place would however be best +generalized and introduced into the vsc_generator.py helper module, for +better reuse between custom generator implementations. ### Template example -This templates expects that the "item" passed in is the Service object. +This template expects that the "item" passed in is a Service object. It calls the gen() function from within the template to delegate work to a separate template for Methods. @@ -282,6 +293,17 @@ to a separate template for Methods. {% endfor %} ``` +The gen() function in the vsc_generator implementation will determine the node +type of `x` at runtime, yielding `Service`. It will will then look into the +`default_templates` variable to see which is the template file to use for a +Service node, and generate the node using that template. + +The global `default_templates` variable is defined by vsc_generator to point +to some templates used for test/demonstration. A custom generator +implementation would modify this variable, or simply overwrite the value after +including the vsc_generator as a module (or later on, this might be passed in +at run-time in a different way). + # Future plans, new proposals and enhancements Please refer to [GitHub tickets](https://github.com/GENIVI/vsc-tools/issues)