Usage info generation
The level of freedom the monadic structure gives makes it hard to automatically generate usage info, but the library implements a heuristics that is good in most of the common cases, and also allows some customization.
Automatic mode
In automatic mode, the library introspects the parameter parser by running it with different automatically generated choices in order to figure out the execution graph.
These automatically generated choices are for:
- flags, trying both true and false
- commands, trying all the valid commands
Let’s see how the usage info generated for the 4th example in the getting started page look like!
import io.github.vigoo.clipp.usageinfo._
val usageGraph = UsageInfoExtractor.getUsageDescription(paramSpec4)
val usageInfo = UsagePrettyPrinter.prettyPrint(usageGraph)
// usageInfo: String = """Usage: Example 4 [-v] [command] ... ... ...
//
// -v, --verbose Verbose output
// <command> One of first, second, third
//
// When command is first:
// --input <value> Input value
//
// When command is second:
// --val1 <value> First input value
// [--val2 <value>] Second input value (optional)
//
// When command is third:
// --interactive Interactive mode
// <command> One of create, delete
//
// When command is create:
// <name> Name of the thing to create
//
// When command is delete:
// <id> Id of the thing to delete
// """
Customizing choices
All the syntax functions have variants with withExplicitChoices = List[T]
parameters which turns
off the automatic branching and uses the given list of values to generate the usage info graph. By
providing a single value, the choice can be locked to a fix value.
Manual mode
In very complex cases the pretty printer part of the library can be still used to display
customized information. In this case a custom list of PrettyPrintCommand
s and an optional
ParameterParserMetadata
can be provided to the UsagePrettyPrinter
.
Partially locked choices
In case of showing the usage info by reacting to bad user input, it is possible to use the state of the
parser up until the error to lock the choices to specific values. This has the same effect as
locking them to a particular value statically with the withExplicitChoices = List(x)
syntax.
This can be used to display only relevant parts of the usage info, for example in sub-command style cases.