doc.developer.script-grammar-v2.0.html Maven / Gradle / Ivy
Taskscript Grammar version 2.0
Daisy Pipeline Taskscript Grammar version 2.0
Latest update: 2007-03-22
This document describes the new (version 2.0) script grammar
for the Daisy Pipeline.
Contents
- Introduction
- Identification
- Name, description and documentation
- Properties
- Script Parameters
- Functions
- Tasks
- Full documentation
- Example
- Notes
Introduction
The Daisy Pipeline executes Jobs. Each Job in its turn is defined in a taskScript (or Script, for short) file. The taskScript
defines what Transformers are executed in what order, and it defines what parameters are sent to the Transformers as
they execute.
The taskscript is an XML grammar. A compound RelaxNG+Schematron Schema1 exists to validate it. The Taskscript file is parsed (and validated)
by the Pipeline core at initialization time.
Identification
The version attribute on the taskScript root element
has the value 2.0 indicating that this is a version 2.0 task script.
The name attribute contains a name of the script that is unique within
the Daisy Pipeline.
<taskScript version="2.0" name="scriptname">
TBD. Naming convention
Name, description and documentation
The nicename element contains the human readable name of the script.
The name is normally up to five words long.
The description element contains a longer description of the script,
perhaps up to five sentences long.
The documentation element carries a uri attribute that contains a relative link to end user documentation of the task.
Normally, the destination of the URI is an XHTML document in the /doc/scripts subfolder.
A template for this XHTML document exists in the /doc/templates folder.
<nicename>Script Nicename</nicename>
<description>Script Description</description>
<documentation uri="../../doc/scripts/doc.html" />
Properties
Properties are variables internal to the script. A user running a script
is not able to set the value of a property.
<property name="propname" value="propvalue"/>
Using properties
Properties (as well as parameters) are referenced from other parts of the script
by using the ${name} syntax, where name is the name of a
property (or parameter).
Property references are allowed in other property or parameter values and in the
value element when defining parameter values for tasks.
Script Parameters
Script parameters can be set by the user before running the script.
The name attribute on the parameter element contains
the name of the parameter while the nicename element contains the
name suitable to be shown in a GUI. The description element contains
a slightly longer description of the parameter suitable to be shown in a tooltip
in a GUI.
Script parameters can either be required or optional, as indicated by the
required attribute on the parameter element. A required
parameter must be supplied by the user when the script is run. If the user does not
supply the value of an optional parameter, the value attribute is used
as a default value.
There are currently seven different datatypes available for script parameters.
File
The mime attribute contains the mime type of the file. The value of the
type attribute is either input or output.
Depending on this value, a GUI can display either an open or a save file dialog.
<parameter name="fileParam" value="" required="true">
<nicename>Input File</nicename>
<description>A DTBook file in 2005-1 or 2005-2 format</description>
<datatype>
<file mime="application/xml" type="input"/>
</datatype>
</parameter>
Files
The mime attribute contains the mime type of the files. The value of the
type attribute is either input or output.
Depending on this value, a GUI can display either an open or a save file dialog.
<parameter name="fileParam" value="" required="true">
<nicename>Input Files</nicename>
<description>One or several DTBook files in 2005-1 or 2005-2 format</description>
<datatype>
<files mime="application/xml" type="input"/>
</datatype>
</parameter>
Directory
The value of the type attribute is either input or
output. Depending on this value, a GUI can display either an open or
a save directory dialog.
<parameter name="directoryParam" value="" required="true">
<nicename>Output Directory</nicename>
<description>The directory the generated book will be placed in</description>
<datatype>
<directory type="output"/>
</datatype>
</parameter>
String
The optional regex attribute contains a regular expression used to
validate the values set by the user.
<parameter name="stringParam" value="" required="true">
<nicename>Identifier</nicename>
<description>The identifier of the book</description>
<datatype>
<string regex="C[0-9]{5}"/>
</datatype>
</parameter>
Boolean
The optional true and false attributes are used to define the
values of the parameter when the parameter is set or unset. The default value for
the attributes are true and false, respectively.
<parameter name="booleanParam" value="1" required="false">
<nicename>Include CSS</nicename>
<description>Include a CSS file reference in the generated document</description>
<datatype>
<boolean true="1" false="0"/>
</datatype>
</parameter>
Integer
The optional min and max attributes set the allowed minimum
and maximum values for this integer. The default minimum value is -231 and
the default maximum value is 231-1.
<parameter name="integerParam" value="680" required="false">
<nicename>Split size</nicename>
<description>The maximum number of MB for each volume of the book</description>
<datatype>
<integer min="17" max="4711"/>
</datatype>
</parameter>
Enum
Each allowed value of the enumeration is defined in its own item subelement.
Each item has a value attribute describing the value and a
nicename attribute suitable for displaying in a GUI.
<parameter name="enumParam" value="o" required="true">
<nicename>Favorite fruit</nicename>
<description>What's your favorite fruit?</description>
<datatype>
<enum>
<item nicename="Apples" value="a"/>
<item nicename="Oranges" value="o"/>
<item nicename="Other" value="ot"/>
</enum>
</datatype>
</parameter>
Functions
Script functions operate on all kinds of script properties, such as parameters. Functions
use the same syntax as properties, but with the name of the function between the dollar
sign and the open curly brace.
...
<value>$functionName{propertyName}</value>
...
The currently defined functions are:
- filename
- Returns the filename portion of a file path
- parent
- Returns the parent directory of a path
Tasks
A task defines the name of a transformer and the parameter values for running it.
Each task element has two attributes: the name attribute
defines the name of the transformer to run while the optional interactive
attribute tells whether the transformer should be run in interactive mode or not, the
default value being false.
Each task also has a set of parameters, where each parameter element has
two subelements. The name element defines the name of a parameter while
the value element defines its value.
<task name="se_tpb_nccNcxOnly">
<parameter>
<name>manifest</name>
<value>${input}</value>
</parameter>
<parameter>
<name>outDir</name>
<value>${outputPath}</value>
</parameter>
</task>
Example
<?xml version="1.0" encoding="utf-8"?>
<taskScript version="2.0" name="dtbook2xhtml">
<nicename>DTBook to XHTML</nicename>
<description>Validates a DTBook file and converts it to XHTML</description>
<parameter name="input" value="" required="true">
<nicename>Input File</nicename>
<description>The DTBook input file</description>
<datatype>
<file mime="application/x-dtbook+xml" type="input"/>
</datatype>
</parameter>
<parameter name="output" value="" required="true">
<nicename>Output File</nicename>
<description>The XHTML output file</description>
<datatype>
<file mime="application/xhtml+xml" type="output"/>
</datatype>
</parameter>
<task name="int_daisy_validator">
<parameter>
<name>input</name>
<value>${input}</value>
</parameter>
</task>
<task name="uk_rnib_dtbook2xhtml">
<parameter>
<name>xml</name>
<value>${input}</value>
</parameter>
<parameter>
<name>out</name>
<value>${output}</value>
</parameter>
</task>
</taskScript>
Appendix. RelaxNG+Schematron grammar for taskScript
Notes
1. The schema lives in the org.daisy.pipeline.core.script package. If you do not have access to the source code, browse the SVN online.