KDevelop5/File template specification: Difference between revisions

From KDE TechBase
(Explanations and screenshot for template options)
 
(24 intermediate revisions by 2 users not shown)
Line 3: Line 3:
=== Template language ===
=== Template language ===


Class templates use the [http://grantlee.org Grantlee] library for rendering templates. It has more features than KMacroExpander, the most important being loops and the ability to expose custom data types from C++ code to templates. The use of Grantlee makes templates more powerful, but also more difficult to write.  
Source filj templates use the [http://grantlee.org Grantlee] library for rendering templates. It has more features than KMacroExpander, the most important being loops and the ability to expose custom data types from C++ code to templates. The use of Grantlee makes templates more powerful, but also more difficult to write.  


For information regarding Grantlee templates in general, refer to its [http://www.grantlee.org/apidox/pages.html documentation]. Since Grantlee's template language is based on Django's, it might be useful to read the [https://docs.djangoproject.com/en/1.1/topics/templates/ Django template documentation] as well.  
For information regarding Grantlee templates in general, refer to its [http://www.grantlee.org/apidox/pages.html documentation]. Since Grantlee's template language is based on Django's, it might be useful to read the [https://docs.djangoproject.com/en/1.1/topics/templates/ Django template documentation] as well.


=== Example template template ===
=== Example template template ===
Line 13: Line 13:
=== File structure ===
=== File structure ===


Like [[Development/KDevelop/Project_template_specification|project templates]], class templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a <tt>.desktop</tt> extension instead of <tt>.kdevtemplate</tt>, although both are supported.  
Like [[Development/KDevelop/Project_template_specification|project templates]], file templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a <tt>.desktop</tt> extension instead of <tt>.kdevtemplate</tt>, although both are supported.  


Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, class templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.  
Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, file templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.


=== Description file format ===
=== Description file format ===
The template descriptions files are normal <tt>.desktop</tt> files. They must contain a <tt>General</tt> section, as well as one section for each output file. In most cases, the template will have two output files for C++ classes and one output file for other languages. However, using separate user interface files and/or a shared d-pointer hierarchy can cause a class to need more files. Templates in '''KDevelop''' allow any number of output files.
==== Example ====
An example description for a template with three output files is below
<syntaxhighlight lang="ini">
[General]
Name=Private Pointer
Comment=C++ Class with a private D-pointer
Category=C++/Basic
Type=Class
Language=C++
Files=Header,PrivateHeader,Implementation
OptionsFile=options.kcfg
[Header]
Name=Public Header
File=class.h
OutputFile={{ name }}.h
[PrivateHeader]
Name=Private Header
File=class_p.h
OutputFile={{ name }}_p.h
[Implementation]
Name=Implementation
File=class.cpp
OutputFile={{ name }}.cpp
</syntaxhighlight>
==== Entries ====
The <tt>Name</tt> and <tt>Comment</tt> entries are the same as in other <tt>.desktop</tt> files and can be translated.
The <tt>Category</tt> is used for grouping when showing a list of templates to the user. It should contain at least two levels, separated by slashes. The default templates use the following format: <tt>Language/Framework</tt>, e.g. <tt>C++/Qt</tt>.
The <tt>Type</tt> is optional and can be either <tt>Class</tt> or <tt>Test</tt>. In both cases the wizard will add some additional configuration pages and variables.
The <tt>Language</tt> is optional and can reference a KDevelop language plugin by it's <tt>X-KDevelop-Language</tt> identifier. When given, the language plugin will be asked to create a class helper, otherwise a default class helper will be chosen.
The <tt>OptionsFile</tt> entry is optional, using it specifies configuration options for this template. For more information about template options, see [[Projects/KDevelop4/Class_template_specification#Custom_options|Custom options]].
A class template description file may also contain an entry with key <tt>BaseClasses</tt>. It is only used for class templates, and any clases specified in this way are added by default to the inheritance list for the new class. The user can still remove those base classes, or add them manually, so this entry is entirely optional, it only makes things easier for the user. It accepts a list of inheritance statements, separated by commas, like so
<syntaxhighlight lang="ini">
; Example for a Qt object
BaseClasses=public QObject
; Example for a KDevelop plugin that implements an interface
BaseClasses=public KDevelop::IPlugin,public KDevelop::IBasicVersionControl
; Example for a Python new-style class
BaseClasses=object
</syntaxhighlight>
==== Output files ====
The <tt>Files</tt> entry specifies template output files. It is a list of strings, where each element is the same as a name of a group in the description file. The corresponding group has three required entries
* <tt>Name</tt> is the user visible file name. It can be translated.
* <tt>File</tt> is the path to the input file within the template archive
* <tt>OutputFile</tt> is the suggested output file name. The actual name can be set by the user, but this is the default value. It will be converted to lowercase if needed, so don't do in here.
The description file above results in a dialog page such as this
[[File:KDevelop-template-output-files-dialog.png|center|alt=KDevelop template output files dialog|Assistant page for template output files]]


=== Variables ===
=== Variables ===


The variables which are passed to class templates are described in the {{class|TemplateClassGenerator|kdevelop|extragear}} API documentation.
==== Generic ====
The following variables are passed to all templates, regardless of their type
 
{| class="wikitable"
!Variable name
!Type
!Description
!Example value
|-
|license
|String
|The license header without any comment characters. It can be split into multiple lines.
|One of the headers listed in [http://techbase.kde.org/Policies/Licensing_Policy KDE Licensing Policy]
|-
|output_file_foo
|String
|The relative path to the output file with identifier <tt>foo</tt>
|mynewclass.h
|-
|output_file_foo_absolute
|String
|The absolute path to the output file <tt>foo</tt>
|/home/user/projects/myproject/mynewclass.h
|-
|}
 
Additionally, values of any [http://techbase.kde.org/Projects/KDevelop4/File_template_specification#Custom_options custom options] exposed by the template are passed as variables.
 
==== Classes ====
The following variables are passed to <tt>Class</tt> templates
 
{| class="wikitable"
!Variable name
!Type
!Description
!Example value
|-
|name
|String
|Class name without namespaces
|Example
|-
|identifier
|String
|The full identifier of the new class, which is composed of namespaces and class name
|MyProject::Utilities::Example
|-
|namespaces
|StringList
|List of nested namespaces in which the class is declared
|[MyProject, Utilities]
|-
|description
|ClassDescription
|An object containing the class name, base classes, functions and members
|
|-
|baseClasses
|InheritanceDescriptionList
|All direct base classes of the new class, containing both the inheritance type and the base class name.
|
|-
|functions
|FunctionDescriptionList
|List of all the functions in the new class
|
|-
|members
|VariableDescriptionList
|List of all the member variables in the new class
|
|-
|}
 
The variables which are passed to class templates are also described in the {{class|TemplateClassGenerator|kdevelop|extragear}} API documentation.
 
==== C++ Specific variables ====
 
Templates for classes in C++ may make use of some additional variables provided by the language support plugin. They cover finding include files and grouping class functions and members by access specifiers.
 
{| class="wikitable"
!Variable name
!Type
!Description
|-
|public_functions, protected_functions, private_functions
|FunctionDescriptionList
|Class functions grouped by access modifiers. These lists do not include slots.
|-
|public_slots, protected_slots, private_slots
|FunctionDescriptionList
|Qt slots grouped by access modifiers
|-
|signals
|FunctionDescriptionList
|All Qt signals in the new class
|-
|public_members, protected_members, private_members
|VariableDescriptionList
|Data members grouped by access modifiers
|-
|needs_qobject_macro
|bool
|<tt>true</tt> if the class has at least one signal or slot, <tt>false</tt> otherwise
|-
|included_files
|StringList
|List of headers files that need to be included. This variable lists the missing include files for base classes.
|-
|}
 
==== Tests ====
The following variables are passed to <tt>Test</tt> templates
 
{| class="wikitable"
!Variable name
!Type
!Description
!Example value
|-
|name
|String
|Test name without namespaces
|MathTest
|-
|testCases
|StringList
|List of test case names. They do not necessarily begin or end with "test", it is up to templates for frameworks that require such prefixes to add them.
|[addition, multiplication, negativeNumbers]
|-
|}


=== Additional templates and filters ===
=== Additional templates and filters ===
To make writing templates easier, '''KDevelop''' supplies additional template utilities. They are both in the form of text template, available for including into your own, or additional Grantlee filters.
==== Templates for inclusion ====
These templates usually read some variables from the context. Thus, you have to make sure the correct variables are set before including the template. This is normally done using <code>with</code> statements.
<syntaxhighlight lang="smarty">
{% for f in functions %}
  {% with f.arguments as arguments %}
    {{ f.returnType|default:"void" }} {{ f.name }}({% include "arguments_types_names.txt" %});
  {% endwith %}
{% endfor %}
</syntaxhighlight>
Includable templates in '''KDevPlatform''' are:
{| class="wikitable"
!Template
!Required variables
!Language
!Description
|-
|<tt>arguments_names.txt</tt>
|arguments : VariableDescriptionList
|Weakly-typed languages
|Comma-separated list of argument names. 
|-
|<tt>arguments_types_names.txt</tt>
|arguments : VariableDescriptionList
|Strongly-typed languages
|Comma-separated list of argument types and names. 
|-
|<tt>include_guard_cpp.txt</tt>
|namespaces : StringList
|C++
|Include guard macro, generated from the namespaces and the class name.
|-
|<tt>namespace_open_cpp.txt</tt>
|namespaces : StringList
|C++
|Opening tag for nested namespaces
|-
|<tt>namespace_close_cpp.txt</tt>
|namespaces : StringList
|C++
|Closing tag for nested namespaces
|-
|<tt>namespace_use_cpp.txt</tt>
|namespaces : StringList
|C++
|<tt>using namespace</tt> statement for nested namespaces
|-
|}
==== Template filters ====
KDevPlatform provides an additional filter library. Because filters are implemented in code and not modifiable by users, it is preferred to use template inclusion if possible. These filters are mostly utilities for string operations and are not language specific.
To use them in templates, add <code><nowiki>{% load kdev_filters %}</nowiki></code> to the beginning of your template file.
{| class="wikitable"
!Template filter
!Description
|-
|<tt>lines_prepend</tt>
|Takes a string argument and prepends it to every line of the input. It is intended for licenses and other blocks of commented text.
|-
|<tt>upper_first</tt>
|Converts the first character of input into uppercase, and leaves the rest intact. This is useful for creating accessor functions, and prefixing identifier in general.
|-
|<tt>camel_case</tt>
|Converts the input from an underscore notation to camel case, starting with a lowercase character.
|-
|<tt>camel_case_upper</tt>
|Converts the input from an underscore notation to camel case, starting with an uppercase character.
|-
|<tt>underscores</tt>
|Converts the input to the underscore notations, where words are separated by underscores instead of uppercase letters. The output is entirely lowercase.
|}


=== Custom options ===
=== Custom options ===

Latest revision as of 10:56, 11 March 2016

 
Under Construction
This is a new page, currently under construction!


Template language

Source filj templates use the Grantlee library for rendering templates. It has more features than KMacroExpander, the most important being loops and the ability to expose custom data types from C++ code to templates. The use of Grantlee makes templates more powerful, but also more difficult to write.

For information regarding Grantlee templates in general, refer to its documentation. Since Grantlee's template language is based on Django's, it might be useful to read the Django template documentation as well.

Example template template

There is a project template that creates a new project consisting of a single KDevelop class template. You can use it by starting a new project, choosing Get More Templates... and installing this one. Proceeding to create a project using this template will create an example class template.

File structure

Like project templates, file templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a .desktop extension instead of .kdevtemplate, although both are supported.

Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, file templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.

Description file format

The template descriptions files are normal .desktop files. They must contain a General section, as well as one section for each output file. In most cases, the template will have two output files for C++ classes and one output file for other languages. However, using separate user interface files and/or a shared d-pointer hierarchy can cause a class to need more files. Templates in KDevelop allow any number of output files.

Example

An example description for a template with three output files is below

[General]
Name=Private Pointer
Comment=C++ Class with a private D-pointer
Category=C++/Basic
Type=Class
Language=C++
Files=Header,PrivateHeader,Implementation
OptionsFile=options.kcfg

[Header]
Name=Public Header
File=class.h
OutputFile={{ name }}.h

[PrivateHeader]
Name=Private Header
File=class_p.h
OutputFile={{ name }}_p.h

[Implementation]
Name=Implementation
File=class.cpp
OutputFile={{ name }}.cpp

Entries

The Name and Comment entries are the same as in other .desktop files and can be translated.

The Category is used for grouping when showing a list of templates to the user. It should contain at least two levels, separated by slashes. The default templates use the following format: Language/Framework, e.g. C++/Qt.

The Type is optional and can be either Class or Test. In both cases the wizard will add some additional configuration pages and variables.

The Language is optional and can reference a KDevelop language plugin by it's X-KDevelop-Language identifier. When given, the language plugin will be asked to create a class helper, otherwise a default class helper will be chosen.

The OptionsFile entry is optional, using it specifies configuration options for this template. For more information about template options, see Custom options.

A class template description file may also contain an entry with key BaseClasses. It is only used for class templates, and any clases specified in this way are added by default to the inheritance list for the new class. The user can still remove those base classes, or add them manually, so this entry is entirely optional, it only makes things easier for the user. It accepts a list of inheritance statements, separated by commas, like so

; Example for a Qt object
BaseClasses=public QObject
; Example for a KDevelop plugin that implements an interface
BaseClasses=public KDevelop::IPlugin,public KDevelop::IBasicVersionControl
; Example for a Python new-style class
BaseClasses=object

Output files

The Files entry specifies template output files. It is a list of strings, where each element is the same as a name of a group in the description file. The corresponding group has three required entries

  • Name is the user visible file name. It can be translated.
  • File is the path to the input file within the template archive
  • OutputFile is the suggested output file name. The actual name can be set by the user, but this is the default value. It will be converted to lowercase if needed, so don't do in here.

The description file above results in a dialog page such as this

KDevelop template output files dialog
Assistant page for template output files

Variables

Generic

The following variables are passed to all templates, regardless of their type

Variable name Type Description Example value
license String The license header without any comment characters. It can be split into multiple lines. One of the headers listed in KDE Licensing Policy
output_file_foo String The relative path to the output file with identifier foo mynewclass.h
output_file_foo_absolute String The absolute path to the output file foo /home/user/projects/myproject/mynewclass.h

Additionally, values of any custom options exposed by the template are passed as variables.

Classes

The following variables are passed to Class templates

Variable name Type Description Example value
name String Class name without namespaces Example
identifier String The full identifier of the new class, which is composed of namespaces and class name MyProject::Utilities::Example
namespaces StringList List of nested namespaces in which the class is declared [MyProject, Utilities]
description ClassDescription An object containing the class name, base classes, functions and members
baseClasses InheritanceDescriptionList All direct base classes of the new class, containing both the inheritance type and the base class name.
functions FunctionDescriptionList List of all the functions in the new class
members VariableDescriptionList List of all the member variables in the new class

The variables which are passed to class templates are also described in the Expression error: Unrecognized word "extragear". API documentation.

C++ Specific variables

Templates for classes in C++ may make use of some additional variables provided by the language support plugin. They cover finding include files and grouping class functions and members by access specifiers.

Variable name Type Description
public_functions, protected_functions, private_functions FunctionDescriptionList Class functions grouped by access modifiers. These lists do not include slots.
public_slots, protected_slots, private_slots FunctionDescriptionList Qt slots grouped by access modifiers
signals FunctionDescriptionList All Qt signals in the new class
public_members, protected_members, private_members VariableDescriptionList Data members grouped by access modifiers
needs_qobject_macro bool true if the class has at least one signal or slot, false otherwise
included_files StringList List of headers files that need to be included. This variable lists the missing include files for base classes.

Tests

The following variables are passed to Test templates

Variable name Type Description Example value
name String Test name without namespaces MathTest
testCases StringList List of test case names. They do not necessarily begin or end with "test", it is up to templates for frameworks that require such prefixes to add them. [addition, multiplication, negativeNumbers]

Additional templates and filters

To make writing templates easier, KDevelop supplies additional template utilities. They are both in the form of text template, available for including into your own, or additional Grantlee filters.

Templates for inclusion

These templates usually read some variables from the context. Thus, you have to make sure the correct variables are set before including the template. This is normally done using with statements.

{% for f in functions %}
  {% with f.arguments as arguments %}
    {{ f.returnType|default:"void" }} {{ f.name }}({% include "arguments_types_names.txt" %});
  {% endwith %}
{% endfor %}

Includable templates in KDevPlatform are:

Template Required variables Language Description
arguments_names.txt arguments : VariableDescriptionList Weakly-typed languages Comma-separated list of argument names.
arguments_types_names.txt arguments : VariableDescriptionList Strongly-typed languages Comma-separated list of argument types and names.
include_guard_cpp.txt namespaces : StringList C++ Include guard macro, generated from the namespaces and the class name.
namespace_open_cpp.txt namespaces : StringList C++ Opening tag for nested namespaces
namespace_close_cpp.txt namespaces : StringList C++ Closing tag for nested namespaces
namespace_use_cpp.txt namespaces : StringList C++ using namespace statement for nested namespaces

Template filters

KDevPlatform provides an additional filter library. Because filters are implemented in code and not modifiable by users, it is preferred to use template inclusion if possible. These filters are mostly utilities for string operations and are not language specific.

To use them in templates, add {% load kdev_filters %} to the beginning of your template file.

Template filter Description
lines_prepend Takes a string argument and prepends it to every line of the input. It is intended for licenses and other blocks of commented text.
upper_first Converts the first character of input into uppercase, and leaves the rest intact. This is useful for creating accessor functions, and prefixing identifier in general.
camel_case Converts the input from an underscore notation to camel case, starting with a lowercase character.
camel_case_upper Converts the input from an underscore notation to camel case, starting with an uppercase character.
underscores Converts the input to the underscore notations, where words are separated by underscores instead of uppercase letters. The output is entirely lowercase.

Custom options

Templates can expose configuration options to the user prior to the class generation. To do this, add a KConfig XT formatted file into the archive, and specify an OptionsFile entry in the template description file pointing to it.

OptionsFile=options.kcfg
Note
Template options are meant to be used only for small differences in large, complex templates. To reduce the number of necessary clicks, it is preferred to use separate templates instead.


For information about the options file format, see Using KConfig XT. Note that KDevelop only supports a subset of the KConfig XT specification. Only Int, Bool and String types are recognized, options with other types are ignored. Furthermore, only name, type, label and default attributes are used. The default value of options is rendered as a template, so it can include variables.

Here is an example options file that exposes two string options, useful for private pointers

<?xml version="1.0" encoding="UTF-8"?>
<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0
      http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
  <kcfgfile arg="true"/>
  <group name="Private Class">
    <entry name="private_class_name" type="String">
      <label>Private class name</label>
      <default>{{ name }}Private</default>
    </entry>
    <entry name="private_member_name" type="String">
      <label>Private member name</label>
      <default>d</default>
    </entry>
  </group>
</kcfg>

Just before creating the class, KDevelop will show an assistant dialog page, asking for the two options

KDevelop template options dialog
Assistant page for template options

The values the user sets for the two options will be available to the template as variables with names matching the entry names. In the private pointer example, the d-pointer declaration template might look like this

private:
    {{ private_class_name }}* const {{ private_member_name }};

If the user accepts the default values, and the class name is Example, the rendered result of this snippet will be

private:
    ExamplePrivate* const d;