Using Gpp

Basic Gpp

Gpp uses Ant to drive Groovy-style template preprocessing. In order to use Gpp, you should have some familiarity with both Ant and Groovy Templates. Gpp supports all legal VTL and by default, includes the Ant project object in all contexts available to your templates. This allows you to access any project properties defined in your build script.

Accessing Ant Properties within a Template

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("$ant.foo");
  }
}

would become:

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("bar");
  }
}

Any Ant project property can be accessed by the template, regardless how the project property was defined. This means that you can use properties loaded from the environment, property files, or xml.

Adding Gpp To Your Project

Gpp is an Extension

In order to use Gpp in your projects as an extension, you must include the following definitions:

    <typedef resource="groovytools.ant/gpp/typedef.properties" />
    <taskdef resource="groovytools.ant/gpp/taskdef.properties" />

Defining a gppInit target like the one below is one way to do organize this and have these definitions executed using a dependency.

  <target name="gppInit">
    <typedef resource="groovytools.ant/gpp/typedef.properties" />
    <taskdef resource="groovytools.ant/gpp/taskdef.properties" />
  </target>

Gpp as an Antlib

In order to use Gpp in your projects as an Antlib, you must add the following line to your <project> tag:

	xmlns:gpp="antlib:groovytools.ant.gpp"

For example,

  <project 
	name="Groovy Tools - Ant: Groovy Pre-Processor Test" 
	default="all" 
	basedir="."
	xmlns:gpp="antlib:groovytools.ant.gpp"
  </project>

Note that by using Gpp as an Antlib, you do not have to load any Gpp typedef or tasksdef resources explicity and so there is generally no need for an gppInit-like target as shown above.

Simple Preprocessing

<gppcopy> is the easiest way to preprocess text files. Use <gppcopy> (extension) or <gpp:copy> (Antlib) just as you would <copy> to preprocess files in addition to copying them. <gppcopy> supports all of <copy>'s parameters and nested parameters.

Note that when using an Antlib, it is best to also specify the default namespace attribute of tasks and filters to avoid naming problems with nested elements. The default namespace for Gpp tasks and filters is xmlns="antlib:groovytools.ant.gpp"

This example shows how one might use various Ant mechanisms to define project properties and select input sources using a <fileset> and <mapper>:

  <target name="preprocess" depends="gppInit">
    <property name="version" value="1.0.0" >
    <property environment="env" >
    <xmlproperty file="some.xml" >
    <gppcopy todir="output" overwrite="true" >
      <fileset dir="src" includes="*.html.gpp" />
      <mapper type="glob" from="*.html.gpp" to="*.html" />
    </gppcopy>
  </target>

  <target name="preprocess">
    <property name="version" value="1.0.0" >
    <property environment="env" >
    <xmlproperty file="some.xml" >
    <gpp:copy todir="output" overwrite="true" xmlns="antlib:groovytools.ant.gpp"> 
      <fileset dir="src" includes="*.html.gpp" />
      <mapper type="glob" from="*.html.gpp" to="*.html" />
    </gpp:copy>
  </target>

Preprocessing Java Code

<gppjavac> (extension) or <gpp:javac> (Antlib) integrates preprocessing with the java compiler to allow you to treat your Java sources as if they were Groovy Templates to support conditional compilation, macros, and whatever else your imagination can come up with.

<gppjavac> and <gpp:javac> accepts all of <javac>'s parameters and nested parameters, so you can simply replace any usage of <javac> with <gppjavac>.

  <target name="compile" depends="gppInit">
    <gppjavac srcdir="src" destdir="build/classes">
      <classpath refid="some.classpath" />
    </gppjavac>
  </target>

  <target name="compile">
    <gpp:javac srcdir="src" destdir="build/classes" xmlns:gpp="antlib:groovytools.ant.gpp" >
      <classpath refid="some.classpath" />
    </gpp:javac>
  </target>

Preprocessing with Filter Chains

Use the groovytools.ant.gpp.gppfilter filter reader in your filter chains to enable Groovy processing in your streams. The following example is essentially identical to the Simple Processing example shown above, but does it using a filter chain instead.

Note that pre-Ant 1.6, external filter readers were accessed via filterreader and as of Ant 1.6, external filter readers can now be used in the same way as built-ins.

  <target name="copychain" depends="gppInit">
    <copy todir="output" overwrite="true">
      <fileset dir="src">
        <include name="**/*.html.gpp" />
      </fileset>
      <filterchain>
        <filterreader classname="groovytools.ant.gpp.GppFilter" />
      </filterchain>
      <mapper type="glob" from="*.html.gpp" to="*.html" />
    </copy>
  </target>

  <target name="copychain">
    <copy todir="output" overwrite="true">
      <fileset dir="src">
        <include name="**/*.html.gpp" />
      </fileset>
      <filterchain>
        <gpp:filter/>
      </filterchain>
      <mapper type="glob" from="*.html.gpp" to="*.html" />
    </copy>
  </target>

