Flags And Optional Parameters - adamtomi/grapefruit GitHub Wiki

It's as easy as it gets, really ;) :

@CommandDefinition(route = "test")
public void testCommand(final @Flag("some-flag") int count) {

}

If count would be a standard parameter, the command line would like this: test 10. However, @Flag is present, which turns the parameter into a flag. Now the command line looks more like this: test --some-flag 10. Specifying a shorthand isn't necessary, but recommended.

@CommandDefinition(route = "test")
public void testCommand(final @Flag(value = "some-flag", shorthand = 's') int count) {

}

Now it's up to the user whether they prefer the name, or use the shorthand instead (which would look like this: test -s 10). If there are more then one parameters (not just flags, but any kind of parameters), it is possible to specify flags in any order, as long as all the route itself is first (meaning that --some-flag 10 test is invalid and will result in an error). Let me give you an example:

@CommandDefinition(route = "test")
public void testCommand(final @Flag(value = "some-flag", shorthand = 's') int count,
                        final @Flag(value = "other-flag", shorthand = 'o') boolean someBoolean,
                        final @Flag(value = "another-flag", shorthand = 'a') String someString) {

}

In the above case these inputs are all valid (these aren't the only valid options):

• test --some-flag 10 --other-flag --another-flag Hello
• test --another-flag Hello -s 10 --other-flag
• test -osa 10 Hello
• test-o --another-flag Hello -s 10
• test

The reason other-flag didn't receive any values is because it's type is boolean, so grapefruit converts it into a presence (or boolean) flag. The value of these kind of flags depends on whether they're specified or not. If so, the value is true, otherwise false.

The third example might seem weird or invalid at first glance, but it's indeed a valid syntax. These are called flag groups; basically flags are grouped together using their shorthands (which means that flags without shorthands cannot be grouped). The syntax is pretty straightforward: -<shorthand-0><shorthand-1><shorthand-2> <value-0> <value-1> <value-2>. Flag groups don't have to include all flags, so technically test -sa 10 Hello --other-flag is also a valid input for the above case.

Couldn't be more straightforward. :)

@CommandDefinition(route = "test")
public void testCommand(final @OptParam String optionalparameter) {
    System.out.println(optionalParameter);
}

In the above case dispatching just test won't fail, since the only parameter of the command is optional. It is allowed to have multiple optional parameters, like this:

@CommandDefinition(route = "test")
public void testCommand(final @OptParam String someString,
                        final @OptParam int someInt,
                        final @OptParam boolean someBoolean) {
}

Flags and optional parameter are optional (which means that it's okay to omit them). Their default values are null for objects, and the default primitive values for primitive types.

It really comes down to personal preference, I personally favor flags purely because in my opinion, they're much more powerful.