Table of Contents

API

1. Template Languages

Trunklet is designed to allow for multiple different templating languages to be defined. This allows working in whatever template language is most comfortable to you.

To support maximum flexibility, Trunklet uses the Variant data type for defining both templates and sets of parameters to use with a template. It is up to the template language implementation to decide what actual data type to use.

1.1. template_language__add

template_language__add(
  language_name varchar(100)
  , parameter_type regtype
  , template_type regtype
  , process_function_options text
  , process_function_body text
  , extract_parameters_options text
  , extract_parameters_body text
) RETURNS void

PERMISSIONS: restricted to superuser. Please contact me if this doesn’t work for you.

Add a new template language.

language_name
must be non-blank and may not start or end with whitespace.

parameter_type
template_type
These are the data types that the language expects parameters and templates to be in.

process_function_options
process_function_body
Besides supplying a name for your language, you must also create a process() function. Trunklet will actually create the function for you. In particular, it will generate a name for the function. process_function_options are the options for the function (things like STRICT, LANGUAGE, etc). process_function_body is the body of the function.

The function must accept (template variant(trunklet_template), parameters variant(trunklet_parameter)[]), where template is the template definition and parameters is an array of parameters. If an array of parameters doesn’t make sense (ie: if parameters are specified via JSON) then the function should verify there is only one element in the array (TODO: allow telling Trunklet that this is the case and have it enforce this). The function must return text. (Should we also support returning variant? Presumably all templates are ultimately text, so I don’t think so.)

Essentially, the SQL that trunklet runs is

CREATE FUNCTION <name>(template variant(trunklet_template), parameters variant(trunklet_parameter)[])
RETURNS text
<process_function_options>
AS <process_function_body>

extract_parameters_options
extract_parameters_body
Equivalent to the process_function parameters, except these support the [extract_parameters] function. Note that this function must also accept a text array of parameter names to extract. See [extract_parameters] for details.

1.2. template_language__remove (TODO)

template_language__remove( language_name varchar(100) ) RETURNS void

Remove an existing template language. This will fail if there are any stored templates.

1.3. template_language

VIEW template_language
  language_name varchar(100)
  , process_function_options text
  , process_function_body text
  , extract_parameters_options text
  , extract_parameters_body text

Returns information about registered template languages.

2. Storing Templates

You can have Trunklet store frequently used templates for you, so that you can refer to them with just a name.

2.1. template__add

template__add( language_name text, template_name text[, template_version int], template variant(trunklet_template) ) RETURNS int

Store a template. template_name and template_version must be unique across ALL templates, regardless of language. Any template with _ as the first character will be considered to be “hidden”, meaning it will not show up in template listings.

If template_version is not specified it defaults to 1.

Returns an ID for the stored template.

Note
 In the future we may add a template_specification type or something similar that allows for something finer-grained than a text field for identifying templates. Ideally this would even allow for users to add their own fields. Ideas on this welcome.

2.2. template__remove

template__remove( language_name text, template_name text[, template_version int] ) RETURNS void
template__remove( template_id int ) RETURNS void

Remove the specified template. template_version defaults to 1 if not specified.

2.3. template__dependency__add

template__dependency__add( table_name text, field_name text ) RETURNS void

An expected use for storing templates is to allow other parts of a database to store templates and be able to refer to them later. That code may need to store a template identifier in a table. If it does so, you would want to have a foreign key that references the table that Trunklet uses to store templates in. template__dependency__add allows you to create such a dependency. Internally, it simply creates the required foreign key constraint. Note that any role executing this must be granted the trunklet__dependency role.

2.4. template__dependency__remove

template__dependency__remove( table_name text, field_name text ) RETURNS void

This function removes an existing template dependency.

3. Usage Functions

These are the functions you will use most commonly when dealing with templates. Most of these functions have two versions; one that accepts the name of a template language and an actual template, and a second that accepts a template name and an optional template version. If the template version is omitted the version of the template with the highest version number is used.

4. Using templates

These are the functions for actually using templates. Generally they have variations for both stored and ad-hoc templates.

Important
 These function treats a missing version number differently than the functions for [Storing_templates] do. Don’t get the two confused!

4.1. process

process_language( language_name text, template variant(trunklet_template), parameters variant(trunklet_parameter) ) RETURNS text
TODO: process_language_array( language_name text, template variant(trunklet_template), parameters variant(trunklet_parameter)[] ) RETURNS text[]
process( template_name text[, template_version int], parameters variant(trunklet_parameter) ) RETURNS text
TODO: process_array( template_name text[, template_version int], parameters variant(trunklet_parameter)[] ) RETURNS text[]

Process the specified template and return the resulting text. The _array versions are the same, except they will accept an array of parameters. Note that the _array versions must be passed a true array and vice-versa. This is especially important with named templates; you must know ahead of time what the template is expecting.

Note
 We don’t simply overload process( language_name text, template variant(trunklet_template), parameters variant(trunklet_parameter) ) for the _array variation because we can’t do that with the version that accepts a template name. It’s better to be unambiguous here.

4.2. execute

execute_language( language_name text, template variant(trunklet_template), parameters variant(trunklet_parameter) ) RETURNS void
execute_language( language_name text, template variant(trunklet_template), parameters variant(trunklet_parameter)[] ) RETURNS void
execute( template_name text[, template_version int], parameters variant(trunklet_parameter) ) RETURNS void

Call [process] and execute the result as SQL. This is an easy way to generate and execute dynamic commands.

Note
 Because these functions always return void we can overload the array version instead of requiring separate execute_array functions. We might add explicit _array versions in the future. The version that accepts a named template will always do the correct thing.

4.3. execute_into

execute_into_language( language_name text, template variant(trunklet_template), parameters variant(trunklet_parameter) ) RETURNS variant(trunklet_return)
execute_into_language_array( language_name text, template variant(trunklet_template)[], parameters variant(trunklet_parameter) ) RETURNS variant(trunklet_return)[]
execute_into( template_name text[, template_version int], parameters variant(trunklet_parameter) ) RETURNS variant(trunklet_return)
execute_into_array( template_name text[, template_version int], parameters variant(trunklet_parameter) ) RETURNS variant(trunklet_return)[]

This is the same as [execute], except we capture the results of the executed SQL. Note that variant currently does not support returning record types.

4.4. extract_parameters

extract_parameters( template_name text[, template_version int], parameters variant(trunklet_parameter), extract_list text[] ) RETURNS variant(trunklet_parameter)

Return a specified set of parameter values. This takes parameters and filters it to only return parameters whose name matches one of the names in extract_list.

5. Variant Modifier

The variant type supports specifying a type modifer. Trunklet makes use of 3 specific variant modifiers:

  • trunklet_template: Used to store templates

  • trunklet_parameter: Used to store parameters for templates

  • trunklet_return: Used to return data from an execute_into

TODOs

Provide a means for callers to pass a set of options to template language functions.

Copyright

Copyright (c) 2015 Jim C. Nasby.