Templates needed for a Processed Pod.

Table of Contents

Template Engine AutodetectionMinimum SetTest-TemplatesVerification utilityUsageData structures accepted by templatesStructure specification syntaxExamplesParameters of required templatesNotes

This describes the template set for the ProcessedPod renderer, the templating engines that can be used, the Test-Template functions, and the test-templates verification utility.

The templating part of Raku-Pod-Render is separated into a Templating module RenderPod::Templating. It is written to allow for other templating engines to be added. Currently the following Engines are available in this distribution:

• Mustache

• Raku Closure (a templating system designed for Raku-Pod-Render)

• Cro Templates

Template Engine Autodetection

Templates are written to be interpretted by a templating engine. The Templating module in this distribution has been written to allow for other engines to be added. It is best to look at the module to see how this is done.

The first minimum set of templates is loaded and an autodetect function determines which engine to use. Subsequent templates added by plugins must use the same template engine.

The template engine is determined in two ways:

• The hash (normally loaded from a file) containing the minimum set of templates may contain the key _templater, which must have a String value that is the name of the class implementing the Templating Engine. For the default engines, these are

MustacheMustacheTemplater

Raku ClosureRakuClosureTemplater

Cro TemplatesCroTemplater

Minimum Set

The minimum set of templates is block-code comment declarator defn dlist-end dlist-start escaped footnotes format-b format-c format-i format-k format-l format-n format-p format-r format-t format-u format-x glossary heading item list meta named output para pod raw source-wrap table toc.

Almost all of these templates expect a [parameter to be rendered](Parameters of required templates.md). The test functions will check the templates for the parameters to be returned.

Test-Templates

These subs are intended for use in a TAP context. They can be applied as follows

use Test;
use RenderPod::Test-Templates;
%templates = EVALFILE "templates/basic-templates.raku";
templates-present %templates, 'basic file contains minimum set of templates';

multi sub templates-present( Hash %templates, Str $description = 'minimum templates present' )Short for 'are all minimum templates present in the hash'. Takes a hash, whose keys are template names. Checks the key-names contains all of the required templates.

multi sub templates-match( Hash %templates, Str $description = 'minimum templates match the specification' )Checks whether the required templates render all parameters. Fails if any parameters are not rendered. If a parameter should not appear, render it as a comment or invisible element, so that it is in the output for it to match the specification, but not be seen when finally rendered. If there are more templates in the hash than are in the specifications, they are ignored.

multi sub extra-templates-match( Hash %templates, Hash %specifications, Str $description = 'extra templates match')Check that templates in %templates match the specifications in %specifications. True if the templates match, AND all the templates in %templates are specified in %specifications.

Verification utility

The test-templates utility helps to verify whether all the parameters specified for a template are in fact rendered by the template.

A template developer may decide not to render a parameter provided by ProcessedPod to the template. The verification tool will flag this with a warning.

If the minimum set of templates is not provided, the renderer will throw an error.

Usage

This testing tool has the structure of the minimum template set coded into it. It is called as

test-templates --extra='filename-of-custom-template-structure.raku' --verbosity=2 'filename-of-templates.raku'

• --extra (optional, default: Any )

This is a Raku compilable program that returns a Hash with the structure of the key, more below.

• --verbosity (optional, default: 0 )

An integer that produces more information for higher values:

*  = 0 returns 0 if no errors, or list templates with errors

*  = 1 0 + parameters sent, sub-keys not returned

*  = 2 1 + sub-keys found in error templates

*  = 3 2 + full response for error templates

*  = 4 all templates with sub-key returns

*  = 5 5 + full response for all templates

• 'filename-of-templates.raku' (mandatory, string)

A Raku compilable program that returns a Hash contains all the minimum templates as keys pointing subroutines.

If the minimum set of templates is not provided in filename-of-templates.raku, a MissingTemplates exception will be thrown.

Since all the templates are provided to all the templates, it is recommended to use sub-templates within the minimum set to simplify the code.

Data structures accepted by templates

All templates, whether Mustache or RakuClosure, expect PodRender to present them with parameters with one of the following data structures

This specification allows for test-templates to create create random data for template and to test whether it is returned.

However, the developer has to provide information about what each template is expecting.

Structure specification syntax

As can be seen from the table in [Data structures accepted by templates](Data structures accepted by templates.md), a parameter value, whether directly expected from a key, or as part of an Array or Hash, may be either 'Bool' or 'Str'. These are given as Str values, eg.

'title' => 'Str',
'heading' => { :text('Str'), :level('Str'), :is-header('Bool') }

A Hash element is specified as a Hash, using { ... } as shown above, and an Array is specified using [ ... ] , eg.

'table' => { :rows( [ 'Str', ] ) }

Examples

Examples of a set of RakuClosureTemplates can be found in the resources directory of the distribution, as

• closure-temp.raku is an array of templates, including a custom image template. The templates are designed for Pod::To::HTML2.

• extra-test.raku is a hash with the template structure for the image template.

Parameters of required templates

These are the parameters for the required templates for ProcessedPod, and helper templates in Pod::To::HTML2

Required templates and their normal parameters

Helper templates in Pod::To::HTML2

Notes

• All blocks pass any extra config parameters to the template, eg., 'class', as well but if a developer passes configuration data to a block, she will be able to use it in the template.

• The template does not need to render a parameter, but the template verification tool will issue a warning if it does not.

• required templates are called by the Renderer, but it is cleaner to break the template into sections. The templates for Pod::To::HTML2 do this, with footer, header and head-block templates, all of which are called by file-wrap. This structure is shown in the table above.

Rendered from PodTemplates at 2022-06-13T16:49:51Z