Options.OptStream.Help

This module contains lower-level functions for working with Help objects. You may need to import this if you work with Help objects directly, as opposed to relying on them being handled automatically by Parser.

Help objects

data Help

Represents help information that could be printed when the user passes --help on the command line.

A Help object contains three parts, each of which could be empty: a header, an options table, and a footer. Help objects can be composed together using <>. That will separately concatenate headers, option tables, and footers.

Instances

Eq Help

Defined in Options.OptStream.Help

Methods

(==) :: Help -> Help -> Bool

(/=) :: Help -> Help -> Bool

Show Help

Defined in Options.OptStream.Help

Methods

showsPrec :: Int -> Help -> ShowS

show :: Help -> String

showList :: [Help] -> ShowS

Semigroup Help

Defined in Options.OptStream.Help

Methods

(<>) :: Help -> Help -> Help

sconcat :: NonEmpty Help -> Help

stimes :: Integral b => b -> Help -> Help

Monoid Help

Defined in Options.OptStream.Help

Methods

mempty :: Help

mappend :: Help -> Help -> Help

mconcat :: [Help] -> Help

formatHelp :: Help -> String

Formats the Help object.

h :: Help
h = makeHeader "Usage: program [options] ARG"
 <> makeFreeArgHelp "ARG" "Positional argument."
 <> makeFlagHelp ["-f", "--foo"] "A flag."
 <> makeParamHelp ["-p", "--param"] "VAL" "A parameter."
 <> makeFooter "Example: program --foo bar"

>>> putStrLn $ formatHelp h
Usage: program [options] ARG

  ARG              Positional argument.
  -f, --foo        A flag.
  -p, --param=VAL  A parameter.

Example: program --foo bar

makeHeader :: String -> Help

Makes a Help object that contains one paragraph in the header.

makeFooter :: String -> Help

Makes a Help object that contains one paragraph in the footer.

makeFlagHelp

Arguments

:: [OptionForm]

All the flag forms, e.g. ["-f", "--foo"].

-> String

Description.

-> Help

Makes a Help object that contains one row in the options table. This function is suitable to add Help to a flag, i.e. an option that doesn't take any additional arguments.

You may pass any number of option forms. However, only the first one of each kind (short and long) will be used.

>>> formatHelp $ makeFlagHelp ["-f", "--foo"] "Description."
"  -f, --foo  Description."

makeParamHelp

Arguments

:: [OptionForm]

All parameter forms, e.g. ["-i", "--input"].

-> String

Metavariable describing the additional argument, e.g. "FILE".

-> String

Description.

-> Help

Makes a Help object that contains one row in the options table. This function is suitable to add Help to a parameter, i.e. an option that takes one additional argument.

You may pass any number of option forms. However, only the first one of each kind (short and long) will be used.

>>> formatHelp $ makeParamHelp ["-i", "--input"] "FILE" "Input file."
"  -i, --input=FILE  Input file."

makeMultiParamHelp

Arguments

:: [OptionForm]

All multiparameter forms, e.g. ["-n", "--full-name"].

-> String

Free-form description for the additional arguments, e.g. "FIRST LAST".

-> String

Description.

-> Help

Makes a Help object that contains one row in the options table. This function is suitable to add Help to a multi-parameter, i.e. an option that takes an arbitrary number of additional arguments.

In practice this behaves almost the same as makeParamHelp, except it advertises a slightly different syntax for passing additional arguments: as proper additional arguments, without '='.

You may pass any number of option forms. However, only the first one of each kind (short and long) will be used.

>>> formatHelp $ makeMultiParamHelp ["-n", "--full-name"] "FIRST LAST" "First and last name."
"  -n, --full-name FIRST LAST  First and last name."

makeFreeArgHelp

Arguments

:: String

Metavariable, e.g. "FILE".

-> String

Description.

-> Help

Makes a Help object that contains one row in the options table. This function is suitable to add Help to a free argument.

>>> formatHelp $ makeFreeArgHelp "FILE" "Input file."
"  FILE  Input file."

Modifiers

clearHelpHeader :: Help -> Help

Clears the header of a Help object. Doesn't affect the options table and the footer.

clearHelpFooter :: Help -> Help

Clears the footer of a Help object. Doesn't affect the header and the options table.

clearHelpTable :: Help -> Help

Clears the options table of a Help object. Doesn't affect the header and the footer.

sortHelpTable :: Help -> Help

Sorts the options table so that:

• Free argument options go first, proper options go second.
• Free arguments are sorted lexicographically by metavariable, then by description.
• Options are sorted lexicographically by short form, then by long form, then by description.