Styler

Description

The styler task makes useful combinations of XSLT transformations easy to specify in an Ant build file. Like the built-in task style, styler can apply a single transformation to a set of XML files. But it can also:

• handle multiple transformations, in parallel or pipelined.

• enable transformations that split or merge files

• process non-XML files, especially HTML (based on JTidy) and Simple Outline XML (SOX).

• apply non-XSLT transformation, especially "regular fragmentations"

• use any custom XMLReader or XMLFilter class to handle new file formats and transformation techniques. See the customisation page.

Parameters

As an add-in task, styler must be installed by placing the styler.jar file in the Ant lib directory. The following taskdef is then placed in any build.xml file that uses styler:

<taskdef classname="au.com.Langdale.styler.StylerTask" name="styler"/>

The styler element has no attributes, everything is specified with nested elements as follows.

<styler>
	<fileset ...> ... </fileset>
	<input ...>
		<mapper .../>
	</input>
	<output ...>
		<mapper .../>
	</output>
	<transform ...>
		<mapper .../>
	</transform>
	...
	<param ...>
		<mapper .../>
	</param>
	...
</styler>

fileset

A fileset specifies a set of base files that will be used to drive the task. By default these are the input files. One transformation pipeline is run for each file in the fileset. The input, output and transform script files for each pipeline may be derived from the base file by file mappers.

input

An optional input element maps each base file to an input file. If omitted, each base file is taken as an input file. The type attribute or, by default, the file extension selects the parser that will be used. See the file type table below.

output

An output element maps each base file to an output file. The type attribute or, by default, the file extension selects the serializer that will be used. See the file type table below.

transform

A transform element specifies a transformation. This element selects the type of transformation and, if applicable, a rule or script file. The latter may be mapped from the base file name. Multiple transform elements may be used to specify a pipeline. That is, the output of the first transformation becomes the input of the second and so on.

param

A param element specifies a stylesheet parameter and its value. Any number of parameters may be specified and each parameter is passed to every transformation. The parameter value may be a string or an URL mapped from the base file.

The input, output, transform, and param elements each take an optional, nested mapper element (see core types) and the following attributes.

Input, Output and Transform Types

The type attribute or, if omitted, the file name extension determines how each input and transform file is parsed and how each output file is generated. For transforms the type also selects the transformer implementation. The following table lists the built-in alternatives but these may be extended (see below).

Processors to handle additional file and transform types may be added relatively easily if they have SAX interfaces. See the customisation page.

Examples

A Pipeline

This example processes each XML file in the testdata directory to produce a file of the same name in the testout directory. Each file is transformed by the select_data.xslt stylesheet followed by the format_report.xslt stylesheet. Its often easier to design each stylesheet to do just one thing and chain them in this way.

		<styler>
			<fileset dir="testdata">
				<include name="*.xml"/>
			</fileset>
			<transform file="select_data.xslt"/>
			<transform file="format_report.xslt"/>
			<output dir="testout"/>
		</styler>

Parallel Transforms

This example runs each stylesheet found in the skins directory to transform the same file, log.xml. A parameter, user-name, is passed to each stylesheet. The results are written as HTML in the views directory.

		<styler>
			<fileset dir="skins">
				<include name="*.xslt"/>
			</fileset>
			<input file="log.xml"/>
			<transform dir="skins"/>
			<param name="user-name" value="${user}"/>
			<output dir="results">
				<mapper type="glob" from="*.xslt" to="*.html"/>
			</output>
		</styler>

File Merging

This example merges each input file *Xml with a corresponding file *.extra producing a file in the merged directory with the same name as the input.

		<styler>
			<fileset dir=".">
				<include name="*Xml"/>
			</fileset>
			<transform file="merge.xslt"/>
			<param name="url-to-merge" dir=".">
				<mapper type="glob" from="*Xml" to="*Extra"/>
			</param>
			<output dir="merged"/>
		</pipe>

The merge.xslt file might contain something like the following in one of its templates:

		<xsl:apply-templates select="document($url-to-merge)" />

Screen Scraping

This example parses HTML files, then repairs all site-relative URL's to point at the new document directory. The document directory is passed by the task to the stylesheet as a parameter, called base, in the form of an URL.

		<styler>
			<fileset dir="site">
				<include name="*.html"/>
			</fileset>
			<transform file="fix-base.xslt"/>
			<param name="base" file="cleaned"/>
			<output dir="cleaned"/>
		</styler>

The fix-base stylesheet might contain a template something like the following:

	<xsl:template match="@href|@src">
		<xsl:attribute name="{name()}">
			<xsl:if test="starts-with(.,'/')">
				<xsl:value-of select="$base"/>
			</xsl:if>
			<xsl:value-of select="."/>
		</xsl:attribute>
	</xsl:template>

Converting Custom Languages

The final example parses a Rational Rose model file, extracts modelling data, cross-references it, and encodes it in a standard schema language, RDF. The extension used for the input file tells styler to use the petal parser instead of a standard XML parser. (The stylesheets used here can be found at http://xmodel.sourceforge.net.)

		<styler>
			<fileset dir=".">
				<include name="*Mdl"/>
			</fileset>
			<transform file="PetalClasses.xslt"/>
			<transform file="CrossRef.xslt"/>
			<transform file="Petal2RDF.xslt"/>
			<output dir=".">
				<mapper type="glob" from="*Mdl" to="*.rdf"/>
			</output>
		</styler>

Command Line

The styler jar file provides a command line interface that is sometimes useful. This has the following syntax:

Java -cp styler.jar au.com.Langdale.styler.Pipe \
	input-file transform-file1 transform-file2 ... output-file

The input-file and output-file follow the conventions given above. Each transform-file must end in .xslt. A single pipeline is run parsing the input file and generating the output file.

Notes and Limitations

Up-to-Date Files

The task does not take into account whether the outputs are up-to-date with respect to the input files and stylesheets. The output files are unconditionally regenerated.

File types

The type of the input file is deduced from its name whenever no type attribute is supplied. This is convenient although may go against the usual ant philosophy.