Data.Registry.Options.DisplayHelpBox

Support for displaying a full help message as a Box (https:/hackage.haskell.orgpackage/boxes)

The main display function uses a registry to register various Display "name" Data Box values which depend on each other

Display "name" Data Box is responsible for the display of Data in the section "name" as a Box, which can then be rendered as Text with renderBox.

For example there is a Display "command-options" Help Box to display the options of a given command (represented as a Help value) in 2 columns: option flags / option help text.

This Display value depends on 2 other Display values:

• Display "option-flag" OptionDescription Box to display the flag of an option
• Display "option-help" OptionDescription Box to display the help of an option

It is possible to modify the display of the overall help of a command by adding a different display on top of the registry of displays. For example @ myDisplayBoxRegistry = fun myDisplayOptionFlagBox <: displayBoxRegistry

myDisplayOptionFlagBox :: Display "option-flag" OptionDescription Box myDisplayOptionFlagBox = Display $ fromMaybe "" . _name -- just use the option long name

myDisplayHelp :: Help -> Box myDisplayHelp = renderBox . display (make (Display "any" Help Box) myDisplayBoxRegistry)

Documentation

displayHelp :: Help -> Text

Default display for a Help Text

displayHelpBox :: Help -> Box

Default display for a Help Box

displayBoxRegistry :: Registry _ _

This registry provides overridable functions for displaying various parts of a help text.

It can be overridden to display the help differently

displayAllBox :: Display "title" Help Box -> Display "usage" Help Box -> Display "options" Help Box -> Display "commands" Help Box -> Display "any" Help Box

• Template*

Display "title" Help Box

Display "usage" Help Box

Display "commands" Help Box

• Example*

fs - a utility to copy and move files",

USAGE

fs [-h|--help] [-v|--version] [copy] [move]

OPTIONS

• h,--help BOOL Display this help message
• v,--version BOOL Display the version

COMMANDS

copy [OPTIONS] copy a file from SOURCE to TARGET move [OPTIONS] move a file from SOURCE to TARGET

fs copy - copy a file from SOURCE to TARGET

fs copy [-h|--help] [-f|--force] [-r|--retries INT] [SOURCE] [TARGET]

• h,--help BOOL Display this help message
• f,--force BOOL Force the action even if a file already exists with the same name
• r,--retries INT number of retries in case of an error SOURCE Source path TARGET Target path

fs move - move a file from SOURCE to TARGET

fs move [-h|--help] [-f|--force] [SOURCE] [TARGET]

• h,--help BOOL Display this help message
• f,--force BOOL Force the action even if a file already exists with the same name SOURCE Source path TARGET Target path

displayHelpTitleBox :: Display "command-title" Help Box -> Display "title" Help Box

Example

fs - a utility to copy and move files

We reused the display for a command title, which should work for either a top-level or a sub command

displayUsageBox :: Display "option-usage" OptionDescription Box -> Display "usage" Help Box

Example

USAGE

fs [-h|--help] [-v|--version] [copy] [move]

displayOptionsBox :: Display "command-options" [OptionDescription] Box -> Display "options" Help Box

Example

OPTIONS

• h,--help BOOL Display this help message
• v,--version BOOL Display the version

displayCommandsBox :: TableParameters -> Display "command-summary" Help [Box] -> Display "command-detail" Help Box -> Display "commands" Help Box

Example

COMMANDS

copy [OPTIONS] copy a file from SOURCE to TARGET move [OPTIONS] move a file from SOURCE to TARGET

fs copy - copy a file from SOURCE to TARGET

fs copy [-h|--help] [-f|--force] [-r|--retries INT] [SOURCE] [TARGET]

• h,--help BOOL Display this help message
• f,--force BOOL Force the action even if a file already exists with the same name
• r,--retries INT number of retries in case of an error SOURCE Source path TARGET Target path

fs move - move a file from SOURCE to TARGET

fs move [-h|--help] [-f|--force] [SOURCE] [TARGET]

• h,--help BOOL Display this help message
• f,--force BOOL Force the action even if a file already exists with the same name SOURCE Source path TARGET Target path

displayCommandSummaryBox :: Display "command-summary" Help [Box]

Example

copy [OPTIONS] copy a file from SOURCE to TARGET"

displayCommandDetailBox :: TableParameters -> Display "command-title" Help Box -> Display "command-usage" Help Box -> Display "option" OptionDescription [Box] -> Display "command-detail" Help Box

Example

fs move - move a file from SOURCE to TARGET

fs move [-h|--help] [-f|--force] [SOURCE] [TARGET]

• h,--help BOOL Display this help message
• f,--force BOOL Force the action even if a file already exists with the same name SOURCE Source path TARGET Target path

displayCommandTitleBox :: ParagraphWidth -> Display "command-title" Help Box

Example

fs move - move a file from SOURCE to TARGET

