https://github.com/h908714124/jbock

Reflectionless command line parser
https://github.com/h908714124/jbock

annotation-processing command-line-parser java

Last synced: about 2 months ago
JSON representation

Reflectionless command line parser

• Host: GitHub
• URL: https://github.com/h908714124/jbock
• Owner: jbock-java
• License: mit
• Created: 2017-04-12T14:48:23.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2024-06-20T09:59:44.000Z (3 months ago)
• Last Synced: 2024-07-29T01:19:06.321Z (about 2 months ago)
• Topics: annotation-processing, command-line-parser, java
• Language: Java
• Homepage:
• Size: 4.92 MB
• Stars: 82
• Watchers: 3
• Forks: 7
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: .github/CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-java - jbock - Typesafe, reflection-free, annotation based command-line parser. (Projects / CLI)

README

        
[![jbock-compiler](https://maven-badges.herokuapp.com/maven-central/io.github.jbock-java/jbock-compiler/badge.svg?color=grey&subject=jbock-compiler)](https://maven-badges.herokuapp.com/maven-central/io.github.jbock-java/jbock-compiler)

[![jbock](https://maven-badges.herokuapp.com/maven-central/io.github.jbock-java/jbock/badge.svg?subject=jbock)](https://maven-badges.herokuapp.com/maven-central/io.github.jbock-java/jbock)

jbock is a command line parser, which uses the same well-known annotation names as [JCommander](https://jcommander.org/)

and [picocli](https://github.com/remkop/picocli).

It is an

[annotation processor](https://openjdk.java.net/groups/compiler/processing-code.html)

so it doesn't use runtime reflection, but generates a custom parser at compile time instead.

### Quick rundown

Create an abstract class, or alternatively a Java interface,

and add the `@Command` annotation.

In this so-called *command class*, each abstract method represents a command line option or argument.

Every such method must have

* getter signature (doesn't return `void`, takes no arguments) and

* annotation (either `@Option`, `@Parameter` or `@VarargsParameter`).

The types `boolean`, `List` and `Optional` (including `OptionalInt`) have special meaning.

See example below.

````java

@Command

abstract class DeleteCommand {

  @Option(names = {"-v", "--verbosity"},

          description = {"A non-required, named option. The return type is optionalish.",

                         "Using int or Integer would make it required."})

  abstract OptionalInt verbosity();

  @Parameter(

          index = 0,

          description = {"A required positional parameter. Return type is not optionalish.",

                         "Built-in converter is available for type Path."})

  abstract Path path();

  @Parameter(

          index = 1,

          description = "An optional positional parameter.")

  abstract Optional anotherPath();

  @VarargsParameter(

          description = {"A varargs parameter. There can only be one of these.",

                         "Must return List."})

  abstract List morePaths();

  

  @Option(names = "--dry-run",

          description = "A nullary option, a.k.a. mode flag. Must return boolean.")

  abstract boolean dryRun();

  

  @Option(names = "-h",

          description = "A repeatable option. Must return List.")

  abstract List headers(); 

  

  @Option(names = "--charset",

          description = "Named option with a custom converter",

          converter = CharsetConverter.class)

  abstract Optional charset();

  

  static class CharsetConverter extends StringConverter {

    @Override

    protected Charset convert(String token) { return Charset.forName(token); }

  }

}

````

The generated class is called `*Parser`.

````java

public static void main(String[] args) {

  DeleteCommand command = DeleteCommandParser.parseOrExit(args);

  // or: Either either = DeleteCommandParser.parse(List.of(args));

}

````

### Standard types

Some types don't need a custom converter. See [StandardConverters.java](https://github.com/jbock-java/jbock/blob/master/jbock/src/main/java/net/jbock/contrib/StandardConverters.java).

### Subcommands

The `@SuperCommand` annotation can be used to define a git-like subcommand structure. See [javadoc](https://github.com/jbock-java/jbock/blob/master/jbock/src/main/java/net/jbock/SuperCommand.java).

### Sample projects

* [jbock-maven-example](https://github.com/jbock-java/jbock-maven-example)

* [jbock-gradle-example](https://github.com/jbock-java/jbock-gradle-example)

### Alternatives

* [Tim's list](https://github.com/timtiemens/javacommandlineparser)