Core classes of the Args4J command line parser.

What is Args4J?

Args4J is a command line parser. As such, its job is to parse the String-array passed to the main() method and transfer the values to a Java object, which includes type conversion. The entry point into this parsing is the CmdLineParser class, with its parse() method.

Args4J must know the mapping between the flag from the command line and the target for the value. There are many ways to use Args4J:

place an @Option or @Argument annotation at a setter or on a field
provide a XML configuration file
make all fields publicly available

Depending on what you want, you may have perform a configuration step before parsing.

Examples

java Main -text newText

The typical use involves writing a small bean class and providing the annotations.

This feature is available since the first Args4J release:

public class Bean {
   @Option(name="-text")
    String text;
}
public class Main {
    public static void main(String[] args) throws CmdLineException {
        Object bean = new Bean();
        CmdLineParser parser = new CmdLineParser(bean);
        parser.parse(args);
    }
}

An easy way to initialize fields without touching the bean source code is to use the FieldParser.

The FieldParser scans all fields of bean class (including inheritance), and makes them publicly available as options with a - prefix in the name.

This feature is available since Args4J release 2.0.16:

public class Bean {
    String text;
}
public class Main {
    public static void main(String[] args) throws CmdLineException {
        Object bean = new Bean();
        CmdLineParser parser = new CmdLineParser(null);
        new FieldParser().parse(parser, bean);
        parser.parse(args);
    }
}

While the FieldParser is easier to use, the XmlParser supports more features.

That said, it supports all features which are available via annotations: usage text, specifying handlers, and more. You have to provide an XML InputSource or a URL to the XML file.

This feature is available since Args4J release 2.0.16:

public class Bean {
    String text;
}
public class Main {
    public static void main(String[] args) throws CmdLineException {
        Object bean = new Bean();
        CmdLineParser parser = new CmdLineParser(null);
        new XmlParser().parse(getClass().getResource(bean.getClass().getName() + ".xml"), parser, bean);
        parser.parse(args);
    }
}
<args>
  <option field="text" name="-text" usage="Output text"/>
</args>

Modifier and Type	Interface and Description
public interface	Localizable A message that can be formatted with arguments and locale.
public interface	OptionHandlerFilter Selects `OptionHandler`.

Modifier and Type	Annotation and Description
public @interface	Argument Argument of the command line.
public @interface	Option Marks a field/setter that receives a command line switch value.

Class Summary

Modifier and Type	Class and Description
public class	ClassParser Parser for analyzing Args4J annotations in the class hierarchy.
public class	CmdLineException Signals an error in the user input.
public class	CmdLineParser Command line argument owner.
public class	Config Metadataconfiguration.
public class	FieldParser This metadata parser makes all field available to the CmdLineParser.
public class	IllegalAnnotationError Signals an incorrect use of args4j annotations.
public class	NamedOptionDef Immutable run-time copy of `Option` annotation.
public class	OptionDef Run-time copy of the Option or Argument annotation.
public class	OptionHandlerRegistry Manages the registration of option handlers.
public class	ParserProperties Set of properties that controls `CmdLineParser` behaviours.
public class	Starter Starter class which uses reflection to instantiate the business class, parse the command line parameters, sets the fields of the business class and doing the help message handling.
pack-priv class	Utilities Misc utility methods.
public class	XmlParser Parses an XML-file specifying the 'annotations'.

Modifier and Type	Enum and Description
public enum	ExampleMode Deprecated use `OptionHandlerFilter` Used with `CmdLineParser#printExample(ExampleMode)`.
pack-priv enum	Messages

Package org.kohsuke.args4j

What is Args4J?

Examples

Interface Summary

Annotation Summary

Class Summary

Enum Summary