KDevelop5/File template specification: Difference between revisions

    From KDE TechBase
    Line 62: Line 62:
    * <tt>File</tt> is the path to the input file within the template archive
    * <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.
    * <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 ===

    Revision as of 12:47, 10 July 2012

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


    Template language

    Class 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, 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 .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, 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.

    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++
    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 can contain more than one level, separated by slashes, but the first level should always be the language name.

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

    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

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

    Additional templates and filters

    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;