Safe Haskell | Safe-Inferred |
---|---|
Language | GHC2021 |
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 optionDisplay "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)
Synopsis
- displayHelp :: Help -> Text
- displayHelpBox :: Help -> Box
- displayBoxRegistry :: Registry _ _
- displayAllBox :: Display "title" Help Box -> Display "usage" Help Box -> Display "options" Help Box -> Display "commands" Help Box -> Display "any" Help Box
- displayHelpTitleBox :: Display "command-title" Help Box -> Display "title" Help Box
- displayUsageBox :: Display "option-usage" OptionDescription Box -> Display "usage" Help Box
- displayOptionsBox :: Display "command-options" [OptionDescription] Box -> Display "options" Help Box
- displayCommandsBox :: TableParameters -> Display "command-summary" Help [Box] -> Display "command-detail" Help Box -> Display "commands" Help Box
- displayCommandSummaryBox :: Display "command-summary" Help [Box]
- displayCommandDetailBox :: TableParameters -> Display "command-title" Help Box -> Display "command-usage" Help Box -> Display "option" OptionDescription [Box] -> Display "command-detail" Help Box
- displayCommandTitleBox :: ParagraphWidth -> Display "command-title" Help Box
- displayCommandUsageBox :: Display "option-usage" OptionDescription Box -> Display "command-usage" Help Box
- displayCommandOptionsBox :: TableParameters -> Display "option" OptionDescription [Box] -> Display "command-options" [OptionDescription] Box
- displayOptionBox :: TableParameters -> Display "option" OptionDescription [Box] -> Display "option" OptionDescription Box
- displayOptionBoxes :: Display "option-flag" OptionDescription Box -> Display "option-help" OptionDescription Box -> Display "option" OptionDescription [Box]
- displayOptionUsageBox :: Display "metavar-usage" OptionDescription Box -> Display "option-usage" OptionDescription Box
- displayOptionFlagBox :: Display "metavar" OptionDescription Box -> Display "option-flag" OptionDescription Box
- displayOptionHelpBox :: ParagraphWidth -> Display "option-help" OptionDescription Box
- displayMetavarUsageBox :: Display "metavar-usage" OptionDescription Box
- displayMetavarBox :: Display "metavar" OptionDescription Box
- isEmpty :: Box -> Bool
- separate :: Box -> [Box] -> Box
- piped :: [Box] -> Box
- commaed :: [Box] -> Box
- brackets :: Box -> Box
- parens :: Box -> Box
- hsepNonEmpty :: [Box] -> Box
- hcatNonEmpty :: [Box] -> Box
- vsepNonEmpty :: [Box] -> Box
- vcatNonEmpty :: [Box] -> Box
- mText :: Maybe Text -> Box
- tText :: Text -> Box
- (<:>) :: Box -> Box -> Box
- renderBox :: Box -> Text
- table :: TableParameters -> [[Box]] -> Box
- paragraph :: ParagraphWidth -> Text -> Box
- mParagraph :: ParagraphWidth -> Maybe Text -> Box
- newtype ParagraphWidth = ParagraphWidth Int
- data TableParameters = TableParameters {
- horizontalAlignment :: Alignment
- verticalAlignment :: Alignment
- intercolumn :: Int
Documentation
displayHelp :: Help -> Text Source #
Default display for a Help Text
displayHelpBox :: Help -> Box Source #
Default display for a Help Box
displayBoxRegistry :: Registry _ _ Source #
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 Source #
- 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 Source #
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 Source #
Example
USAGE
fs [-h|--help] [-v|--version] [copy] [move]
displayOptionsBox :: Display "command-options" [OptionDescription] Box -> Display "options" Help Box Source #
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 Source #
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] Source #
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 Source #
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 Source #
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 Source #
Example
fs move [-h|--help] [-f|--force] [SOURCE] [TARGET]
displayCommandOptionsBox :: TableParameters -> Display "option" OptionDescription [Box] -> Display "command-options" [OptionDescription] Box Source #
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 Source #
Example
- h,--help BOOL Display this help message
displayOptionBoxes :: Display "option-flag" OptionDescription Box -> Display "option-help" OptionDescription Box -> Display "option" OptionDescription [Box] Source #
Example
- h,--help BOOL Display this help message
displayOptionUsageBox :: Display "metavar-usage" OptionDescription Box -> Display "option-usage" OptionDescription Box Source #
Example
- -h|--help
- -f|--file FILE
displayOptionFlagBox :: Display "metavar" OptionDescription Box -> Display "option-flag" OptionDescription Box Source #
Example
- h,--help BOOL
displayOptionHelpBox :: ParagraphWidth -> Display "option-help" OptionDescription Box Source #
Example
Display this help message
displayMetavarUsageBox :: Display "metavar-usage" OptionDescription Box Source #
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 Source #
Display a metavar in a full help text
- Char
- is transformed to String
isEmpty :: Box -> Bool Source #
Return True if a Box is Empty The best we can do is to render the box and compare it to the empty text
hsepNonEmpty :: [Box] -> Box Source #
Remove empty docs and use hsep
hcatNonEmpty :: [Box] -> Box Source #
Remove empty docs and use hcat
vsepNonEmpty :: [Box] -> Box Source #
Remove empty docs and use vsep
vcatNonEmpty :: [Box] -> Box Source #
Remove empty docs and use vcat
renderBox :: Box -> Text Source #
Render a Box as Text The render function for boxes adds one last newline which we want to avoid
table :: TableParameters -> [[Box]] -> Box Source #
Display a table given a list of rows containing boxes
paragraph :: ParagraphWidth -> Text -> Box Source #
Create a paragraph for some Text, wrapping the text at paragraph width
mParagraph :: ParagraphWidth -> Maybe Text -> Box Source #
Create a paragraph for an option piece of text
newtype ParagraphWidth Source #
Width of paragraph, used in conjunction with the paragraph
function
Instances
Num ParagraphWidth Source # | |
Defined in Data.Registry.Options.DisplayHelpBox (+) :: ParagraphWidth -> ParagraphWidth -> ParagraphWidth # (-) :: ParagraphWidth -> ParagraphWidth -> ParagraphWidth # (*) :: ParagraphWidth -> ParagraphWidth -> ParagraphWidth # negate :: ParagraphWidth -> ParagraphWidth # abs :: ParagraphWidth -> ParagraphWidth # signum :: ParagraphWidth -> ParagraphWidth # fromInteger :: Integer -> ParagraphWidth # | |
Show ParagraphWidth Source # | |
Defined in Data.Registry.Options.DisplayHelpBox showsPrec :: Int -> ParagraphWidth -> ShowS # show :: ParagraphWidth -> String # showList :: [ParagraphWidth] -> ShowS # | |
Eq ParagraphWidth Source # | |
Defined in Data.Registry.Options.DisplayHelpBox (==) :: ParagraphWidth -> ParagraphWidth -> Bool # (/=) :: ParagraphWidth -> ParagraphWidth -> Bool # |
data TableParameters Source #
Those parameters are used when creating a table with the
table
function
TableParameters | |
|
Instances
Show TableParameters Source # | |
Defined in Data.Registry.Options.DisplayHelpBox showsPrec :: Int -> TableParameters -> ShowS # show :: TableParameters -> String # showList :: [TableParameters] -> ShowS # | |
Eq TableParameters Source # | |
Defined in Data.Registry.Options.DisplayHelpBox (==) :: TableParameters -> TableParameters -> Bool # (/=) :: TableParameters -> TableParameters -> Bool # |