Overview

Is it possible to set a variable from an Ant script, like xslt? Yes! Starting with version 2.07 (1g).

• xvcl task - Equivalent to a command line for the XVCL processor.
• set tag - set command.
• setmulti tag - set-multi command.
• var attribute - var attribute.
• value - value attribute. Supports ${property-name}. Supports ?@variable-name?.
• deferEvaluation attribute - The defer-evaluation attribute.

System variables

The following variables are set automatically by the XVCL processor:

• xvcl.system - A list of system variables.
• xvcl.starttime - Timestamp at the start of the XVCL processor.
• xvcl.version - Version of XVCL Processor.
• xvcl.appendoutput - Set when the appendOutput option is true.
• xvcl.beautifyoutput - Set when the beautifyOutput option is true.
• xvcl.includetraces - Set when the includeTraceInfo option is true.
• xvcl.loggeneratedfiles - Set when the logGeneratedFiles option is true.
• xvcl.namespace (?) - Set when namespace option is true.
• xvcl.verifyonly - Set when the verifyOnly option is true.
• xvcl.verbose - Set when the verbose option is true.
• xvcl.spc - Name of SPC.
• xvcl.env - List of system properties.
• xvcl.env.n - System property n.
• xvcl.frame.location - Location of current frame.
• xvcl.frame.name - Name of current frame.
• xvcl.frame.language - Language of current frame.
• xvcl.frame.outdir - Output directory of current frame.
• xvcl.frame.outfile - Output file of current frame.

System variables (3.5.0)

 $XVCL.SPC - SPC
 $XVCL.PROJECT - project
 $XVCL.VERSION - version.
 $XVCL.BEAUTIFYOUTPUT - Option B.
 $XVCL.LOGGENERATEDFILES - Option L.
 $XVCL.INCLUDETRACES - Option T.
 $XVCL.VERIFYONLY - Option V.
 $XVCL.ENFORCENAMESPACE - Option N.

 $XVCL.DATE - Current date.
 $XVCL.TIME - Current time.
 $XVCL.TIMESTAMP - Current time in milliseconds.
 $XVCL.FRAMELOCATION - frame.location.
 $XVCL.FRAMENAME - frame.name
 $XVCL.USERNAME - User name.
 $XVCL.ENV.n - System property n.
 $XVCL.MESSAGE
 $XVCL.EXCEPTION

Example: Simple variable

As you may know, the property tag is used to set a property in an Ant script. The property tag is not part of the XVCL specification. It is part of Ant.

 ----- build.xml -----
 <property name="dest" value="build/src"/>

In an x-frame, the set tag is used to set a variable. The var attribute is the name of a variable. The value attribute gives a variable its value. The optional defer-evaluation tag controls evaluation: no (immediate) or yes (deferred).

 ----- spc.xvcl -----
 <set var="text-1" value="demo"/>
 <set var="text-2" value="?@text-1?" defer-evaluation="no"/>
 <set var="text-3" value="?@text-1?" defer-evaluation="yes"/>

A variable in an x-frame is similar to a property in Ant. Unlike a property, a variable can be removed with a reset tag or replaced with a set tag.

 ----- build.xml -----
 <set var="text-1" value="demo"/>
 <set var="text-2" value="?@text-1?" deferEvaluation="no"/>
 <set var="text-3" value="?@text-1?" deferEvaluation="yes"/>

Within the XVCLAntTask task, xvcl, a list of set and setmulti tags is supported. Just like the set tag in an x-frame, use the set tag to set a variable. The var attribute is its name. The value attribute is its value. In an Ant script, the value attribute can reference an Ant property with ${property-name}, the usual Ant notation.

 ----- build.xml -----
 <target name="emit" depends="taskdef">
   <xvcl spc="spc.xvcl">
     <set var="product-name" value="Example"/>
     <set var="dest" value="${dest}"/>
   </xvcl>
 </target>

