Args - A java configuration file and command line parser

Easy to use configuration, option and command line argument processor. Args supplies functionality for both command line parsing and configuration support using common definitions. Configuration of programs and command line parsing typically go hand in hand and are implemented together by Args.

• Getting Started
• Options
  • Create using annotations
  • Create using factory class Args
  • Create using builder pattern
  • Accessing option values
• Groups
  • Static Groups
  • Dynamic Groups
    • Dynamic group node structure
• Examples

---

Getting Started

Args API has been designed with ease of use in mind. The main entry point, and for the most part, the only API you need to interact with is the Args factory class. It provides 99% of all functionality you need.

public class Example1 {
    @Option
    static boolean a;

    public static void main(String[] args) {
        Args.parseArgs(args, Example1.class);

        System.out.printf("a=%s%n", a);
    }
}

See the full [Example1 - basic usage] for more details.

Options

The basic unit of configuration in Args is an option represented by java interace OptionInfo<T> where <T> is a value type such as String, Boolean, Integer or a a Collection<?> type. An option always belongs to a group and is never by itself.

Create using annotations

The most common way to create options is through annotation, but that is not the only way. Options are created programmatically through a factory class, through a builder pattern or by annotating java class fields and methods.

public class MyClass {
    @Option
    static int option1;

    @Option
    static String option2;

    public static void main(String[] args) {
        Args.parseArgs(args, MyClass.class);
     }
}

Create using factory class Args

RootGroupInfo root = Args.createRoot();

OptionInfo<Integer> option1 = Args.createOption(Integer.class, "option1");
root.addOption(option1);

OptionInfo<String> option2 = Args.createOption(String.class, "option1");
root.addOption(option2);

Create using builder pattern

RootGroupInfo root = new RootGroupBuilder()
    .build();

 OptionInfo<Integer> option1 = new OptionBuilder<Integer>()
      .withType(Integer.class)
     .withName("option1")
     .build();
 root.addOption(option1);

 OptionInfo<String> option2 = new OptionBuilder<String>()
     .withType(String.class)
     .withName("option2")
     .buid();
 root.addOption(option2);

Accessing option values

...
RootGroupInfo root = Args.parseArgs(args, MyClass.class);
OptionInfo<Integer> option1 = root.getStaticOption(Integer.class, "option1");
OptionInfo<String> option2 = root.getStaticOption(String.class, "option2");

System.out.printf("option1 = %d%n", option1.getValue());
System.out.printf("option2 = %s%n", option2.getValue());

Groups

A group is a collection of options and is of type java interface GroupInfo<T>. Since GroupInfo<T> extends an OptionInfo<T>, a group is also an option which can hold a value. Group values are only used by dynamic groups, as they are used to uniquely identify a group using its name and value as absolutely unique identifiers. The group interface provides numerous methods for

• Adding options to a group
• Adding groups as children to a group
• Getting a group by name or user object instance

Static Groups

Static groups are the ones which do not have a value set (i.e. group.getValue() == null). This is to ensure that no dynamic class fields ever are defined for a static group. For static groups defined based on annotated user classes, a static group will contain all options defined based on static class fields.

For example

@Group
public class MyClass {
    @Option
    static int field1;

    @Option
    int field2;

A static group defined for this class, will contain only one option, 'field1' as that is the only static class field/property being defined as an option.

Dynamic Groups

Dyanmic groups are the ones which must have a unique value set (i.e. group.getValue() != null). This allows multiple dynamic groups to be allocated with the same group name and still uniquely be distinguishable. A dynamic group will also hold an object instance of the user annotated class (i.e group.get(Class<T> annotatedClassType)).

For example

@Group
public class MyClass {
    @Option
    static int field1;

    @Option
    int field2;

A dynamic group created for this class, will contain only one option, 'field2'.

For example, given the following command line arguments and parsed by Args.parseArgs(args, MyClass.class)

--my-class firstInstance --field2 10 --my-class secondInstance --field2 20

The option tree returned by the Args builder would contain two dynamic groups. Group 1 named 'myclass' with group value 'firstInstance' of type String.class which is the default type and group 2 also named 'myclass' with group value 'secondInstance'.

Dynamic group node structure

Dynamic group instances are stored as children of the static group of the same annotated user type and name. The overall node tree structure returned by the Args.parseArg or any similar factory method looks like this, for the example given in previous section

RootGroup[name = root]
+ Group[name = my-class, value = null] # The static group
  + Option[name = field1, value = 0]
  + Group[name = my-class, value = firstInstance]
    + Option[name = field2, value = 10]
  + Group[name = my-class, value = secondInstance]
    + Option[name = field2, value = 20]

Examples

1. Full example of the unix 'ls' command options and how to generate unix 'manpage' straight from annotated options: [Example -ls manpage] and its output [Example -ls output].

Project Members:

• Sly Technologies (admin)