The ZKM Preprocessor

The ZKM preprocessor processes a ZKM Script before it is parsed and executed. The preprocessor

actions system variables by replacing them with their equivalent value.
actions include directives by replacing them with the contents of the file specified by the directive.

System variables are replaced before include directives are actioned so an include directive may make use of a system variable. Also, an included file may itself contain include directives. An Apache Ant example of the use of system variables in the Apache Ant environment are shown at the bottom of this page.

Note that if you start Zelix KlassMaster™ using the "-v" (ie. verbose) parameter then

the contents of the properties as delivered to Zelix KlassMaster™ and
the expanded ZKM Script

will be written to the Zelix KlassMaster™ log file which is named ZKM_log.txt by default. This can be very handy for debugging purposes.

System Variables

A system variable has the form

%<variable_name>%

The preprocessor looks

firstly in the extra properties (if they were passed in via the build tool API) and then,
the System properties

for a key equal to the variable name. If the key exists then the preprocessor replaces the variable with the corresponding value retrieved from the properties.

For example, if there is a key my_home in the System properties associated with the value /projects/home then the preprocessor takes the script fragment

open "%my_home%/*";

and converts it to

open "/projects/home/*";

System variables can refer to the standard contents of System properties like java.home as %java.home%. You can add your own variables to the System properties by using the java -D<variable_name>=<variable_value> syntax when you start Zelix KlassMaster. For example:

java -Dmy_home=/projects/home -jar ZKM.jar

Note that the command line processor of your operating system may require to use slightly different syntax. For example, in the Windows environment, if you are executing Zelix KlassMaster™ through a batch or command file, then you will need to enclose the name value pair in double quotes as follows.

java -D"my_home=/projects/home" -jar ZKM.jar

If for some reason you cannot use the command line to set System properties then there are two alternative approaches. One is to set the property as an environmental variable and also set the ZKM_LOAD_ENV_VARIABLES=true environmental variable to tell Zelix KlassMaster™ to load all environmental variables into System properties. The second alternative approach is to place the property into a file named "ZKM_System.properties" in the working directory (i.e. "user.dir"). If Zelix KlassMaster™ finds such a property file then it will load its contents into System properties. The command line approach takes precedence over the environmental variable approach and the "ZKM_System.properties" approach takes precedence over the command line approach.

To refer to an environment variables such as PATH use the following syntax to put the value into System properties.

In Windows	`java -D"PATH=%PATH%"`
In Unix	`java -DPATH=$PATH`

Include Directives

An include directive has the form

<% include "<file_name>" %>

where <file_name> is the name of the file to be included. The file name can be relative (to the current directory) or absolute. For example, the include directive

<% include "fragment.txt" %>

Will be replaced by the contents of the file "fragment.txt". As mentioned above, include directives can make use of system variables as in the following example:

<% include "%my_home%/fragment.txt" %>

Apache Ant Example

Below is an example ZKM Script. %MY_CLASSPATH%, %OPEN_CLASSES% and %SAVE_PATH% are system variables. In the Apache Ant environment, the Zelix KlassMaster™ Ant task ZKMTask passes the Ant project properties through to Zelix KlassMaster™ (as the "extra properties" in the Zelix KlassMaster™ build tool API). So, when the ZKM Script is executed, the ZKM Preprocessor will replace the system variables in the script with the value stored under the corresponding key in either the System Properties or the Apache Ant project properties.

<%include "ZKMExclude.txt"%> is an include directive. When the ZKM Script is executed, the ZKM Preprocessor will replace the directive with the contents of the specified file "ZKMExclude.txt".

///// Start ZKM Script TestScript.txt /////
classpath "%MY_CLASSPATH%";

open        "%OPEN_CLASSES%";

<%include "ZKMExclude.txt"%>

obfuscate   changeLogFileOut="ChangeLog.txt"
            obfuscateFlow=aggressive
            encryptStringLiterals=flowObfuscate
            lineNumbers=delete;

saveAll     "%SAVE_PATH%";
///// End ZKM Script TestScript.txt /////

Below are the contents of the file "ZKMExclude.txt". The include directive in the ZKM Script above says that "ZKMExclude.txt" should be included in the script.

///// Start Include file ZKMExclude.txt /////
exclude     *.* public static main{java.lang.String[]);
///// End Include file ZKMExclude.txt /////

Below are the contents of the Apache Ant build file "build.xml". The places where the three system variables are given values (by the addition of key/value pairs to either the Ant project properties or the system properties) appear in bold.

///// Start build.xml /////
<?xml version="1.0"?>

<project name="ZKMTask" default="main" basedir=".">
  <!-- Add a project property -->
  <property name="OPEN_CLASSES" value="\Projects\MyJar.jar"/>

  <path id="ZKM_classpath">
	<fileset dir="\JDK\j2sdkee1.4\lib" includes="j2ee.jar"/>
	<fileset dir="\JDK\WTK21\wtklib\" includes="kenv.zip"/>
  </path>
  <!-- Add a project property -->
  <property name="MY_CLASSPATH" refid="ZKM_classpath"/>

  <taskdef name="ZKM" classname="ZKMTask"/>

  <target name="main">
    <ZKM scriptFileName="\Projects\TestScript.txt" 
          logFileName="ZKM_log1.txt" 
          trimLogFileName="ZKM_TrimLog1.txt" 
          defaultExcludeFileName="defaultExclude0.txt" 
          defaultTrimExcludeFileName="\Projects\defaultTrimExclude0.txt" 
          isParseOnly="false"
          isVerbose="true" 
     >
        <!-- Add a System property -->
        <sysproperty key="SAVE_PATH" value="\Projects\save" />
     </ZKM>
  </target>
</project>
///// End build.xml /////

The ZKM Preprocessor expands the ZKM Script to what appears below. The places where the three system variables were give values appear in bold. The included file contents are shown in italics.

///// Start ZKM Script TestScript.txt /////
classpath "C:\JDK\j2sdkee1.4\lib\j2ee.jar;C:\JDK\WTK21\wtklib\kenv.zip";

open        "\Projects\MyJar.jar";

///// Start Include file ZKMExclude.txt /////
exclude     *.* public static main{java.lang.String[]);
///// End Include file ZKMExclude.txt /////

obfuscate   changeLogFileOut="ChangeLog.txt"
            obfuscateFlow=aggressive
            encryptStringLiterals=flowObfuscate
            lineNumbers=delete;

saveAll     "\Projects\save";
///// End ZKM Script TestScript.txt /////

Privacy

Refunds