In turn, an expression in XVCL can reference a variable with ?@variable-name?, the usual XVCL notation. The following x-frame emits a list of system properties to an spc.txt file to the "build/src" directory.

 ----- spc.xvcl -----
 <x-frame name="spc.xvcl" outdir="?@dest?" outfile="spc.txt">
 Product Name: <value-of expr="?@product-name?"/>
 <while using-items-in="xvcl.system">
 <value-of expr="?@xvcl.system?"/>: <value-of expr="?@@xvcl.system?"/>
 </while>
 </x-frame>

Example: Varible reference

Variables are evaluated in the order in which they appear in an Ant script. When the name variable is set in an Ant script, it references version, another variable. It is evaluated immediately.

 ----- build.xml -----
 <xvcl spc="spc.xvcl">
   <set var="version" value="2.07"/>
   <set var="name" value="Product ?@version?"/>
 </xvcl>

Example: Deferred evaluation

The deferEvaluation attribute is used when referencing a variable that is not yet defined. In the follwing example, the directory variable is set in an Ant script; it references a variable that is set in the SPC.

 ----- build.xml -----
 <xvcl spc="spc.xvcl">
   <set var="directory" value="demo?@version?/javadoc" deferEvaluation="yes"/>
 </xvcl>

 ----- spc.xvcl -----
 <x-frame name="spc.xvcl" outdir="build/source">
 <set var="version" value="2.07"/>
 <adapt x-frame="demo.xvcl" outdir="?@directory?"/>
 </x-frame>

Example: Variables with multiple values

In an x-frame, the set-multi tag creates a list of values.

 ----- spc.xvcl -----
 <set-multi var="property-list" value="id,name,value"/>

In the xvcl task, the setmulti tag creates a list of values.

 ----- build.xml -----
 <target name="emit" depends="taskdef">
   <xvcl spc="spc.xvcl">
     <setmulti var="property-list" value="id,name,value"/>
   </xvcl>
 </target>

Section A - Notes

As an adapt

Ideally, the adapt tag should be supported by the xvcl tag. The xvcl tag in an Ant script is an SPC.

 ----- build.xml -----
 <xvcl>
 <arg name="n" value="e"/>
 <set var="n" value="e"/>
 <set-multi var="n" value="e"/>
 <adapt x-frame="e" outdir="e" outfile="e">
 <insert break="n">
 </insert>
 </adapt>
 </xvcl>

where e is expanded by Ant, such as ${p}.

set class for Ant

 public class SetCommand {
   public void setVar( String v );
   public void setValue( String v );
   public void setDeferEvaluation( String v ); // yes|no
 }

The var property is required.

 Variable.isValidVar( v );

The value property is required.

 Variable.isValidStr( v );

The defer-evaluation property is optional.

set-multi class for Ant

 public class SetMultiCommand {
   public void setVar( String v );
   public void setValue( String v );
   public void setDelimiter( String v ); (?)
   public void setDeferEvaluation( String v ); // yes|no
 }

Variable class

This class represents variables, both single-value and multiple-value.

variableMap

A collection of Variable objects.

 abstract class XVCLNode {
   :
   private HashMap variableMap;
   :
 }

Method: getVariable()

 public Variable getVariable(String Name){
   if(variableMap==null){
     return ((XVCLNode)this.getParent()).getVariable(Name);
   }
   Variable var=(Variable)variableMap.get(Name);
   if (var==null){
     XVCLNode parent=(XVCLNode)this.getParent();
     return(parent==null?null:parent.getVariable(Name));
   }
   else{
     return var;
   }
 }

XVCL processor invokes first x-frame.

 URL spcURL;
 :
 getFrameParser().build( spcURL );

