Package com.github.hypfvieh.cli.parser

Class CommandLine

java.lang.Object

com.github.hypfvieh.cli.parser.AbstractBaseCommandLine<CommandLine>

com.github.hypfvieh.cli.parser.CommandLine

public final class CommandLine
extends AbstractBaseCommandLine<CommandLine>

A class to parse the Java command-line and access arguments by name and type using CmdArgOptions.

Example of working with a command-line with two options and a custom exception type:

 CommandLine commandLine = new CommandLine()
         .setExceptionType(MyApplicationException.class)
         .addOption(Option.builder(String.class)
                 .name("req1")
                 .required(true)
                 .defaultValue("default")
                 .build())
         .addOption(Option.builder()
                 .name("opt1")
                 .required(false)
                 .build())
         .parse();
 

Since:

1.0.0 - 2022-04-29

Author:

David M., Markus S.

Constructor Summary

Constructors

Constructor	Description
CommandLine()

Method Summary

Modifier and Type	Method	Description
Object	getArg(char _optionName)	Returns an option value using the options short name.
<T> T	getArg(char _optionName, Class<T> _type)	Returns an option value using the options short name and converting the value to the given type.
<T> T	getArg(char _optionName, Class<T> _type, T _default)	Returns an option value using the options short name and converting the value to the given type.
<T> T	getArg(CmdArgOption<T> _option)	Returns the value associated with argument option.
<T> T	getArg(CmdArgOption<T> _option, T _default)	Returns the value associated with argument option.
Object	getArg(CharSequence _optionName)	Returns an option value using the options name.
<T> T	getArg(CharSequence _optionName, Class<T> _type)	Returns an option value using the options name and converting the value to the given type.
<T> T	getArg(CharSequence _optionName, Class<T> _type, T _default)	Returns an option value using the options name and converting the value to the given type.
int	getArgCount(CmdArgOption<?> _option)	Returns the number of occurrences of the given option.
<T> List<T>	getArgs(char _optionName, Class<T> _type)	Returns all option values using the options short name and converting the values to the given type.
<T> List<T>	getArgs(CmdArgOption<T> _option)	Returns the value associated with argument option.
<T> List<T>	getArgs(CmdArgOption<T> _option, T _default)	Returns the value associated with argument option.
<T> List<T>	getArgs(CharSequence _optionName, Class<T> _type)	Returns all option values using the options name and converting the values to the given type.
boolean	hasArg(char _arg)	Checks if the given option was at least used once in the command line.
boolean	hasArg(CmdArgOption<?> _option)	Checks if the given option was at least used once in the command line.
boolean	hasArg(String _arg)	Checks if the given option was at least used once in the command line.
CommandLine	parse(String[] _args)	Parses the given arguments.
protected CommandLine	self()	Reference to ourselves for chaining.

Methods inherited from class com.github.hypfvieh.cli.parser.AbstractBaseCommandLine

addOption, addOptions, getDupArgs, getExceptionType, getKnownArgs, getLogger, getLongOptPattern, getLongOptPrefix, getOption, getOptions, getShortOptPattern, getShortOptPrefix, getUnknownArgs, getUnknownTokens, getUsage, hasArg, hasOption, hasOption, isFailOnDupArg, isFailOnUnknownArg, isFailOnUnknownToken, isParsed, logResults, printUsage, printUsage, registerConverter, setParsed, withExceptionType, withFailOnDupArg, withFailOnUnknownArg, withFailOnUnknownToken, withLongOptPrefix, withShortOptPrefix, withUsageFormatter

Methods inherited from class java.lang.Object

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

Constructor Details

CommandLine

public CommandLine()

Method Details

self

protected CommandLine self()

Reference to ourselves for chaining.

Specified by:

self in class AbstractBaseCommandLine<CommandLine>

Returns:

this

parse

public CommandLine parse(String[] _args)

Parses the given arguments.

Parameters:

_args - arguments to read

Returns:

this

getArg

public <T> T getArg(CmdArgOption<T> _option)

Returns the value associated with argument option.

If no value is present, the default value of that option is returned (and might by null).
If the option does not support values or option was not set, null is returned.
If the option is a repeatable option, the value of the first occurrence is returned.

Type Parameters:

T - type of option value

Parameters:

_option - option

Returns:

value, maybe null

getArg

public <T> T getArg(CmdArgOption<T> _option,
 T _default)

Returns the value associated with argument option.

If no value is present, the given default value is used.
If the given default is also null, the default of that option is returned (and might by null). If the option does not support values or if the option was not set, null is returned.

Type Parameters:

T - type of option value

Parameters:

_option - option

_default - default to use when no value present (overrides default specified in option)

Returns:

value, maybe null

getArgs

public <T> List<T> getArgs(CmdArgOption<T> _option)

