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 PrettyPrintCommands 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.