# Package org.kohsuke.args4j

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>

`

Interface Summary
Localizable: A message that can be formatted with arguments and locale.
OptionHandlerFilter: Selects `OptionHandler`.
OptionHandlerRegistry.OptionHandlerFactory: Provide custom logic for creating `OptionHandler` implementation.

Class Summary
ClassParser: Parser for analyzing Args4J annotations in the class hierarchy.
CmdLineParser: Command line argument owner.
Config: Metadataconfiguration.
FieldParser: This metadata parser makes all field available to the CmdLineParser.
NamedOptionDef: Immutable run-time copy of `Option` annotation.
OptionDef: Run-time copy of the Option or Argument annotation.
OptionHandlerRegistry: Manages the registration of option handlers.
ParserProperties: Set of properties that controls `CmdLineParser` behaviours.
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.
XmlParser: Parses an XML-file specifying the 'annotations'.

Enum Summary
ExampleMode: Deprecated. use `OptionHandlerFilter`

Exception Summary
CmdLineException: Signals an error in the user input.

Error Summary
IllegalAnnotationError: Signals an incorrect use of args4j annotations.

Annotation Types Summary
Argument: Argument of the command line.
Option: Marks a field/setter that receives a command line switch value.