Getting started

Introduction

This page introduces the basic usage of yacap.

Understanding command line arguments

As far as the parser goes, the command line arguments could be separated into 3 sections:

• Names options: label-value pairs (or simple labels without values)
• Unnamed arguments: Zero, one or more arguments representing a list of input
• Possible an internal argument list: they are arguments which have to be passed unparsed (usually they are arguments your program passes to some other, internally called program)

All three sections are optional.

To demonstrate the three sections, look at the following command line:

:::java
   myapp -abc --max 10 -s sometext file1 file2 -- -x -s othertext

As visible, each option label starts with one or two hyphen(s) and optionally followed by a value. There are two ways to specify arguments:

• Short (or POSIX) form: the option label starts with a single hyphen (-) and the label is always exactly one character.
• Long (or GNU) form: the option label starts with double hyphens (--) and the name is an arbitary long text containing aphanumeric characters or hyphen.

The short form options, when they contain no value, like switches or flags, can be collapsed into one option. (-abc) Other options are supported by value, such as --max or -s.

The named option section ends when the parser first runs into an argument which doesn't start with hyphen. From here, all arguments are regarded as unnamed arguments till the end or till the parse-closing signal of a sole double hyphen (--). So the unnamed arguments here are file1 and file2.

The arguments after the sole double hyphen (--) are regarded as internal and won't be parsed, but will be passed forward the application as is.

Configuring option sets

To define all possible options of your application you should create an OptionSet.

Creating option set

It is simple to create your option set:

:::java 
   myOptionSet = new OptionSet(); 

and then register your options into.

The options are immutable objects and they should be created through their builders. Each option you register should have a unique long name and if you specify a short for as well, it has to be unique also.

Creating a simple option

For example, let's create a simple flag option with no value, and add it a short form:

:::java 
   BooleanOption boolOption = new BooleanOption.Builder("bool")
       .withShortForm('b')
       .getInstance();

This option will be accessible from command line by either the short form -b or the long form --bool. It will be optional.

Register an option

To register the option to your set, use the registerOption function:


myOptionSet.registerOption(boolOption);


The types of the options

The following option types are provided by yacap:

Class	Has value	Description
BooleanOption	no	Represents a logical choice, such as flags. Specifying the option means true, omiting means false.
StringOption	yes	A common string option.
IntegerOption	yes	A 4-byte, signed integer option. Accepts any value that the Integer.parseInt() can convert.
LongOption	yes	A 8-byte, signed integer option. Accepts any value that the Long.parseLong() can convert.
DoubleOption	yes	A floating point option. Accepts any value that the Double.parseDouble() can convert.
EnumOption<E>	yes	An option of predefined value set. Accepts the values of the associated enum.

Creating an option with value

To create an option with parameter you have to do nothing special. The type of the option defines whether it requires a value or not.

The following code will create an optional string option with no short form:

:::java 
   StringOption stringOption = new StringOption.Builder("str").getInstance();

Setting option policy

When it isn't specified otherwise, an option is marked as optional. To change this you can define the policy:

:::java 
   StringOption stringOption = new StringOption.Builder("str")
      .withDefaultOptionPolicy(OptionPolicy.REQUIRED)
      .getInstance();

These are the possible option policies:

Policy	Behaviour
HIDDEN	The option is regarded as a default option always set to its default value. The user can't specify it, the help won't contain it.
OPTIONAL	The option is optional. If the user doesn't specify it, the result set will not contain it. This is the default policy.
OPTIONAL_AUTO	It is similar to OPTIONAL, but it will always be included in result set with its default value if it was not specified otherwise in command line. This option policy requires a default value to be set.
REQUIRED	The command line should contain this option.

Setting value policy

Usually an option clearly defines whether it requires a value or not. However, there is sometimes meaningful defaul value for the option and one would like to let the user to omit the value and only specifies the option itself. To achieve it, you can override value policy:

:::java
   StringOption stringOption = new StringOption.Builder("str")
        .withValueOptional()
        .withDefaultValue("defval")
        .getInstance();

Setting the default value

By default, an option has no default value, but you can specify one.

:::java
   StringOption stringOption = new StringOption.Builder("str")
        .withDefaultValue("defval")
        .getInstance();

Default value is used when

• either the value policy is set to OPTIONAL and the user hasn't specified a value in command line
• or if the option policy is OPTIONAL_AUTO and the user hasn't specified this option in command line.

Decoupling command line from code

By default, the key used in result set is identical to the long form of the option. It tightly couples the command line option names to your code.

To reduce this dependency one can either use constants or could separate the two keys:

:::java
   StringOption stringOption = new StringOption.Builder("str")
        .withValueKey("internalKey")
        .getInstance();

In the example above, the options will appear as str in command line, but you can refer to it in result set as internalKey.

Providing information for help renderer

Yacap is not only able to parse the command line, but shipped with a highly configurable help renderer. To

To be continued...