Advanced Gpp

Configuring Gpp

Gpp is configured by using adding a <config> nested parameter to any Gpp task or filter. This nested parameter allows you to pass properties directly to the Groovy Template Context and/or Groovy Template Engine prior to use.

  <target name="preprocess" depends="gppInit">
    <gppcopy todir="output" overwrite="true" >
      <fileset dir="src" includes="*.html.gpp" />
      <mapper type="glob" from="*.html.gpp" to="*.html" />
      <config>
        ...
      </config>
    </gppcopy>
  </target>

  <target name="preprocess" >
    <gpp:copy todir="output" overwrite="true" xmlns:gpp="antlib:groovytools.ant.gpp" >
      <fileset dir="src" includes="*.html.gpp" />
      <mapper type="glob" from="*.html.gpp" to="*.html" />
      <config>
        ...
      </config>
    </gpp:copy>
  </target>

You may also configure a Groovy Template Context and/or Groovy Template Engine using a standalone <gppconfig> (extension) or <gpp:config> (Antlib) element, which can be reference by its refid.

  <target name="gppInit">
    <typedef resource="groovytools.ant/gpp/typedef.properties" />
    <taskdef resource="groovytools.ant/gpp/taskdef.properties" />

    <gppconfig id="gppconfig0">
      ...
    </gppconfig>
  </target>

  <target name="preprocess" depends="gppInit">
    <gppcopy todir="output" overwrite="true" >
      <fileset dir="src" includes="*.html.gpp" />
      <mapper type="glob" from="*.html.gpp" to="*.html" />
      <config refid="gppconfig0" />
    </gppcopy>
  </target>

  <target name="gppInit">
    <gpp:config id="gppconfig0">
      ...
    </gpp:config>
  </target>

  <target name="preprocess" depends="gppInit">
    <gpp:copy todir="output" overwrite="true" xmlns:gpp="antlib:groovytools.ant.gpp" >
      <gpp:fileset dir="src" includes="*.html.gpp" />
      <gpp:mapper type="glob" from="*.html.gpp" to="*.html" />
      <gpp:config refid="gppconfig0" />
    </gpp:copy>
  </target>

Groovy Template Context Configuration

This table describes the Groovy Template Context properties set by default by Gpp in addition to any other properties defined by default by the Groovy Template itself. You can of course override these settings and/or any others in your build scripts:

The <context> nested parameter of <gppconfig> allows you to define properties and tools for use by your templates.

• The <property> nested parameter of <context> is similar to Ant's <property> in that it can be used to define a simple property or to read properties from a file using the extended property file syntax. In addition properties defined in this way are not made Ant project properties and are available in your templates by their simple names, i.e. they do not need to be preceded by ant. to be accessed in your templates.

  Example Groovy Template Context property definitions

  <gppconfig id="gppconfig0" > <context> <property key="foo" value="bar" /> <property file="some.properties" /> </context> </gppconfig>

• The <tool> nested parameter of <context> is used to load utility objects into the context for use by templates. Your tool simply needs to have a public no-arg constructor so that it can be created dynamically by Gpp.

  There are two methods in which to configure tools:

  1. Specify the fully qualified class name of the tool using the className attribute:

     Example of Groovy Template Context tool configured using the className attribute

     <gppconfig id="gppconfig0" > <context> <tool key="mytool" className="foo.bar.MyTool" /> </context> </gppconfig>

  While simpler than the next method, this method does not support configuration of the tool.

  2. Specify the id of a configured data type using the refid attribute:

     Example of a Groovy Template Context tool configured using the refid attribute

     <typedef name="mytool" className="foo.bar.MyTool" > <mytool id="mytool0" someProp="someValue" > <gppconfig id="gppconfig0" > <context> <tool key="mytool" refid="mytool0" /> </context> </gppconfig>

     The advantage of this method over the previous method is that you can configure your tool using Ant's configuration conventions. (Note: Ant dynamically supports any class following its configuration conventions, so it is not necessary for your tool to extend org.apache.tools.ant.types.DataType to make this work.)

  Regardless of which method you use, if your tool supports the method

  	public void setTemplateContext(Map map)
  

  then that method will be invoked, passing your tool the Groovy Template Context instance prior to use.

Copyright ©2007 FoundryLogic, LLC. All rights Reserved.