Template DSL

The template DSL allows to create text based output using data from the declaration and configuration DSL. It follows ideas from other templating DSLs and allow to place variables within a text body. The language supports text templates that return a formatted string and file templates that create a file and store its generated text in that file.

Note: The DSL is in an early stage, and certain functions may not work as intended.

Data Model

Templates access a fused data model based on the declaration and configuration value. In general the data model is generated based on the declaration model and its declarations of features and configuration options. Then the values set and features selected in the configuration model are added to the model.

<<Insert Data Model Figure>>

Header

A template file can contain multiple templates, but is always tailored for one scientific model. Therefore, the header refers to Declaration model.

for uvic

File Template

File templates are indicated by the keyword file followed by an expression to define file the name. After the colon follows the template body. That can be any template expression, i.e., variable names, loops, conditions and rich text starting with ”’ and ending with ”’.

file "mk.in" : '''
# Add version directory for use
# for Uvic_ESCM 2.9 version reference run with the opem extension

### Add your directory path here:
Version_Directory = #{general.version_directory}

Model_Options =
#{for features use featureTemplate(it)}
'''

Text Template

Text templates take zero or more parameters and produce a text string as result. The example below is named printSourceDirectory and has two parameters. The first parameter is named filename and is of type string. The second is called number and of type int.

The body of the text template works similar to the body file template with the difference that the defined parameter are also available in addition to the configuration information. The details of the expression in the body are introduced below.

template printSourceDirectory(string filename, int number) '''Source_Directory(#{number}) = #{filename}'''

Template Expressions

A template expression can be composed of elementary elements such as values, like strings, numbers and enumerals, that can be combined in with operations, functions and rich strings. A rich string is a special string that can contain inline variables in text that are replaced at runtime with the specific value. In the following, we explain the basic elements, functions, rich strings, operators, and control structures.

Values

The CP-DSL supports different basic data types and corresponding values.

  • string = string/text value
  • float = floating point values which use double precision floating point values internally
  • int = integer values which use 64 bit integer values internally
  • boolean = boolean value
  • enumerals = user defined numerals

The CP-DSL also supports range types and file as a datatype. However, as values these are specified with numbers and strings respectively. Strings are specified with double or single quotes (“double quote”, ‘single quote’), numbers as integers or any float notations, e.g., 1.23 or 1.0e-10.

Configuration Data

Configuration data is accessible from the template language following the tree structure defined in the declaration model. This means on top level all global features and parameter groups are directly accessible by name. For example, the UVic declaration model defines the parameter groups general, source, and data. They can referred to by name. In addition, it is possible to access their attributes with the point notation, i.e., element-name.attribute-name. For example, general.executable_file refers to the attribute executable_file of the parameter group general.

In addition to defined attributes, there are also synthetic attributes which are inferred from the configuration data. There are different synthetic attributes for parameter groups, parameters, and features.

Global Level

  • name = name of the configuration
  • model = name of the model
  • groups = all groups as a list/array
  • features = all features as a list/array

Parameter

  • name = name of the parameter
  • description = description information of the parameter
  • value = value of the parameter (in many cases this can be omitted and just the reference to the parameter is sufficient.

Parameter Group

  • name = name of the parameter group
  • description = description information of the parameter group
  • parameters = all parameters as a list/array

Feature

  • name = name of the feature
  • description = description information of the feature
  • enabled = true if the feature have been selected in the configuration file
  • groups = all parameter groups belonging to the feature as a list/array

Functions

functions

Rich Strings

Rich string

Iterate Lists

template groupTemplate(Group group) ''' &#{group.name} #{for group.parameters join ", " use parameterTemplate(it)} /'''

Conditionals






Switches





Value switches





template codeExtensionsTemplate(FileType type, int count)
	switch type
		case f90 '''Code_Extension(#{count}) = f90'''
		case f '''Code_Extension(#{count}) = f'''
	end





Type switches





template valueTemplate(top value)
	switch value
		is float value
		is int value
		is boolean '''.#{value}.'''
		is string ''''#{value}' '''
		is float[] '''#{for value join "," use valueTemplate(it)}'''
		default '''Error'''
	end





Calling Text Templates





Text templates can be called in expressions with the keyword use followed by parameters in enclosed in brackets, e.g., featureTemplate(param1, param2).





template parameterTemplate(Parameter parameter) '''#{parameter.name}=#{use valueTemplate(parameter.value)}'''