gov.nih.ncats.common.cli

Class CliSpecification

java.lang.Object

gov.nih.ncats.common.cli.CliSpecification

public class CliSpecification
extends Object

Specification describing the options for a given program. This specification is what is used to validate and parse program options.

Method Summary

Modifier and Type	Method and Description
CliSpecification	addValidation(java.util.function.Predicate<Cli> validationRule, java.util.function.Function<Cli,String> errorMessageFunction) Add an additional validation rule to this overall specification.
CliSpecification	addValidation(java.util.function.Predicate<Cli> validationRule, String errorMessage) Add an additional validation rule to this overall specification.
static CliSpecification	create(CliOptionBuilder... options) Create a new CliSpecification with the given options.
static CliSpecification	createWithHelp(CliOptionBuilder... options) Create a new CliSpecification with a default help option with the option name "-h" and long name "--help" along with the given other options.
CliSpecification	description(String description) Sets a description to this usage to describe what this program does.
String	generateUsage() Generate the Usage String of this specification.
static CliOptionBuilder	group(CliOptionBuilder... options) Create a new group of options where the specification is only valid if either all the required options in the group are present, or none of them are present.
boolean	helpRequested(String[] args) Is one of these passed in arguments -h, --h, -help or --help.
static BasicCliOptionBuilder	option(String optName) Create a new BasicCliOptionBuilder that is mapped to the given option name.
Cli	parse(String[] args) Parse the command line options of the given String array, often the arguments from a Main method.
Cli	parse(URL url) Parse the query parameters as a urlencoded command line arguments.
CliSpecification	programName(String programName) Sets this program name to this usage.
static CliOptionBuilder	radio(CliOptionBuilder... radioOptions) Create a new Radio group of options where the specification is only valid if only one of the given options can be selected.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createWithHelp

public static CliSpecification createWithHelp(CliOptionBuilder... options)

Create a new CliSpecification with a default help option with the option name "-h" and long name "--help" along with the given other options.

Parameters:

options - varargs of other options to include in this specification; may be empty but no item in the list can be null.

Returns:

a new CliSpecification will never be null.

create

public static CliSpecification create(CliOptionBuilder... options)

Create a new CliSpecification with the given options.

Parameters:

options - varargs of options to include in this specification; may be empty but no item in the list can be null.

Returns:

a new CliSpecification will never be null.

option

public static BasicCliOptionBuilder option(String optName)

Create a new BasicCliOptionBuilder that is mapped to the given option name. By default this radio group is not required, to make it required in the specification set the CliOptionBuilder.setRequired(boolean) method.

Parameters:

optName - the name of the option that will be in the specification as "-$optName".

Returns:

a new BasicCliOptionBuilder will never be null.

radio

public static CliOptionBuilder radio(CliOptionBuilder... radioOptions)

Create a new Radio group of options where the specification is only valid if only one of the given options can be selected. Nesting other groups as one of the radio options is allowed. By default this radio group is not required, to make it required in the specification set the CliOptionBuilder.setRequired(boolean) method.

Parameters:

radioOptions - a varargs list of radio options; none of the options may be null.

Returns:

a new CliOptionBuilder.

group

public static CliOptionBuilder group(CliOptionBuilder... options)

Create a new group of options where the specification is only valid if either all the required options in the group are present, or none of them are present. If this group is required, then this specification is only valid if the all the required options in this group are present. Nesting other groups as one of this group's options is allowed. By default this group is not required, to make it required in the specification set the CliOptionBuilder.setRequired(boolean) method.

Parameters:

options - a varargs list of options in this group; none of the options may be null.

Returns:

a new CliOptionBuilder.

addValidation

public CliSpecification addValidation(java.util.function.Predicate<Cli> validationRule,
                                      String errorMessage)

Add an additional validation rule to this overall specification.

Parameters:

validationRule - A Predicate function that passes in the parsed Cli instance from a program invocation that will return true if this Cli passes this new validation rule; false otherwise. This Predicate can not be null.

errorMessage - The message to use in the new CliValidationException that will be thrown if the given predicate returns false.

Returns:

this.

Throws:

NullPointerException - if validationRule is null.

addValidation

public CliSpecification addValidation(java.util.function.Predicate<Cli> validationRule,
                                      java.util.function.Function<Cli,String> errorMessageFunction)

Add an additional validation rule to this overall specification.

Parameters:

validationRule - A Predicate function that passes in the parsed Cli instance from a program invocation that will return true if this Cli passes this new validation rule; false otherwise. This Predicate can not be null.

errorMessageFunction - A function to generate the message to use in the new CliValidationException that will be thrown if the given predicate returns false.

Returns:

this.

Throws:

NullPointerException - if either parameter is null.

description

public CliSpecification description(String description)

Sets a description to this usage to describe what this program does.

Parameters:

description - the description of this program, if null, then there is no description.

Returns:

this.

programName

public CliSpecification programName(String programName)

Sets this program name to this usage.

Parameters:

programName - the name of this program, if null, then there is no name.

Returns:

this.

parse

public Cli parse(URL url)
          throws IOException

Parse the query parameters as a urlencoded command line arguments. It is a assumed that key=value means -key value.

Parameters:

url - the URL to parse; can not e null.

Returns:

a new Cli of the parsed options in the URL parameters.

Throws:

IOException - if there is a prolem decodeing the URL parameters

CliValidationException - if the url parameters violate this CliSpecification.

generateUsage

public String generateUsage()

Generate the Usage String of this specification.

Returns:

a new String will never be null.

helpRequested

public boolean helpRequested(String[] args)

Is one of these passed in arguments -h, --h, -help or --help.

Parameters:

args - the command line arguments to parse.

Returns:

true if at least one of these arguments is "-h", "--h", "-help" or "--help"; false otherwise

parse

public Cli parse(String[] args)
          throws CliValidationException

Parse the command line options of the given String array, often the arguments from a Main method.

Parameters:

args - the arguments array to parse.

Returns:

a new Cli of the parsed options.

Throws:

CliValidationException - if the arguments violate this CliSpecification.