Customizing help

Annotations

A number of annotations can be used, either on fields or on classes defining options, to customize the help message generated by case-app.

@AppName("My App")
@ProgName("my-app")
@AppVersion("0.1.0")
@ArgsName("things")
case class Options(
  @HelpMessage("How many foos")
  @Name("f")
  @ValueDescription("Foo count")
    foo: Int = 0
)

This makes the help message look like

Usage: my-app [options] [things]

Options:
  -f, --foo Foo count  How many foos

Without any of the annotations, the help message looks like

Usage: options0 [options]

Options:
  -f, --foo int

Hidden options

Annotate an option with @Hidden to hide it from the default help message:

case class Options(
  @Hidden
    foo: Int = 0,
  other: String = ""
)

This makes the help message look like

Usage: my-app [options]

Help options:
  --usage            Print usage and exit
  -h, -help, --help  Print help message and exit

Other options:
  --other string

When using hidden options alongside with the CaseApp class, you can offer users to get an help message that includes the hidden options with --full-help, like

object MyApp extends CaseApp[Options] {
  override def hasFullHelp = true
  def run(options: Options, args: RemainingArgs): Unit = {
    ???
  }
}

We get

$ my-app --full-help

Usage: my-app [options]

Help options:
  --usage                                        Print usage and exit
  -h, -help, --help                              Print help message and exit
  -help-full, -full-help, --help-full, --full-help  Print help message, including hidden options, and exit

Other options:
  --foo int       (hidden)
  --other string

Option groups

case class Options(
  @Group("First")
    foo: Int = 0,
  @Group("Second")
    other: String = ""
)

This makes the help message look like

Usage: my-app [options]

First options:
  --foo int

Help options:
  --usage            Print usage and exit
  -h, -help, --help  Print help message and exit

Second options:
  --other string

When using the CaseApp or Command classes, you can sort groups with

object MyApp extends CaseApp[Options] {
  override def helpFormat = super.helpFormat.withSortedGroups(
    Some(Seq("Help", "First", "Second"))
  )
  def run(options: Options, args: RemainingArgs): Unit = {
    ???
  }
}

One then gets

Usage: my-app [options]

Help options:
  --usage            Print usage and exit
  -h, -help, --help  Print help message and exit

First options:
  --foo int

Second options:
  --other string