• the parent command name is appended to the command name if the parent is defined
• if the command is a default subcommand the name is parenthesized

displayCommandUsageBox :: Display "option-usage" OptionDescription Box -> Display "command-usage" Help Box

Example

fs move [-h|--help] [-f|--force] [SOURCE] [TARGET]

displayCommandOptionsBox :: TableParameters -> Display "option" OptionDescription [Box] -> Display "command-options" [OptionDescription] Box

Example

• h,--help BOOL Display this help message
• f,--force BOOL Force the action even if a file already exists with the same name

displayOptionBox :: TableParameters -> Display "option" OptionDescription [Box] -> Display "option" OptionDescription Box

Example

• h,--help BOOL Display this help message

displayOptionBoxes :: Display "option-flag" OptionDescription Box -> Display "option-help" OptionDescription Box -> Display "option" OptionDescription [Box]

Example

• h,--help BOOL Display this help message

displayOptionUsageBox :: Display "metavar-usage" OptionDescription Box -> Display "option-usage" OptionDescription Box

Example

-h|--help

-f|--file FILE

displayOptionFlagBox :: Display "metavar" OptionDescription Box -> Display "option-flag" OptionDescription Box

Example

• h,--help BOOL

displayOptionHelpBox :: ParagraphWidth -> Display "option-help" OptionDescription Box

Example

Display this help message

displayMetavarUsageBox :: Display "metavar-usage" OptionDescription Box

Display a metavar, except for a switch because it is obvious that it is a boolean or for a String flag

Example

FILE

displayMetavarBox :: Display "metavar" OptionDescription Box

Display a metavar in a full help text

Char

is transformed to String

isEmpty :: Box -> Bool

Return True if a Box is Empty The best we can do is to render the box and compare it to the empty text

separate :: Box -> [Box] -> Box

Separate a list of Boxes with a separator

piped :: [Box] -> Box

Separate a list of boxes with a pipe

commaed :: [Box] -> Box

Separate a list of boxes with a comma

brackets :: Box -> Box

Add brackets to a Box

parens :: Box -> Box

Add parens to a Box

hsepNonEmpty :: [Box] -> Box

Remove empty docs and use hsep

hcatNonEmpty :: [Box] -> Box

Remove empty docs and use hcat

vsepNonEmpty :: [Box] -> Box

Remove empty docs and use vsep

vcatNonEmpty :: [Box] -> Box

Remove empty docs and use vcat

mText :: Maybe Text -> Box

Create a box for non empty text

tText :: Text -> Box

Create a box for a Text value instead of a String

(<:>) :: Box -> Box -> Box

Non-clashing append operator for boxes

renderBox :: Box -> Text

Render a Box as Text The render function for boxes adds one last newline which we want to avoid

table :: TableParameters -> [[Box]] -> Box

Display a table given a list of rows containing boxes

paragraph :: ParagraphWidth -> Text -> Box

Create a paragraph for some Text, wrapping the text at paragraph width

mParagraph :: ParagraphWidth -> Maybe Text -> Box

Create a paragraph for an option piece of text

newtype ParagraphWidth

Width of paragraph, used in conjunction with the paragraph function

Constructors

ParagraphWidth Int

Instances

Num ParagraphWidth

Defined in Data.Registry.Options.DisplayHelpBox

Methods

(+) :: ParagraphWidth -> ParagraphWidth -> ParagraphWidth

(-) :: ParagraphWidth -> ParagraphWidth -> ParagraphWidth

(*) :: ParagraphWidth -> ParagraphWidth -> ParagraphWidth

negate :: ParagraphWidth -> ParagraphWidth

abs :: ParagraphWidth -> ParagraphWidth

signum :: ParagraphWidth -> ParagraphWidth

fromInteger :: Integer -> ParagraphWidth

Show ParagraphWidth

Defined in Data.Registry.Options.DisplayHelpBox

Methods

showsPrec :: Int -> ParagraphWidth -> ShowS

show :: ParagraphWidth -> String

showList :: [ParagraphWidth] -> ShowS

Eq ParagraphWidth

Defined in Data.Registry.Options.DisplayHelpBox

Methods

(==) :: ParagraphWidth -> ParagraphWidth -> Bool

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

data TableParameters

Those parameters are used when creating a table with the table function

Constructors

TableParameters

Fields

• horizontalAlignment :: Alignment
• verticalAlignment :: Alignment
• intercolumn :: Int

Instances

Show TableParameters

Defined in Data.Registry.Options.DisplayHelpBox

Methods

showsPrec :: Int -> TableParameters -> ShowS

show :: TableParameters -> String

showList :: [TableParameters] -> ShowS

Eq TableParameters

Defined in Data.Registry.Options.DisplayHelpBox

Methods

(==) :: TableParameters -> TableParameters -> Bool

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