se.softhouse:jargo-addons

Code that could have been added to jargo if it didn't require third party dependencies.

License

License

GroupId

GroupId

se.softhouse
ArtifactId

ArtifactId

jargo-addons
Last Version

Last Version

0.4.14
Release Date

Release Date

Type

Type

jar
Description

Description

Code that could have been added to jargo if it didn't require third party dependencies.

Download jargo-addons

How to add to project

<!-- https://jarcasting.com/artifacts/se.softhouse/jargo-addons/ -->
<dependency>
    <groupId>se.softhouse</groupId>
    <artifactId>jargo-addons</artifactId>
    <version>0.4.14</version>
</dependency>
// https://jarcasting.com/artifacts/se.softhouse/jargo-addons/
implementation 'se.softhouse:jargo-addons:0.4.14'
// https://jarcasting.com/artifacts/se.softhouse/jargo-addons/
implementation ("se.softhouse:jargo-addons:0.4.14")
'se.softhouse:jargo-addons:jar:0.4.14'
<dependency org="se.softhouse" name="jargo-addons" rev="0.4.14">
  <artifact name="jargo-addons" type="jar" />
</dependency>
@Grapes(
@Grab(group='se.softhouse', module='jargo-addons', version='0.4.14')
)
libraryDependencies += "se.softhouse" % "jargo-addons" % "0.4.14"
[se.softhouse/jargo-addons "0.4.14"]

Dependencies

compile (2)

Group / Artifact Type Version
se.softhouse : jargo jar 0.4.14
joda-time : joda-time jar 2.2

provided (1)

Group / Artifact Type Version
com.google.code.findbugs : jsr305 jar 1.3.9

test (12)

Group / Artifact Type Version
se.softhouse : common-test jar 0.4.14
se.softhouse : jargo test-jar 0.4.14
com.google.guava : guava jar 24.1-jre
com.google.caliper : caliper jar 0.5-rc1
com.google.guava : guava-testlib jar 24.1-jre
com.google.code.findbugs : annotations jar 2.0.0
org.easytesting : fest-assert jar 1.4
junit : junit jar 4.11
org.jacoco : org.jacoco.agent jar 0.8.1
com.google.code.tempus-fugit : tempus-fugit jar 1.1
org.powermock : powermock-module-junit4 jar 1.7.0RC2
org.powermock : powermock-api-mockito jar 1.7.0RC2

Project Modules

There are no modules declared in this project.

Jargo

A tool to ease the handling of program arguments/options
Build Status

Maven Central

Most basic usage

import static se.softhouse.jargo.Arguments.*;
...
String[] args = {"--enable-logging", "--listen-port", "8090", "Hello"};

Argument<?> helpArgument = helpArgument("-h", "--help"); //Will throw when -h is encountered
Argument<Boolean> enableLogging = optionArgument("-l", "--enable-logging")
									.description("Output debug information to standard out").build();
Argument<String> greetingPhrase = stringArgument()
									.description("A greeting phrase to greet new connections with").build();
Argument<List<Integer>> ports = integerArgument("-p", "--listen-port")
									.defaultValue(8080)
									.description("The port clients should connect to.")
									.metaDescription("<port>")
									.limitTo(Range.closed(0, 65536))
									.repeated().build();

try
{
	ParsedArguments arguments = CommandLineParser.withArguments(greetingPhrase, enableLogging, ports)
													.andArguments(helpArgument)
													.parse(args);
													
	System.out.println("Logging enabled: " + arguments.get(enableLogging));
	System.out.println("Ports: " + arguments.get(ports));
	System.out.println("Greeting visitors with: " + arguments.get(greetingPhrase));
}
catch(ArgumentException exception)
{
	System.out.println(exception.getMessageAndUsage());
	System.exit(1);
}

Tab-completions

No program is complete without tab-completions! So after building your project's jar (.jar), you (and your users) need to specify:

alias my-app="java -jar <path-to-app>.jar"
complete -o default -o bashdefault -o nospace -C my-app "my-app"

in their ~/.bash_profile file to enjoy the automatic tab-completions Jargo provides.

For more examples see the Javadoc

Dependency

Jargo

 <dependency>
   <groupId>se.softhouse</groupId>
   <artifactId>jargo</artifactId>
   <version>0.4.13</version>
 </dependency>

Common-test (optional) Javadoc

 <dependency>
  <groupId>se.softhouse</groupId>
  <artifactId>common-test</artifactId>
  <version>0.4.13</version>

JDK compatiblity

JDK 6

Version <= 0.4.1 (used Guava)

JDK 8

From version 0.4.2 and onwards this library requires jdk 8 and Guava was removed as a dependency. This made this library even more lightweight (179K, no external dependencies). Especially useful as command line tools are often distributed, so the small file-size can be useful. If you want to go even further in reducing the filesize of your program, you can try out Proguard

Bugs/Questions

Stack Overflow

Issues

QA forum

Rationale

for writing yet another argument parsing library (see Is there a good command line argument parser for Java? for others)

  1. Because type-safety, immutability and readability matters

  2. Compared to annotation based solutions (like JCommander) jargo can be updated at runtime to support more arguments

  3. The generics on Argument gives you compile-time errors when switching types

    In JCommander:

    @Parameter(names = "-file", converter = FileConverter.class)  
    File file; //Oops, changing this to int would not work very well with FileConverter

    In jargo:

    Arguments.fileArgument("-file").parse("-file", "filename.txt").createNewFile();

    if fileArgument would change to being integerArgument, trying to call createNewFile() would generate a compile-time error

  4. Because JCommander doesn't support repeated arguments other than List<String>

    String[] args = {"--numbers", "5", "6", "--numbers", "3", "4"};  
    Argument<List<List<Integer>>> numbers = Arguments.integerArgument("--numbers").arity(2).repeated().build();
  5. Reflection makes it hard to analyze references to classes/methods and it often requires a granted suppressAccessChecks from the SecurityManager, this may not be wanted. No reflection is used in jargo.

For contributors

Possible candidates for refactoring

Check code-smells at codescene.io.

se.softhouse

Softhouse

Versions

Version
0.4.14
0.4.13
0.4.12
0.4.11
0.4.10
0.4.9
0.4.8
0.4.7
0.4.5
0.4.4
0.4.2
0.4.1
0.2