A Java library for parsing and validating CLI arguments (and Strings formatted alike).
To install from Maven Central use group ID com.github.tmarsteel
and
artifact ID jcli
:
<!-- in the <dependencies> in your pom.xml -->
<dependency>
<groupId>com.github.tmarsteel</groupId>
<artifactId>jcli</artifactId>
<version>2.3.0</version>
</dependency>
Go to the releases page and download tmarsteel-jcli-X.X.X.jar
from the latest release.
- Flags, Options and Arguments
- Validation
- entirely configurable using XML
- convert/parse input to data types such as
File
,BigDecimal
andPattern
- Constraints on inputs, e.g: file must exist and be readable, integer ranges, pattern matching (and group extraction!), ...
- Helptext generation: put
<description>
tags in your XML and the help output is generated for you - Multi Command support in the style of
git commit
andapt-get install
- Text formatting tools for rich CLI interface: Currently Tables, Lists and wrapping text
- Environment-Agnostic: accept *NIX style commands on *NIX systems, DOS style commands on DOS systems
- Input validation
- Walkthrough: an introduction to XML configuration
- detailed Documentation a full explanation of all XML directives and of how to create custom filters and rules
- Programmatical Configuration documentation of programmatical configuration
- Helptext: How to generate a help text based on validation constraints
- Sub-Commands: How to use the multi-command support
- Text formatting tools: Create text based tables and lists
- Gotchas: Avoid pitfalls by reading this page
jCLI can be configured either via XML documents or programmtaically (modifying the parsed XML configuration is possible, but not convenient).
The library distinguishes three types of input: flags, options and arguments. They are supposed to be arranged in this order: <executable> [flags and options] : arguments...
Options and arguments can have arbitrary values, falgs are represented as boolean
, set or not set.
If you only want to parse input (without support for aliases, validation and OS specifiy syntax), just push the data into an instance of Input
:
import com.tmarsteel.jcli.Input;
import com.tmarsteel.jcli.Environment;
// ...
public static void main(String[] args) {
Input input = new Input(Environment.UNIX, args);
boolean verbose = input.isFlagSet("verbose");
}
To offer aliases (e.g. -v
and --verbose
for the same flag), validate the values of options/arguments and to adapt the syntax to the platform your software is being run on use
Validator
:
Validator inputValidator = new Validator();
You can then programmatically configure the validator. But most of the time you will want to load an XML configuration, this can be done like this:
ValidatorConfigurator configurator = XMLValidatorConfigurator.getInstance(
getClass().getResourceAsStream("cli-config.xml")
);
configurator.configure(inputValidator);
class SampleProgram
{
public static void main(final String[] args)
{
Validator inputValidator = new Validator();
// configure inputValidator
Validator.ValidatedInput input;
try
{
input = inputValidator.parse(args);
System.out.println("foo: " + input.getOption("foo"));
System.out.println("baz: " + input.isFlagSet("baz"));
System.out.println("arg: " + input.getArgument("sampleArgument"));
}
catch (ParseException ex)
{
System.out.println("Failed to initialize: " + ex.getMessage());
return;
}
catch (ValidationException ex)
{
System.out.println("Please check your input: " + ex.getMessage());
return;
}
}
}
> java SampleProgram -foo "Hello World!" : sampleArgument
foo: Hello World!
baz: false
arg: sampleArgument
On UNIX systems (File.separatorChar == '/'
) flags are recognised by a single-dash prefix and options by a double-dash prefix:
program -flag --option optionValue : argument
On DOS systems (File.separatorChar != '/'
) both flags and options are expected to be prefixed with a forward
slash (/
); whether something is a flag or an option is derived from context.
When using arguments with a Validator
, these arguments have to be configured in order to be accessed.