DPML
Using Global Filters
HomeUtilitiesStationMetro
Global Filters

Filters are used to replace tokens in source code with assigned values and are applied during copy operations when filtering is enabled. This tutorial demonstrates this feature by extending our project definition to include such a filter specification.

index.xml

Any number of filters can be declared within an enclosing filters element. The filters element may be declared within a project or module defintion. In the following example we are declaring a single filter inside the project defintion which declares a filter token of MESSAGE and a substition value equal to the expansion of the ${message} property value. As such, any copy operation declared in the build file that has filtering enabled will result in the substitution of the toke @MESSAGE@ with the assigned value.

<?xml version="1.0" encoding="ISO-8859-1"?>
<index xmlns="dpml:library">

  <project name="demo" basedir=".">
    <properties>
      <property name="location" value="New York"/>
      <property name="message" value="Hello for ${user.name} in ${location}"/>
    </properties>
    <filters>
      <filter token="MESSAGE" value="${message}"/>
    </filters>
  </project>

</index>
build.xml

To demonstrate the above we have updated the build file to copy a file named src/DEMO.TXT to target/RESULT.TXT. The DEMO.TXT file contains the @MESSAGE@ token and the resulting RESULT.TXT file should contain the expanded value. The build target validates this by loading the result file and echoing its contents.

<project name="demo" default="install">

  <target name="init">
    <property name="src" location="${basedir}/src"/>
    <property name="target" location="${basedir}/target"/>
  </target>

  <target name="clean" depends="init">
    <delete dir="${target}"/>
  </target>

  <target name="build" depends="init,clean">
    <mkdir dir="${target}"/>
    <copy file="${src}/DEMO.TXT" toFile="${target}/RESULT.TXT" filtering="true"/>
    <loadfile srcFile="${target}/RESULT.TXT" property="result"/>
    <echo message="${result}"/>
  </target>

  <target name="install" depends="build"/>

</project>
Building the project ..
$ cd tutorials\tooling\filters
$ build

-------------------------------------------------------------------------
demo#SNAPSHOT
-------------------------------------------------------------------------

init:

clean:

build:
    [mkdir] Created dir: D:\dpml\tutorials\tooling\filters\target
     [copy] Copying 1 file to D:\dpml\tutorials\tooling\filters\target
     [echo]
     [echo] The message is Hello from mcconnell in New York.

install:

BUILD SUCCESSFUL
Total time: 0 seconds

$
        
Summary

Property and filter declarations demonstrated here deal with resonably simple value assignments (either direct values or values resolved by dereferencing symbolic values). However - when dealing with large numbers of projects you will frequently need to reference features of another project in the declaration of a local property of feature value. Before addressing this subject we need to introduce multiple projects and the support that Depot provides in build sequencing.

The next tutorial introduces type production declarations in a project definition.