Commit b2d35285 authored by Maxime Perrotin's avatar Maxime Perrotin

Document the template engine

parent 24d8f56e
SKELETON TEMPLATES
==================
This is the place where the templates describe what code shall be generated when the tool is asked to generate function skeletons (done by default).
Adding or modifying the templates does not require recompilation of the tool. It is possible to add support for new languages or generate additional files for the existing languages by just adding new subfolders.
The format of the template file is the one of the _templates-parser_ engine from Adacore. Complete documentation is available online (http://docs.adacore.com/live/wave/aws/html/template_parser/index.html)
How to add or modify a template
-------------------------------
You can create your own template files. We will show how the C templates are defined, as if we had to do them from scratch.
Each set of template allows to generate one file corresponding to a build script (e.g. a Makefile) and one file with content related to a TASTE function. For both, you are free to set the name of the file and all its content.
In this example we will create a set of template that generate the _header files_, as part of the C function skeletons.
1. Create a new folder (any name)
```
$ mkdir c-header
$ cd c-header
```
2. List the template files
These files are needed:
```
c-header/
├── function-filename.tmplt # Name of the file we want to generate
├── function.tmplt # Main template for the output file
├── interface.tmplt # Template for one provided or required interface
├── makefile-filename.tmplt # Name of the file we want to generate for the build script
├── makefile.tmplt # Content of the build script
└── trigger.tmplt # Condition that triggers the application of this template
```
3. Define the trigger
The file trigger.tmplt defines the condition that has to be fulfilled for the tool to actually process the templates in the current folder.
It has to return the string TRUE if the condition is met. Any other value means FALSE.
For example, for the C header, the content is the following:
```
@@IF@@ @_Language_@ = "C"
TRUE
@@END_IF@@
```
`@_Language_@` is a template variable. The list of available variables is listed at the top of each template file, for convenience.
If you look at the template for the _body_ file trigger for C, it contains an additional condition:
```
@@IF@@ @_Language_@ = "C" and not @_Filename_Is_Present_@
TRUE
@@END_IF@@
```
Here, we want to generate the file _only if it is not already there_, to prevent overwritting user code.
4. Define the filenames
The `function-filename.tmplt` and `makefile-filename.tmplt" are used to determine the output file name:
```
$ cat function-filename.tmplt
@_LOWER:Name_@.h
```
The template engine allows to filter strings in many convenient way. Here we lowercase the function name to return a filename in lowercase.
```
$ cat makefile-filename.tmplt
Makefile
```
5. Define the content of the function template
Many template variables are available as attributes derived from the parsing of the Interface View:
```
@@-- @_Name_@ : The name of the function
@@-- @_Language_@ : The implementation language
@@-- @_List_Of_PIs_@ : List of all Provided Interfaces (just names)
@@-- @_List_Of_RIs_@ : List of all Required Interfaces (just names)
@@-- @_List_Of_Sync_PIs@ : List of synchronous Provided Interfaces
@@-- @_List_Of_Sync_RIs@ : List of synchronous Required Interfaces
@@-- @_List_Of_ASync_PIs@ : List of asynchronous Provided Interfaces
@@-- @_List_Of_ASync_RIs@ : List of asynchronous Required Interfaces
@@-- @_ASN1_Modules_@ : List of ASN.1 Modules names
@@-- @_ASN1_Files_@ : List of ASN.1 Files with path
@@-- @_Timers_@ : List of timers (just names)
@@-- @_Has_Context_@ : Flag, True if there are context parameters
@@-- @_CP_Names_@ : List of Context Parameter names
@@-- @_CP_Types_@ : List of Context Parameter types
@@-- @_Provided_Interfaces_@ : From template: Provided interfaces with params
@@-- @_Required_Interfaces_@ : From template: Required interfaces with params
@@-- @_Property_Names_@ : List of User-defined properties (names)
@@-- @_Property_Values_@ : List of User-defined properties (values)
@@-- @_Is_Type_@ : Flag, True if function is a component type
@@-- @_Instance_Of_@ : Optional name of component type
```
It is possible to render lists of items with automatic indentation, and shape the overall output file based on the output language.
For example this is an extract of the C template:
```
/*
* DO NOT EDIT THIS FILE, IT WILL BE OVERWRITTEN DURING THE BUILD
*/
#pragma once
#include "dataview-uniq.h"
#ifdef __cplusplus
extern "C" {
#endif
void @_LOWER:Name_@_startup();
/* Provided interfaces */
@@TABLE@@
@_Provided_Interfaces_@
@@END_TABLE@@
```
Provided and Required interface templates are defined in a separate file and provided to the function template as a list.
This is an extract of `interface.tmplt`:
```
@@IF@@ @_Direction_@ = "PI"
void @_LOWER:Parent_Function_@_PI_@_LOWER:Name_@(
@@ELSE@@
extern void @_LOWER:Parent_Function_@_RI_@_LOWER:Name_@(
@@END_IF@@
```
When applying this template, the engine will generate:
```
void function_PI_interface_name(
```
or
```
extern void function_RI_interface_name(
```
And this is followed by the list of typed parameters.
6. Define the template of the buildscript
In the case of a Makefile, the content can be:
```
all: compile-linux
clean:
rm -rf obj
compile-linux:
mkdir -p obj && cd obj && gcc -c ../src/*.c
```
But it can obviously be much more complex and use the available template variables.
7. Test it!
If the trigger condition you defined return TRUE, the template will be exectuted.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment