JSAPAntTask (JSAP: the Java Simple Argument Parser)
Keywords: com.martiansoftware.jsap.ant.JSAPAntTask class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.martiansoftware.jsap.ant
Class JSAPAntTask

    java.lang.Object
      org.apache.tools.ant.ProjectComponent
          org.apache.tools.ant.Task
              com.martiansoftware.jsap.ant.JSAPAntTask

    public class JSAPAntTask

extends org.apache.tools.ant.Task

An ANT task that generates a custom subclass of JSAP to simplify its use in a program. Rather than create all of the Switches, FlaggedOptions, and UnflaggedOptions and registering each with the JSAP, the developer does not need to do anything but instantiate the custom JSAP produced by this task.

To use this task, you must first declare it in your ANT build file with a <taskdef> tag, as follows:

`<taskdef name="jsap" classname="com.martiansoftware.jsap.ant.JSAPAntTask" classpath="${lib}/[jsap jarfile]"/>`

Note that this `taskdef` must be placed in your build file BEFORE your jsap task. The `classpath` attribute in the above example assumes that [jsap jarfile] is the name of the JSAP jarfile you're using, and is in the directory referenced by the ANT "lib" property.

Once declared, the jsap task can be used as many times as you wish. The jsap task supports the following attributes:

- srcdir (required): the source directory below which the generated JSAP source code should be placed.
- classname (required): the fully-qualified classname of the JSAP to generate.
- public (optional): "true" or "false" (default false). If true, the generated class will be declared public.

The jsap task supports the following nested elements:

- switch - declares a Switch (com.martiansoftware.jsap.Switch).
- flaggedoption - declares a FlaggedOption (com.martiansoftware.jsap.FlaggedOption).
- unflaggedoption - declares an UnflaggedOption (com.martiansoftware.jsap.UnflaggedOption).

These nested elements support the following attributes:

Attribute | Description | switch | flaggedoption | unflaggedoption | qualifiedswitch
id | Unique id for this parameter. This must be unique among all parameters defined in this ANT task. | Required | Required | Required | Required
shortflag | Short flag for this parameter. Only the first character of this attribute is read by the jsap task. This must be unique among all short flags defined in this ANT task. | Either shortflag or longflag is required. Both may be specified. | Either shortflag or longflag is required. Both may be specified. | N/A | Either shortflag or longflag is required. Both may be specified.
longflag | Long flag for this parameter. This must be unique among all long flags defined in this ANT task. | Either shortflag or longflag is required. Both may be specified. | Either shortflag or longflag is required. Both may be specified. | N/A | Either shortflag or longflag is required. Both may be specified.
required | "true" or "false" (default false). Indicates whether the specified parameter is required. | N/A | Optional | Optional | Optional
islist | "true" or "false" (default false). Indicates whether the specified parameter can be supplied as a list of values separated by a delimiter character. | N/A | Optional | Optional | Optional
listseparator | Specifies the delimiter character to use for list parameters. Default is JSAP.DEFAULT_LISTSEPARATOR | N/A | Optional | Optional | Optional
stringparser | Specifies the subclass of com.martiansoftware.jsap.StringParser to be used in parsing this parameter's values. If the specified class name contains no "dot" characters, it is assumed to be in the package com.martiansoftware.jsap.stringparsers. Default value is com.martiansoftware.jsap.stringparsers.StringStringParser. | N/A | Optional | Optional | Optional
greedy | "true" or "false" (default false). Specifies whether the unflaggedoption should be "greedy"; that is, should consume all remaining unflagged arguments from the command line. | N/A | N/A | Optional | N/A

All of these nested elements support multiple nested `<default>` elements. The text content of these tags is used as a default value for the parameter containing the tag.

Finally, the <flaggedoption> and <unflaggedoption> support multiple nested <property> elements, with similar syntax to ANT's <property> elements. These properties are set within the parameter's StringParser, assuming it is a subclass of com.martiansoftware.jsap.PropertyStringParser.

## Example

     & lt;taskdef name = "jsap" classname = "com.martiansoftware.jsap.ant.JSAPAntTask"
          classpath="${build}"/>

         <target name="createExampleAntJSAP">

             <jsap srcdir="${src}"
              classname="com.martiansoftware.jsap.examples.ExampleAntJSAP">

                 <!-- create a switch flagged by "v" or "verbose" -->
                 <switch id="verbose" shortflag="v" longflag="verbose"/>

                 <!-- create a required flaggedoption looking for an integer,
                  flagged by "n" (e.g. "-n 5") -->
                 <flaggedoption id="num" required="true" shortflag="n"
                  stringparser="IntegerStringParser">
                     <default>5</default>
                 </flaggedoption>

                 <!-- create an unflaggedoption that reads all of the unflagged
                  arguments from the
                  command line -->
                 <unflaggedoption id="files" greedy="true" />

                 <!-- create a flaggedoption looking for a Date in "MM/DD/YY"
                  format, flagged by "d"
                      or "date", defaulting to Christmas, 2002. -->
                 <flaggedoption id="date" shortflag="d" longflag="date"
                  stringparser="DateStringParser">
                     <property name="format" value="MM/DD/YYYY"/>
                     <default>12/25/2002</default>
                 </flaggedoption>

             </jsap>

         </target>

Author:
  Marty Lamb
See Also:
  `JSAP`, `Parameter`, `Switch`, `FlaggedOption`, `UnflaggedOption`, `StringParser`, `PropertyStringParser`

Constructor Summary
`JSAPAntTask()` Creates a new JSAPAntTask.

Method Summary
`void` | `addConfiguredFlaggedoption(FlaggedOptionConfiguration flaggedOptionConfig)` Adds a nested FlaggedOptionConfiguration to the generated JSAP.
`void` | `addConfiguredSwitch(SwitchConfiguration switchConfig)` Adds a nested SwitchConfiguration to the generated JSAP.
`void` | `addConfiguredUnflaggedoption(UnflaggedOptionConfiguration unflaggedOptionConfig)` Adds a nested UnflaggedOptionConfiguration to the generated JSAP.
`void` | `execute()` Validates the JSAP configuration and, if successful, writes the java source code for a JSAP subclass that implements the configuration specified in the ant build file.
`void` | `setClassname(String className)` Sets the full classname for the generated JSAP.
`void` | `setPublic(boolean isPublic)` Sets whether the generated JSAP should be declared public.
`void` | `setSrcdir(File srcDir)` Sets the top-level source directory under which the generated JSAP class file should be written.

Methods inherited from class org.apache.tools.ant.Task
`getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, init, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName`

Methods inherited from class org.apache.tools.ant.ProjectComponent
`getProject, setProject`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### JSAPAntTask

    public JSAPAntTask()

  Creates a new JSAPAntTask. One JSAPAntTask is created for each <jsap> section in an ant built file.

Method Detail

### setPublic

    public void setPublic(boolean isPublic)

  Sets whether the generated JSAP should be declared public. Default is false.

  Parameters:
    `isPublic` - if true, the generated JSAP will be declared public.

### setSrcdir

    public void setSrcdir(File srcDir)

  Sets the top-level source directory under which the generated JSAP class file should be written.

  Parameters:
    `srcDir` - the top-level source directory under which the generated JSAP class file should be written.

### setClassname

    public void setClassname(String className)

  Sets the full classname for the generated JSAP.

  Parameters:
    `className` - the full classname for the generated JSAP.

### addConfiguredFlaggedoption

    public void addConfiguredFlaggedoption(FlaggedOptionConfiguration flaggedOptionConfig)

  Adds a nested FlaggedOptionConfiguration to the generated JSAP.

  Parameters:
    `flaggedOptionConfig` - the nested FlaggedOptionConfiguration to add to the generated JSAP.

### addConfiguredUnflaggedoption

    public void addConfiguredUnflaggedoption(UnflaggedOptionConfiguration unflaggedOptionConfig)

  Adds a nested UnflaggedOptionConfiguration to the generated JSAP.

  Parameters:
    `unflaggedOptionConfig` - the nested UnflaggedOptionConfiguration to add to the generated JSAP.

### addConfiguredSwitch

    public void addConfiguredSwitch(SwitchConfiguration switchConfig)

  Adds a nested SwitchConfiguration to the generated JSAP.

  Parameters:
    `switchConfig` - the nested SwitchConfiguration to add to the generated JSAP.

### execute

    public void execute()
                 throws org.apache.tools.ant.BuildException

  Validates the JSAP configuration and, if successful, writes the java source code for a JSAP subclass that implements the configuration specified in the ant build file.

  Overrides:
    `execute` in class `org.apache.tools.ant.Task`
  Throws:
    `org.apache.tools.ant.BuildException` - if unsuccessful for any reason.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2005, Martian Software, Inc.. All Rights Reserved.
For the latest version and documentation, please visit http://www.martiansoftware.com/jsap