FrameParser invokes first x-frame.

 public void build(URL spcURL) throws XVCLException {
   //
   // fully load first frame into memory.
   //
   Document document=getXVCLDocument(spcURL);
   Element element=document.getRootElement();
   if(element instanceof Frame){

     // add SPC to adapting tree. for Workbench
     String framePathName=spcURL.toString();
     if(framePathName.startsWith("file:/")){
       framePathName = framePathName.substring(6);
     }
     //
     // output frame name to log.
     //
     getOptionTable().addLog(spcURL.toString().substring(6),spcURL.toString().substring(6));

     //
     // parse frame works
     //
     ((Frame)element).parse(spcURL);
     //SPC should begin with an Frame element.

     //OptionTable.getLog();

     //begin#######################
     // generate information file
     boolean mOption = Boolean.valueOf(getOption("OptionM")).booleanValue();
     if (mOption)
     {
       generateInfoFile(framePathName);
     }
   }
   else{
     throw new XVCLException("XVCL Node tree is not valid", XVCLException.INTERNAL_ERROR);
   }
 }

XVCL processor has-a frame-parser.

1. Modify XVCL processor to support system variables.
2. Modify XVCL processor to invoke FrameParser.build(..., variable-map );
3. Modify Frame to support storeVariable().
   1. Frame extends XVCLNode.
   2. public void XVCLNode.storeVariable(String name,Variable var);

Method: XVCLNode.getOption()

 public abstract class XVCLNode extends MyElement {
   :
   public OptionTable getOptionTable() {
     return getFrameParser().getOptionTable();
   }
   public String getOption( String v ) {
     // *D! return getFrameParser().getOptionTable().getOption( v );
     return getOptionTable().getOption( v );
   }
   :
 }

Method: XVCLNode.isLocalVariable()

Checks if the nearest variable table has defined the value.

 public boolean isLocalVariable(String Name){
   if(variableMap==null){
     return ((XVCLNode)this.getParent()).isLocalVariable(Name);
   }
   else{
     return (variableMap.get(Name)!=null);
   }
 }

Method: XVCLNode.storeVariable()

 public void storeVariable(String name,Variable var){
   if(variableMap!=null){
     variableMap.put(name,var);
   }
   else{
     ((XVCLNode)this.getParent()).storeVariable(name,var);
   }
 }

There are two kinds of nodes: with and without a variable map. Those with a variable map are x-frame (?).

Proposed interface: evaluator

An evaluator is needed to evaluate the value of a variable.

 public interface Evaluator {
   public StringBuffer resolve( String value );
 }

Proposed method: XVCLNode.setVariable()

The set tag sets a variable. The set tag in an Ant script should use exactly the same code as the set tag in an x-frame. The mechanism to create a new instance of Variable could be moved to XVCLNode.

 public void setVariable( String name, String value, boolean deferEvaluation )
     throw XVCLException {
   :
   Variable var = new Variable();
   :
   storeVariable( name, var );
 }

Proposed method: XVCLNode.setMultiVariable()

 public void setMultiVariable( String name, String value, boolean deferEvaluation )
     throw XVCLException {
 :
 }

Method: Frame.getParent()

 public Element getParent(){
   return adaptingNode;
 }

For a frame, the parent is the adapting node.

Method: Frame.parse()

 public StringBuffer parse(URL frameURL,XVCLNode adaptNode);

Method: Variable.isValidVar()

Checks whether a string expression is a valid variable name.

 static public boolean isValidVar(String var){
   boolean valid = true;

   if ( (var.indexOf("?") > 0) || (var.indexOf("@") > 0) || (var.indexOf(",") > 0) ) { 
     valid = false;
   }
   return valid;
 }

Method: Variable.isValidStr()

Checks whether a string expression is valid.

 static public boolean isValidStr(String str){
   boolean valid = true;

// if ( (str.indexOf("?") > 0) || (str.indexOf("@") > 0) || (str.indexOf(",") > 0) ) { ------change by cao yang

   if ( (str.indexOf("?") > 0) || (str.indexOf("@") > 0)) { 
     valid = false;
   }
   return valid;
 }

Method Variable.constructor

Constructs a variable with variable name and value delimiter.

 public Variable(String name,String valueDelimiter);