Returns the value associated with argument option.

If no value is present, the default value of that option is returned (and might by null). If the option does not support values or if the option was not set, null is returned.

Type Parameters:

T - type of option value

Parameters:

_option - option

Returns:

List, maybe empty or null

getArgs

public <T> List<T> getArgs(CmdArgOption<T> _option,
 T _default)

Returns the value associated with argument option.

If no value is present, the given default value is used.
If the given default is also null, the default of that option is returned (and might by null). If the option does not support values or if the option was not set, null is returned.

Type Parameters:

T - type of option value

Parameters:

_option - option

_default - default to use when no value present (overrides default specified in option)

Returns:

List, maybe empty or null

getArg

public Object getArg(CharSequence _optionName)

Returns an option value using the options name.

Parameters:

_optionName - option name

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed before

getArg

public Object getArg(char _optionName)

Returns an option value using the options short name.

Parameters:

_optionName - option short name

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed before

getArg

public <T> T getArg(CharSequence _optionName,
 Class<T> _type,
 T _default)

Returns an option value using the options name and converting the value to the given type.
Will use the configured converter to convert the value.

If given type is not the same as the type specified in CmdArgOption an exception is thrown.

Type Parameters:

T - data type of argument

Parameters:

_optionName - option short name

_type - expected value type

_default - default to use if option not set (and not required)

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed

RuntimeException - if type class is not the type defined in CmdArgOption

Since:

1.0.1 - 2022-05-24

getArg

public <T> T getArg(CharSequence _optionName,
 Class<T> _type)

Returns an option value using the options name and converting the value to the given type.
Will use the configured converter to convert the value.

If given type is not the same as the type specified in CmdArgOption an exception is thrown.

Type Parameters:

T - data type of argument

Parameters:

_optionName - option short name

_type - expected value type

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed

RuntimeException - if type class is not the type defined in CmdArgOption

Since:

1.0.1 - 2022-05-24

getArg

public <T> T getArg(char _optionName,
 Class<T> _type)

Returns an option value using the options short name and converting the value to the given type.
Will use the configured converter to convert the value.

If given type is not the same as the type specified in CmdArgOption an exception is thrown.

Type Parameters:

T - type of option value

Parameters:

_optionName - option short name

_type - expected value type

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed

RuntimeException - if type class is not the type defined in CmdArgOption

Since:

1.0.1 - 2022-05-24

getArg

public <T> T getArg(char _optionName,
 Class<T> _type,
 T _default)

Returns an option value using the options short name and converting the value to the given type.
Will use the configured converter to convert the value.

If given type is not the same as the type specified in CmdArgOption an exception is thrown.

Type Parameters:

T - data type of argument

Parameters:

_optionName - option short name

_type - expected value type

_default - default to use if option not set (and not required)

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed

RuntimeException - if type class is not the type defined in CmdArgOption

Since:

1.0.1 - 2022-05-24

getArgs

public <T> List<T> getArgs(CharSequence _optionName,
 Class<T> _type)

Returns all option values using the options name and converting the values to the given type.
Will use the configured converter to convert the value.

If given type is not the same as the type specified in CmdArgOption an exception is thrown.

Type Parameters:

T - data type of argument

Parameters:

_optionName - option short name

_type - expected value type

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed

RuntimeException - if type class is not the type defined in CmdArgOption

Since:

1.0.1 - 2022-05-24

getArgs

public <T> List<T> getArgs(char _optionName,
 Class<T> _type)

Returns all option values using the options short name and converting the values to the given type.
Will use the configured converter to convert the value.

If given type is not the same as the type specified in CmdArgOption an exception is thrown.

Type Parameters:

T - data type of argument

Parameters:

_optionName - option short name

_type - expected value type

Returns:

value or null if option has no value

Throws:

RuntimeException - if option is unknown or command line was not parsed

RuntimeException - if type class is not the type defined in CmdArgOption

Since:

1.0.1 - 2022-05-24

hasArg

public boolean hasArg(CmdArgOption<?> _option)

Checks if the given option was at least used once in the command line.

Parameters:

_option - option to check

Returns:

true if it was used at least once, false otherwise

hasArg

public boolean hasArg(String _arg)

Checks if the given option was at least used once in the command line.

Will only check if the string argument was found as option name, will not check with short name.

Parameters:

_option - option to check

Returns:

true if it was used at least once, false otherwise

hasArg

public boolean hasArg(char _arg)

Checks if the given option was at least used once in the command line.

Will only check if the char argument was found as short option.

Parameters:

_option - option to check

Returns:

true if it was used at least once, false otherwise

getArgCount

public int getArgCount(CmdArgOption<?> _option)

Returns the number of occurrences of the given option.

If the option was never set, 0 is returned.

Parameters:

_option - option

Returns:

number of occurrences