-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Utilities and combinators for parsing command line options
--
-- optparse-applicative is a haskell library for parsing options on the
-- command line, and providing a powerful applicative interface for
-- composing them.
--
-- optparse-applicative takes care of reading and validating the
-- arguments passed to the command line, handling and reporting errors,
-- generating a usage line, a comprehensive help screen, and enabling
-- context-sensitive bash, zsh, and fish completions.
--
-- See the included README for detailed instructions and examples, which
-- is also available on github
-- https://github.com/pcapriotti/optparse-applicative.
@package optparse-applicative
@version 0.18.0.0
module Options.Applicative.Help.Levenshtein
-- | Calculate the Damerau-Levenshtein edit distance between two lists
-- (strings).
--
-- This is modified from https://wiki.haskell.org/Edit_distance
-- and is originally from Lloyd Allison's paper "Lazy Dynamic-Programming
-- can be Eager"
--
-- It's been changed though from Levenshtein to Damerau-Levenshtein,
-- which treats transposition of adjacent characters as one change
-- instead of two.
--
-- Complexity O(|a|*(1 + editDistance a b))
editDistance :: Eq a => [a] -> [a] -> Int
module Options.Applicative.Help.Pretty
-- | An associative operation.
--
--
-- >>> [1,2,3] <> [4,5,6]
-- [1,2,3,4,5,6]
--
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>
-- |
-- >>> pipe
-- |
--
pipe :: Doc ann
-- |
-- >>> equals
-- =
--
equals :: Doc ann
-- |
-- >>> backslash
-- \
--
backslash :: Doc ann
-- |
-- >>> slash
-- /
--
slash :: Doc ann
-- |
-- >>> dot
-- .
--
dot :: Doc ann
-- |
-- >>> "a" <> space <> "b"
-- a b
--
--
-- This is mostly used via <+>,
--
--
-- >>> "a" <+> "b"
-- a b
--
space :: Doc ann
-- |
-- >>> comma
-- ,
--
comma :: Doc ann
-- |
-- >>> colon
-- :
--
colon :: Doc ann
-- |
-- >>> semi
-- ;
--
semi :: Doc ann
-- |
-- >>> rbrace
-- }
--
rbrace :: Doc ann
-- |
-- >>> lbrace
-- {
--
lbrace :: Doc ann
-- |
-- >>> rbracket
-- ]
--
rbracket :: Doc ann
-- |
-- >>> lbracket
-- [
--
lbracket :: Doc ann
-- |
-- >>> rangle
-- >
--
rangle :: Doc ann
-- |
-- >>> langle
-- <
--
langle :: Doc ann
-- |
-- >>> rparen
-- )
--
rparen :: Doc ann
-- |
-- >>> lparen
-- (
--
lparen :: Doc ann
-- |
-- >>> dquote
-- "
--
dquote :: Doc ann
-- |
-- >>> squote
-- '
--
squote :: Doc ann
-- |
-- >>> braces "·"
-- {·}
--
braces :: Doc ann -> Doc ann
-- |
-- >>> brackets "·"
-- [·]
--
brackets :: Doc ann -> Doc ann
-- |
-- >>> angles "·"
-- <·>
--
angles :: Doc ann -> Doc ann
-- |
-- >>> parens "·"
-- (·)
--
parens :: Doc ann -> Doc ann
-- |
-- >>> dquotes "·"
-- "·"
--
dquotes :: Doc ann -> Doc ann
-- |
-- >>> squotes "·"
-- '·'
--
squotes :: Doc ann -> Doc ann
-- | (layoutCompact x) lays out the document x without
-- adding any indentation and without preserving annotations. Since no
-- 'pretty' printing is involved, this layouter is very fast. The
-- resulting output contains fewer characters than a prettyprinted
-- version and can be used for output that is read by other programs.
--
--
-- >>> let doc = hang 4 (vsep ["lorem", "ipsum", hang 4 (vsep ["dolor", "sit"])])
--
-- >>> doc
-- lorem
-- ipsum
-- dolor
-- sit
--
--
--
-- >>> let putDocCompact = renderIO System.IO.stdout . layoutCompact
--
-- >>> putDocCompact doc
-- lorem
-- ipsum
-- dolor
-- sit
--
layoutCompact :: Doc ann1 -> SimpleDocStream ann2
-- | A layout algorithm with more lookahead than layoutPretty, that
-- introduces line breaks earlier if the content does not (or will not,
-- rather) fit into one line.
--
-- Consider the following python-ish document,
--
--
-- >>> let fun x = hang 2 ("fun(" <> softline' <> x) <> ")"
--
-- >>> let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))
--
--
-- which we’ll be rendering using the following pipeline (where the
-- layout algorithm has been left open):
--
--
-- >>> import Data.Text.IO as T
--
-- >>> import Prettyprinter.Render.Text
--
-- >>> let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
--
-- >>> let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
--
--
-- If we render this using layoutPretty with a page width of 26
-- characters per line, all the fun calls fit into the first
-- line so they will be put there:
--
--
-- >>> go layoutPretty doc
-- |------------------------|
-- fun(fun(fun(fun(fun(
-- [ abcdef
-- , ghijklm ])))))
-- |------------------------|
--
--
-- Note that this exceeds the desired 26 character page width. The same
-- document, rendered with layoutSmart, fits the layout
-- contstraints:
--
--
-- >>> go layoutSmart doc
-- |------------------------|
-- fun(
-- fun(
-- fun(
-- fun(
-- fun(
-- [ abcdef
-- , ghijklm ])))))
-- |------------------------|
--
--
-- The key difference between layoutPretty and layoutSmart
-- is that the latter will check the potential document until it
-- encounters a line with the same indentation or less than the start of
-- the document. Any line encountered earlier is assumed to belong to the
-- same syntactic structure. layoutPretty checks only the first
-- line.
--
-- Consider for example the question of whether the As fit into
-- the document below:
--
--
-- 1 A
-- 2 A
-- 3 A
-- 4 B
-- 5 B
--
--
-- layoutPretty will check only line 1, ignoring whether e.g. line
-- 2 might already be too wide. By contrast, layoutSmart stops
-- only once it reaches line 4, where the B has the same
-- indentation as the first A.
layoutSmart :: LayoutOptions -> Doc ann -> SimpleDocStream ann
-- | This is the default layout algorithm, and it is used by show,
-- putDoc and hPutDoc.
--
-- layoutPretty commits to rendering something in a
-- certain way if the next element fits the layout constraints; in other
-- words, it has one SimpleDocStream element lookahead when
-- rendering. Consider using the smarter, but a bit less performant,
-- layoutSmart algorithm if the results seem to run off
-- to the right before having lots of line breaks.
layoutPretty :: LayoutOptions -> Doc ann -> SimpleDocStream ann
-- | The default layout options, suitable when you just want some output,
-- and don’t particularly care about the details. Used by the Show
-- instance, for example.
--
--
-- >>> defaultLayoutOptions
-- LayoutOptions {layoutPageWidth = AvailablePerLine 80 1.0}
--
defaultLayoutOptions :: LayoutOptions
-- | Remove all trailing space characters.
--
-- This has some performance impact, because it does an entire additional
-- pass over the SimpleDocStream.
--
-- No trimming will be done inside annotations, which are considered to
-- contain no (trimmable) whitespace, since the annotation might actually
-- be about the whitespace, for example a renderer that colors the
-- background of trailing whitespace, as e.g. git diff can be
-- configured to do.
--
-- Historical note: Since v1.7.0, layoutPretty and
-- layoutSmart avoid producing the trailing whitespace that was
-- the original motivation for creating removeTrailingWhitespace.
-- See https://github.com/quchen/prettyprinter/pull/139 for some
-- background info.
removeTrailingWhitespace :: SimpleDocStream ann -> SimpleDocStream ann
-- | (fuse depth doc) combines text nodes so they can be
-- rendered more efficiently. A fused document is always laid out
-- identical to its unfused version.
--
-- When laying a Document out to a SimpleDocStream, every
-- component of the input is translated directly to the simpler output
-- format. This sometimes yields undesirable chunking when many pieces
-- have been concatenated together.
--
-- For example
--
--
-- >>> "a" <> "b" <> pretty 'c' <> "d"
-- abcd
--
--
-- results in a chain of four entries in a SimpleDocStream,
-- although this is fully equivalent to the tightly packed
--
--
-- >>> "abcd" :: Doc ann
-- abcd
--
--
-- which is only a single SimpleDocStream entry, and can be
-- processed faster.
--
-- It is therefore a good idea to run fuse on concatenations of
-- lots of small strings that are used many times:
--
--
-- >>> let oftenUsed = fuse Shallow ("a" <> "b" <> pretty 'c' <> "d")
--
-- >>> hsep (replicate 5 oftenUsed)
-- abcd abcd abcd abcd abcd
--
fuse :: FusionDepth -> Doc ann -> Doc ann
-- | Change the annotation of a document to a different annotation, or none
-- at all. alterAnnotations for SimpleDocStream.
--
-- Note that the Doc version is more flexible, since it allows
-- changing a single annotation to multiple ones. (SimpleDocTree
-- restores this flexibility again.)
alterAnnotationsS :: (ann -> Maybe ann') -> SimpleDocStream ann -> SimpleDocStream ann'
-- | Change the annotation of a document. reAnnotate for
-- SimpleDocStream.
reAnnotateS :: (ann -> ann') -> SimpleDocStream ann -> SimpleDocStream ann'
-- | Remove all annotations. unAnnotate for SimpleDocStream.
unAnnotateS :: SimpleDocStream ann -> SimpleDocStream xxx
-- | Change the annotations of a Document. Individual annotations
-- can be removed, changed, or replaced by multiple ones.
--
-- This is a general function that combines unAnnotate and
-- reAnnotate, and it is useful for mapping semantic annotations
-- (such as »this is a keyword«) to display annotations (such as »this is
-- red and underlined«), because some backends may not care about certain
-- annotations, while others may.
--
-- Annotations earlier in the new list will be applied earlier, i.e.
-- returning [Bold, Green] will result in a bold document that
-- contains green text, and not vice-versa.
--
-- Since this traverses the entire Doc tree, including
-- parts that are not rendered due to other layouts fitting better, it is
-- preferrable to reannotate after producing the layout by using
-- alterAnnotationsS.
alterAnnotations :: (ann -> [ann']) -> Doc ann -> Doc ann'
-- | Change the annotation of a Document.
--
-- Useful in particular to embed documents with one form of annotation in
-- a more generally annotated document.
--
-- Since this traverses the entire Doc tree, including
-- parts that are not rendered due to other layouts fitting better, it is
-- preferrable to reannotate after producing the layout by using
-- reAnnotateS.
--
-- Since reAnnotate has the right type and satisfies
-- 'reAnnotate id = id', it is used to define the
-- Functor instance of Doc.
reAnnotate :: (ann -> ann') -> Doc ann -> Doc ann'
-- | Remove all annotations.
--
-- Although unAnnotate is idempotent with respect to rendering,
--
--
-- unAnnotate . unAnnotate = unAnnotate
--
--
-- it should not be used without caution, for each invocation traverses
-- the entire contained document. If possible, it is preferrable to
-- unannotate after producing the layout by using unAnnotateS.
unAnnotate :: Doc ann -> Doc xxx
-- | Add an annotation to a Doc. This annotation can then
-- be used by the renderer to e.g. add color to certain parts of the
-- output. For a full tutorial example on how to use it, see the
-- Prettyprinter.Render.Tutorials.StackMachineTutorial or
-- Prettyprinter.Render.Tutorials.TreeRenderingTutorial modules.
--
-- This function is only relevant for custom formats with their own
-- annotations, and not relevant for basic prettyprinting. The predefined
-- renderers, e.g. Prettyprinter.Render.Text, should be enough for
-- the most common needs.
annotate :: ann -> Doc ann -> Doc ann
-- | (surround x l r) surrounds document x with
-- l and r.
--
--
-- >>> surround "·" "A" "Z"
-- A·Z
--
--
-- This is merely an argument reordering of enclose, but
-- allows for definitions like
--
--
-- >>> concatWith (surround dot) ["Prettyprinter", "Render", "Text"]
-- Prettyprinter.Render.Text
--
surround :: Doc ann -> Doc ann -> Doc ann -> Doc ann
-- | (enclose l r x) encloses document x between
-- documents l and r using <>.
--
--
-- >>> enclose "A" "Z" "·"
-- A·Z
--
--
--
-- enclose l r x = l <> x <> r
--
enclose :: Doc ann -> Doc ann -> Doc ann -> Doc ann
-- | (plural n one many) is one if n is
-- 1, and many otherwise. A typical use case is adding
-- a plural "s".
--
--
-- >>> let things = [True]
--
-- >>> let amount = length things
--
-- >>> pretty things <+> "has" <+> pretty amount <+> plural "entry" "entries" amount
-- [True] has 1 entry
--
plural :: (Num amount, Eq amount) => doc -> doc -> amount -> doc
-- | (fillBreak i x) first lays out the document
-- x. It then appends spaces until the width is equal
-- to i. If the width of x is already larger than
-- i, the nesting level is increased by i and a
-- line is appended. When we redefine ptype in the
-- example given in fill to use fillBreak, we get
-- a useful variation of the output:
--
--
-- >>> let types = [("empty","Doc"), ("nest","Int -> Doc -> Doc"), ("fillSep","[Doc] -> Doc")]
--
-- >>> let ptype (name, tp) = fillBreak 5 (pretty name) <+> "::" <+> pretty tp
--
-- >>> "let" <+> align (vcat (map ptype types))
-- let empty :: Doc
-- nest :: Int -> Doc -> Doc
-- fillSep
-- :: [Doc] -> Doc
--
fillBreak :: Int -> Doc ann -> Doc ann
-- | (fill i x) lays out the document x. It then
-- appends spaces until the width is equal to i. If the
-- width of x is already larger, nothing is appended.
--
-- This function is quite useful in practice to output a list of
-- bindings:
--
--
-- >>> let types = [("empty","Doc"), ("nest","Int -> Doc -> Doc"), ("fillSep","[Doc] -> Doc")]
--
-- >>> let ptype (name, tp) = fill 5 (pretty name) <+> "::" <+> pretty tp
--
-- >>> "let" <+> align (vcat (map ptype types))
-- let empty :: Doc
-- nest :: Int -> Doc -> Doc
-- fillSep :: [Doc] -> Doc
--
fill :: Int -> Doc ann -> Doc ann
-- | Layout a document depending on the page width, if one has been
-- specified.
--
--
-- >>> let prettyPageWidth (AvailablePerLine l r) = "Width:" <+> pretty l <> ", ribbon fraction:" <+> pretty r
--
-- >>> let doc = "prefix" <+> pageWidth (brackets . prettyPageWidth)
--
-- >>> putDocW 32 (vsep [indent n doc | n <- [0,4,8]])
-- prefix [Width: 32, ribbon fraction: 1.0]
-- prefix [Width: 32, ribbon fraction: 1.0]
-- prefix [Width: 32, ribbon fraction: 1.0]
--
pageWidth :: (PageWidth -> Doc ann) -> Doc ann
-- | (width doc f) lays out the document doc, and
-- makes the column width of it available to a function.
--
--
-- >>> let annotate doc = width (brackets doc) (\w -> " <- width:" <+> pretty w)
--
-- >>> align (vsep (map annotate ["---", "------", indent 3 "---", vsep ["---", indent 4 "---"]]))
-- [---] <- width: 5
-- [------] <- width: 8
-- [ ---] <- width: 8
-- [---
-- ---] <- width: 8
--
width :: Doc ann -> (Int -> Doc ann) -> Doc ann
-- | Layout a document depending on the current nesting level.
-- align is implemented in terms of nesting.
--
--
-- >>> let doc = "prefix" <+> nesting (\l -> brackets ("Nested:" <+> pretty l))
--
-- >>> vsep [indent n doc | n <- [0,4,8]]
-- prefix [Nested: 0]
-- prefix [Nested: 4]
-- prefix [Nested: 8]
--
nesting :: (Int -> Doc ann) -> Doc ann
-- | Layout a document depending on which column it starts at. align
-- is implemented in terms of column.
--
--
-- >>> column (\l -> "Columns are" <+> pretty l <> "-based.")
-- Columns are 0-based.
--
--
--
-- >>> let doc = "prefix" <+> column (\l -> "| <- column" <+> pretty l)
--
-- >>> vsep [indent n doc | n <- [0,4,8]]
-- prefix | <- column 7
-- prefix | <- column 11
-- prefix | <- column 15
--
column :: (Int -> Doc ann) -> Doc ann
-- | (punctuate p xs) appends p to all but the
-- last document in xs.
--
--
-- >>> let docs = punctuate comma (Util.words "lorem ipsum dolor sit amet")
--
-- >>> putDocW 80 (hsep docs)
-- lorem, ipsum, dolor, sit, amet
--
--
-- The separators are put at the end of the entries, which we can see if
-- we position the result vertically:
--
--
-- >>> putDocW 20 (vsep docs)
-- lorem,
-- ipsum,
-- dolor,
-- sit,
-- amet
--
--
-- If you want put the commas in front of their elements instead of at
-- the end, you should use tupled or, in general,
-- encloseSep.
punctuate :: Doc ann -> [Doc ann] -> [Doc ann]
-- | (cat xs) tries laying out the documents xs
-- separated with nothing, and if this does not fit the page, separates
-- them with newlines. This is what differentiates it from vcat,
-- which always lays out its contents beneath each other.
--
--
-- >>> let docs = Util.words "lorem ipsum dolor"
--
-- >>> putDocW 80 ("Docs:" <+> cat docs)
-- Docs: loremipsumdolor
--
--
-- When there is enough space, the documents are put above one another:
--
--
-- >>> putDocW 10 ("Docs:" <+> cat docs)
-- Docs: lorem
-- ipsum
-- dolor
--
--
--
-- cat = group . vcat
--
cat :: [Doc ann] -> Doc ann
-- | (fillCat xs) concatenates documents xs
-- horizontally with <> as long as it fits the
-- page, then inserts a line' and continues doing that
-- for all documents in xs. This is similar to how an ordinary
-- word processor lays out the text if you just keep typing after you hit
-- the maximum line length.
--
-- (line' means that if grouped, the documents are
-- separated with nothing instead of newlines. See fillSep if you
-- want a space instead.)
--
-- Observe the difference between fillSep and fillCat.
-- fillSep concatenates the entries spaced when
-- grouped:
--
--
-- >>> let docs = take 20 (cycle (["lorem", "ipsum", "dolor", "sit", "amet"]))
--
-- >>> putDocW 40 ("Grouped:" <+> group (fillSep docs))
-- Grouped: lorem ipsum dolor sit amet
-- lorem ipsum dolor sit amet lorem ipsum
-- dolor sit amet lorem ipsum dolor sit
-- amet
--
--
-- On the other hand, fillCat concatenates the entries directly
-- when grouped:
--
--
-- >>> putDocW 40 ("Grouped:" <+> group (fillCat docs))
-- Grouped: loremipsumdolorsitametlorem
-- ipsumdolorsitametloremipsumdolorsitamet
-- loremipsumdolorsitamet
--
fillCat :: [Doc ann] -> Doc ann
-- | (vcat xs) vertically concatenates the documents
-- xs. If it is grouped, the line breaks are removed.
--
-- In other words vcat is like vsep, with
-- newlines removed instead of replaced by spaces.
--
--
-- >>> let docs = Util.words "lorem ipsum dolor"
--
-- >>> vcat docs
-- lorem
-- ipsum
-- dolor
--
-- >>> group (vcat docs)
-- loremipsumdolor
--
--
-- Since grouping a vcat is rather common, cat is a
-- built-in shortcut for it.
vcat :: [Doc ann] -> Doc ann
-- | (hcat xs) concatenates all documents xs
-- horizontally with <> (i.e. without any spacing).
--
-- It is provided only for consistency, since it is identical to
-- mconcat.
--
--
-- >>> let docs = Util.words "lorem ipsum dolor"
--
-- >>> hcat docs
-- loremipsumdolor
--
hcat :: [Doc ann] -> Doc ann
-- | (sep xs) tries laying out the documents xs
-- separated with spaces, and if this does not fit the page,
-- separates them with newlines. This is what differentiates it from
-- vsep, which always lays out its contents beneath each other.
--
--
-- >>> let doc = "prefix" <+> sep ["text", "to", "lay", "out"]
--
-- >>> putDocW 80 doc
-- prefix text to lay out
--
--
-- With a narrower layout, the entries are separated by newlines:
--
--
-- >>> putDocW 20 doc
-- prefix text
-- to
-- lay
-- out
--
--
--
-- sep = group . vsep
--
sep :: [Doc ann] -> Doc ann
-- | (fillSep xs) concatenates the documents xs
-- horizontally with <+> as long as it fits the
-- page, then inserts a line and continues doing that for
-- all documents in xs. (line means that if
-- grouped, the documents are separated with a space
-- instead of newlines. Use fillCat if you do not want a
-- space.)
--
-- Let's print some words to fill the line:
--
--
-- >>> let docs = take 20 (cycle ["lorem", "ipsum", "dolor", "sit", "amet"])
--
-- >>> putDocW 80 ("Docs:" <+> fillSep docs)
-- Docs: lorem ipsum dolor sit amet lorem ipsum dolor sit amet lorem ipsum dolor
-- sit amet lorem ipsum dolor sit amet
--
--
-- The same document, printed at a width of only 40, yields
--
--
-- >>> putDocW 40 ("Docs:" <+> fillSep docs)
-- Docs: lorem ipsum dolor sit amet lorem
-- ipsum dolor sit amet lorem ipsum dolor
-- sit amet lorem ipsum dolor sit amet
--
fillSep :: [Doc ann] -> Doc ann
-- | (vsep xs) concatenates all documents xs above
-- each other. If a group undoes the line breaks inserted by
-- vsep, the documents are separated with a space
-- instead.
--
-- Using vsep alone yields
--
--
-- >>> "prefix" <+> vsep ["text", "to", "lay", "out"]
-- prefix text
-- to
-- lay
-- out
--
--
-- grouping a vsep separates the documents with a
-- space if it fits the page (and does nothing otherwise). See
-- the sep convenience function for this use case.
--
-- The align function can be used to align the documents under
-- their first element:
--
--
-- >>> "prefix" <+> align (vsep ["text", "to", "lay", "out"])
-- prefix text
-- to
-- lay
-- out
--
--
-- Since grouping a vsep is rather common, sep is a
-- built-in for doing that.
vsep :: [Doc ann] -> Doc ann
-- | (hsep xs) concatenates all documents xs
-- horizontally with <+>, i.e. it puts a space
-- between all entries.
--
--
-- >>> let docs = Util.words "lorem ipsum dolor sit amet"
--
--
--
-- >>> hsep docs
-- lorem ipsum dolor sit amet
--
--
-- hsep does not introduce line breaks on its own, even
-- when the page is too narrow:
--
--
-- >>> putDocW 5 (hsep docs)
-- lorem ipsum dolor sit amet
--
--
-- For automatic line breaks, consider using fillSep instead.
hsep :: [Doc ann] -> Doc ann
-- | Concatenate all documents element-wise with a binary function.
--
--
-- concatWith _ [] = mempty
-- concatWith (**) [x,y,z] = x ** y ** z
--
--
-- Multiple convenience definitions based on concatWith are
-- already predefined, for example:
--
--
-- hsep = concatWith (<+>)
-- fillSep = concatWith (\x y -> x <> softline <> y)
--
--
-- This is also useful to define customized joiners:
--
--
-- >>> concatWith (surround dot) ["Prettyprinter", "Render", "Text"]
-- Prettyprinter.Render.Text
--
concatWith :: Foldable t => (Doc ann -> Doc ann -> Doc ann) -> t (Doc ann) -> Doc ann
-- | (x <+> y) concatenates document x and
-- y with a space in between.
--
--
-- >>> "hello" <+> "world"
-- hello world
--
--
--
-- x <+> y = x <> space <> y
--
(<+>) :: Doc ann -> Doc ann -> Doc ann
infixr 6 <+>
-- | Haskell-inspired variant of encloseSep with parentheses and
-- comma as separator.
--
--
-- >>> let doc = tupled (map pretty [1,20,300,4000])
--
--
--
-- >>> putDocW 80 doc
-- (1, 20, 300, 4000)
--
--
--
-- >>> putDocW 10 doc
-- ( 1
-- , 20
-- , 300
-- , 4000 )
--
tupled :: [Doc ann] -> Doc ann
-- | Haskell-inspired variant of encloseSep with braces and comma as
-- separator.
--
--
-- >>> let doc = list (map pretty [1,20,300,4000])
--
--
--
-- >>> putDocW 80 doc
-- [1, 20, 300, 4000]
--
--
--
-- >>> putDocW 10 doc
-- [ 1
-- , 20
-- , 300
-- , 4000 ]
--
list :: [Doc ann] -> Doc ann
-- | (encloseSep l r sep xs) concatenates the documents
-- xs separated by sep, and encloses the resulting
-- document by l and r.
--
-- The documents are laid out horizontally if that fits the page:
--
--
-- >>> let doc = "list" <+> align (encloseSep lbracket rbracket comma (map pretty [1,20,300,4000]))
--
-- >>> putDocW 80 doc
-- list [1,20,300,4000]
--
--
-- If there is not enough space, then the input is split into lines
-- entry-wise therwise they are laid out vertically, with separators put
-- in the front:
--
--
-- >>> putDocW 10 doc
-- list [1
-- ,20
-- ,300
-- ,4000]
--
--
-- Note that doc contains an explicit call to align so
-- that the list items are aligned vertically.
--
-- For putting separators at the end of entries instead, have a look at
-- punctuate.
encloseSep :: Doc ann -> Doc ann -> Doc ann -> [Doc ann] -> Doc ann
-- | (indent i x) indents document x by i
-- columns, starting from the current cursor position.
--
--
-- >>> let doc = reflow "The indent function indents these words!"
--
-- >>> putDocW 24 ("prefix" <> indent 4 doc)
-- prefix The indent
-- function
-- indents these
-- words!
--
--
--
-- indent i d = hang i ({i spaces} <> d)
--
indent :: Int -> Doc ann -> Doc ann
-- | (hang i x) lays out the document x with a
-- nesting level set to the current column plus i.
-- Negative values are allowed, and decrease the nesting level
-- accordingly.
--
--
-- >>> let doc = reflow "Indenting these words with hang"
--
-- >>> putDocW 24 ("prefix" <+> hang 4 doc)
-- prefix Indenting these
-- words with
-- hang
--
--
-- This differs from nest, which is based on the current
-- nesting level plus i. When you're not sure, try the more
-- efficient nest first. In our example, this would yield
--
--
-- >>> let doc = reflow "Indenting these words with nest"
--
-- >>> putDocW 24 ("prefix" <+> nest 4 doc)
-- prefix Indenting these
-- words with nest
--
--
--
-- hang i doc = align (nest i doc)
--
hang :: Int -> Doc ann -> Doc ann
-- | (align x) lays out the document x with the
-- nesting level set to the current column. It is used for example to
-- implement hang.
--
-- As an example, we will put a document right above another one,
-- regardless of the current nesting level. Without alignment, the
-- second line is put simply below everything we've had so far:
--
--
-- >>> "lorem" <+> vsep ["ipsum", "dolor"]
-- lorem ipsum
-- dolor
--
--
-- If we add an align to the mix, the vsep's
-- contents all start in the same column:
--
--
-- >>> "lorem" <+> align (vsep ["ipsum", "dolor"])
-- lorem ipsum
-- dolor
--
align :: Doc ann -> Doc ann
-- | By default, (flatAlt x y) renders as x.
-- However when grouped, y will be preferred, with
-- x as the fallback for the case when y doesn't fit.
--
--
-- >>> let doc = flatAlt "a" "b"
--
-- >>> putDoc doc
-- a
--
-- >>> putDoc (group doc)
-- b
--
-- >>> putDocW 0 (group doc)
-- a
--
--
-- flatAlt is particularly useful for defining conditional
-- separators such as
--
--
-- softline = group (flatAlt hardline " ")
--
--
--
-- >>> let hello = "Hello" <> softline <> "world!"
--
-- >>> putDocW 12 hello
-- Hello world!
--
-- >>> putDocW 11 hello
-- Hello
-- world!
--
--
-- Example: Haskell's do-notation
--
-- We can use this to render Haskell's do-notation nicely:
--
--
-- >>> let open = flatAlt "" "{ "
--
-- >>> let close = flatAlt "" " }"
--
-- >>> let separator = flatAlt "" "; "
--
-- >>> let prettyDo xs = group ("do" <+> align (encloseSep open close separator xs))
--
-- >>> let statements = ["name:_ <- getArgs", "let greet = \"Hello, \" <> name", "putStrLn greet"]
--
--
-- This is put into a single line with {;} style if it fits:
--
--
-- >>> putDocW 80 (prettyDo statements)
-- do { name:_ <- getArgs; let greet = "Hello, " <> name; putStrLn greet }
--
--
-- When there is not enough space the statements are broken up into lines
-- nicely:
--
--
-- >>> putDocW 10 (prettyDo statements)
-- do name:_ <- getArgs
-- let greet = "Hello, " <> name
-- putStrLn greet
--
--
-- Notes
--
-- Users should be careful to choose x to be less wide than
-- y. Otherwise, if y turns out not to fit the page, we
-- fall back on an even wider layout:
--
--
-- >>> let ugly = group (flatAlt "even wider" "too wide")
--
-- >>> putDocW 7 ugly
-- even wider
--
--
-- Also note that group will flatten y:
--
--
-- >>> putDoc (group (flatAlt "x" ("y" <> line <> "y")))
-- y y
--
--
-- This also means that an "unflattenable" y which contains a
-- hard linebreak will never be rendered:
--
--
-- >>> putDoc (group (flatAlt "x" ("y" <> hardline <> "y")))
-- x
--
flatAlt :: Doc ann -> Doc ann -> Doc ann
-- | (group x) tries laying out x into a single
-- line by removing the contained line breaks; if this does not fit the
-- page, or when a hardline within x prevents it from
-- being flattened, x is laid out without any changes.
--
-- The group function is key to layouts that adapt to available
-- space nicely.
--
-- See vcat, line, or flatAlt for examples that are
-- related, or make good use of it.
group :: Doc ann -> Doc ann
-- | A hardline is always laid out as a line break,
-- even when grouped or when there is plenty of space. Note that
-- it might still be simply discarded if it is part of a flatAlt
-- inside a group.
--
--
-- >>> let doc = "lorem ipsum" <> hardline <> "dolor sit amet"
--
-- >>> putDocW 1000 doc
-- lorem ipsum
-- dolor sit amet
--
--
--
-- >>> group doc
-- lorem ipsum
-- dolor sit amet
--
hardline :: Doc ann
-- | softline' is like softline, but
-- behaves like mempty if the resulting output does not
-- fit on the page (instead of space). In other words,
-- line is to line' how
-- softline is to softline'.
--
-- With enough space, we get direct concatenation:
--
--
-- >>> let doc = "ThisWord" <> softline' <> "IsWayTooLong"
--
-- >>> putDocW 80 doc
-- ThisWordIsWayTooLong
--
--
-- If we narrow the page to width 10, the layouter produces a line break:
--
--
-- >>> putDocW 10 doc
-- ThisWord
-- IsWayTooLong
--
--
--
-- softline' = group line'
--
softline' :: Doc ann
-- | softline behaves like space if the
-- resulting output fits the page, otherwise like line.
--
-- Here, we have enough space to put everything in one line:
--
--
-- >>> let doc = "lorem ipsum" <> softline <> "dolor sit amet"
--
-- >>> putDocW 80 doc
-- lorem ipsum dolor sit amet
--
--
-- If we narrow the page to width 10, the layouter produces a line break:
--
--
-- >>> putDocW 10 doc
-- lorem ipsum
-- dolor sit amet
--
--
--
-- softline = group line
--
softline :: Doc ann
-- | line' is like line, but behaves like
-- mempty if the line break is undone by group
-- (instead of space).
--
--
-- >>> let doc = "lorem ipsum" <> line' <> "dolor sit amet"
--
-- >>> doc
-- lorem ipsum
-- dolor sit amet
--
-- >>> group doc
-- lorem ipsumdolor sit amet
--
line' :: Doc ann
-- | The line document advances to the next line and
-- indents to the current nesting level.
--
--
-- >>> let doc = "lorem ipsum" <> line <> "dolor sit amet"
--
-- >>> doc
-- lorem ipsum
-- dolor sit amet
--
--
-- line behaves like space if the line
-- break is undone by group:
--
--
-- >>> group doc
-- lorem ipsum dolor sit amet
--
line :: Doc ann
-- | (nest i x) lays out the document x with the
-- current nesting level (indentation of the following lines) increased
-- by i. Negative values are allowed, and decrease the nesting
-- level accordingly.
--
--
-- >>> vsep [nest 4 (vsep ["lorem", "ipsum", "dolor"]), "sit", "amet"]
-- lorem
-- ipsum
-- dolor
-- sit
-- amet
--
--
-- See also
--
--
-- - hang (nest relative to current cursor position
-- instead of current nesting level)
-- - align (set nesting level to current cursor position)
-- - indent (increase indentation on the spot, padding with
-- spaces).
--
nest :: Int -> Doc ann -> Doc ann
-- | The empty document behaves like (pretty ""), so it has
-- a height of 1. This may lead to surprising behaviour if we expect it
-- to bear no weight inside e.g. vcat, where we get an empty line
-- of output from it (parens for visibility only):
--
--
-- >>> vsep ["hello", parens emptyDoc, "world"]
-- hello
-- ()
-- world
--
--
-- Together with <>, emptyDoc forms the Monoid
-- Doc.
emptyDoc :: Doc ann
-- | Convenience function to convert a Showable value /that must not
-- contain newlines/ to a Doc. If there may be newlines, use
-- viaShow instead.
unsafeViaShow :: Show a => a -> Doc ann
-- | Convenience function to convert a Showable value to a
-- Doc. If the String does not contain newlines, consider
-- using the more performant unsafeViaShow.
viaShow :: Show a => a -> Doc ann
-- | Overloaded conversion to Doc.
--
-- Laws:
--
--
-- - output should be pretty. :-)
--
class Pretty a
-- |
-- >>> pretty 1 <+> pretty "hello" <+> pretty 1.234
-- 1 hello 1.234
--
pretty :: Pretty a => a -> Doc ann
-- | prettyList is only used to define the instance
-- Pretty a => Pretty [a]. In normal circumstances
-- only the pretty function is used.
--
--
-- >>> prettyList [1, 23, 456]
-- [1, 23, 456]
--
prettyList :: Pretty a => [a] -> Doc ann
-- | Fusion depth parameter, used by fuse.
data FusionDepth
-- | Do not dive deep into nested documents, fusing mostly concatenations
-- of text nodes together.
Shallow :: FusionDepth
-- | Recurse into all parts of the Doc, including different layout
-- alternatives, and location-sensitive values such as created by
-- nesting which cannot be fused before, but only during, the
-- layout process. As a result, the performance cost of using deep fusion
-- is often hard to predict, and depends on the interplay between page
-- layout and document to prettyprint.
--
-- This value should only be used if profiling shows it is significantly
-- faster than using Shallow.
Deep :: FusionDepth
-- | The data type SimpleDocStream represents laid out documents
-- and is used by the display functions.
--
-- A simplified view is that Doc =
-- [SimpleDocStream], and the layout functions pick one of
-- the SimpleDocStreams based on which one fits the layout
-- constraints best. This means that SimpleDocStream has all
-- complexity contained in Doc resolved, making it very easy to
-- convert it to other formats, such as plain text or terminal output.
--
-- To write your own Doc to X converter, it is therefore
-- sufficient to convert from SimpleDocStream. The
-- »Render« submodules provide some built-in converters to do so, and
-- helpers to create own ones.
data SimpleDocStream ann
SFail :: SimpleDocStream ann
SEmpty :: SimpleDocStream ann
SChar :: !Char -> SimpleDocStream ann -> SimpleDocStream ann
-- | length is O(n), so we cache it in the Int field.
SText :: !Int -> !Text -> SimpleDocStream ann -> SimpleDocStream ann
-- | Int = indentation level for the (next) line
SLine :: !Int -> SimpleDocStream ann -> SimpleDocStream ann
-- | Add an annotation to the remaining document.
SAnnPush :: ann -> SimpleDocStream ann -> SimpleDocStream ann
-- | Remove a previously pushed annotation.
SAnnPop :: SimpleDocStream ann -> SimpleDocStream ann
-- | Maximum number of characters that fit in one line. The layout
-- algorithms will try not to exceed the set limit by inserting line
-- breaks when applicable (e.g. via softline').
data PageWidth
-- | Layouters should not exceed the specified space per line.
--
--
-- - The Int is the number of characters, including whitespace,
-- that fit in a line. A typical value is 80.
-- - The Double is the ribbon with, i.e. the fraction of the
-- total page width that can be printed on. This allows limiting the
-- length of printable text per line. Values must be between 0 and 1, and
-- 0.4 to 1 is typical.
--
AvailablePerLine :: !Int -> !Double -> PageWidth
-- | Layouters should not introduce line breaks on their own.
Unbounded :: PageWidth
-- | Options to influence the layout algorithms.
newtype LayoutOptions
LayoutOptions :: PageWidth -> LayoutOptions
[layoutPageWidth] :: LayoutOptions -> PageWidth
type Doc = Doc AnsiStyle
type SimpleDoc = SimpleDocStream AnsiStyle
(.$.) :: Doc -> Doc -> Doc
() :: Doc -> Doc -> Doc
-- | Render flattened text on this line, or start a new line before
-- rendering any text.
--
-- This will also nest subsequent lines in the group.
groupOrNestLine :: Doc -> Doc
-- | Separate items in an alternative with a pipe.
--
-- If the first document and the pipe don't fit on the line, then
-- mandatorily flow the next entry onto the following line.
--
-- The (//) softbreak ensures that if the document does fit on the
-- line, there is at least a space, but it's possible for y to still
-- appear on the next line.
altSep :: Doc -> Doc -> Doc
-- | Printer hacks to get nice indentation for long commands and
-- subcommands.
--
-- If we're starting this section over the desired width (usually 1/3 of
-- the ribbon), then we will make a line break, indent all of the usage,
-- and go.
--
-- The ifAtRoot is an interesting clause. If this whole operation is put
-- under a group then the linebreak will disappear; then item d
-- will therefore not be at the starting column, and it won't be indented
-- more.
hangAtIfOver :: Int -> Int -> Doc -> Doc
prettyString :: Double -> Int -> Doc -> String
module Options.Applicative.Help.Chunk
-- | The free monoid on a semigroup a.
newtype Chunk a
Chunk :: Maybe a -> Chunk a
[unChunk] :: Chunk a -> Maybe a
-- | Given a semigroup structure on a, return a monoid structure
-- on 'Chunk a'.
--
-- Note that this is not the same as liftA2.
chunked :: (a -> a -> a) -> Chunk a -> Chunk a -> Chunk a
-- | Concatenate a list into a Chunk. listToChunk satisfies:
--
--
-- isEmpty . listToChunk = null
-- listToChunk = mconcat . fmap pure
--
listToChunk :: Semigroup a => [a] -> Chunk a
-- | Concatenate two Chunks with a space in between. If one is
-- empty, this just returns the other one.
--
-- Unlike <+> for Doc, this operation has a unit
-- element, namely the empty Chunk.
(<<+>>) :: Chunk Doc -> Chunk Doc -> Chunk Doc
-- | Concatenate two Chunks with a softline in between. This is
-- exactly like <<+>>, but uses a softline instead of
-- a space.
(<>) :: Chunk Doc -> Chunk Doc -> Chunk Doc
-- | Concatenate Chunks vertically.
vcatChunks :: [Chunk Doc] -> Chunk Doc
-- | Concatenate Chunks vertically separated by empty lines.
vsepChunks :: [Chunk Doc] -> Chunk Doc
-- | Whether a Chunk is empty. Note that something like 'pure
-- mempty' is not considered an empty chunk, even though the underlying
-- Doc is empty.
isEmpty :: Chunk a -> Bool
-- | Convert a String into a Chunk. This satisfies:
--
--
-- isEmpty . stringChunk = null
-- extractChunk . stringChunk = string
--
stringChunk :: String -> Chunk Doc
-- | Convert a paragraph into a Chunk. The resulting chunk is
-- composed by the words of the original paragraph separated by
-- softlines, so it will be automatically word-wrapped when rendering the
-- underlying document.
--
-- This satisfies:
--
--
-- isEmpty . paragraph = null . words
--
paragraph :: String -> Chunk Doc
-- | Part of a constrained comonad instance.
--
-- This is the counit of the adjunction between Chunk and the
-- forgetful functor from monoids to semigroups. It satisfies:
--
--
-- extractChunk . pure = id
-- extractChunk . fmap pure = id
--
extractChunk :: Monoid a => Chunk a -> a
-- | Display pairs of strings in a table.
tabulate :: Int -> [(Doc, Doc)] -> Chunk Doc
instance GHC.Show.Show a => GHC.Show.Show (Options.Applicative.Help.Chunk.Chunk a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Options.Applicative.Help.Chunk.Chunk a)
instance GHC.Base.Functor Options.Applicative.Help.Chunk.Chunk
instance GHC.Base.Applicative Options.Applicative.Help.Chunk.Chunk
instance GHC.Base.Alternative Options.Applicative.Help.Chunk.Chunk
instance GHC.Base.Monad Options.Applicative.Help.Chunk.Chunk
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Options.Applicative.Help.Chunk.Chunk a)
instance GHC.Base.Semigroup a => GHC.Base.Monoid (Options.Applicative.Help.Chunk.Chunk a)
instance GHC.Base.MonadPlus Options.Applicative.Help.Chunk.Chunk
module Options.Applicative.Help.Types
data ParserHelp
ParserHelp :: Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> ParserHelp
[helpError] :: ParserHelp -> Chunk Doc
[helpSuggestions] :: ParserHelp -> Chunk Doc
[helpHeader] :: ParserHelp -> Chunk Doc
[helpUsage] :: ParserHelp -> Chunk Doc
[helpDescription] :: ParserHelp -> Chunk Doc
[helpBody] :: ParserHelp -> Chunk Doc
[helpGlobals] :: ParserHelp -> Chunk Doc
[helpFooter] :: ParserHelp -> Chunk Doc
-- | Convert a help text to String.
renderHelp :: Int -> ParserHelp -> String
instance GHC.Show.Show Options.Applicative.Help.Types.ParserHelp
instance GHC.Base.Monoid Options.Applicative.Help.Types.ParserHelp
instance GHC.Base.Semigroup Options.Applicative.Help.Types.ParserHelp
module Options.Applicative.Types
data ParseError
ErrorMsg :: String -> ParseError
InfoMsg :: String -> ParseError
ShowHelpText :: Maybe String -> ParseError
UnknownError :: ParseError
MissingError :: IsCmdStart -> SomeParser -> ParseError
ExpectsArgError :: String -> ParseError
UnexpectedError :: String -> SomeParser -> ParseError
-- | A full description for a runnable Parser for a program.
data ParserInfo a
ParserInfo :: Parser a -> Bool -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Int -> ArgPolicy -> ParserInfo a
-- | the option parser for the program
[infoParser] :: ParserInfo a -> Parser a
-- | whether the help text should contain full documentation
[infoFullDesc] :: ParserInfo a -> Bool
-- | brief parser description
[infoProgDesc] :: ParserInfo a -> Chunk Doc
-- | header of the full parser description
[infoHeader] :: ParserInfo a -> Chunk Doc
-- | footer of the full parser description
[infoFooter] :: ParserInfo a -> Chunk Doc
-- | exit code for a parser failure
[infoFailureCode] :: ParserInfo a -> Int
-- | allow regular options and flags to occur after arguments (default:
-- InterspersePolicy)
[infoPolicy] :: ParserInfo a -> ArgPolicy
-- | Global preferences for a top-level Parser.
data ParserPrefs
ParserPrefs :: String -> Bool -> Bool -> Bool -> Backtracking -> Int -> Bool -> Bool -> Int -> ParserPrefs
-- | metavar suffix for multiple options
[prefMultiSuffix] :: ParserPrefs -> String
-- | automatically disambiguate abbreviations (default: False)
[prefDisambiguate] :: ParserPrefs -> Bool
-- | always show help text on parse errors (default: False)
[prefShowHelpOnError] :: ParserPrefs -> Bool
-- | show the help text for a command or subcommand if it fails with no
-- input (default: False)
[prefShowHelpOnEmpty] :: ParserPrefs -> Bool
-- | backtrack to parent parser when a subcommand fails (default:
-- Backtrack)
[prefBacktrack] :: ParserPrefs -> Backtracking
-- | number of columns in the terminal, used to format the help page
-- (default: 80)
[prefColumns] :: ParserPrefs -> Int
-- | when displaying long names in usage and help, use an '=' sign for long
-- names, rather than a single space (default: False)
[prefHelpLongEquals] :: ParserPrefs -> Bool
-- | when displaying subparsers' usage help, show parent options under a
-- "global options" section (default: False)
[prefHelpShowGlobal] :: ParserPrefs -> Bool
-- | Indentation width for tables
[prefTabulateFill] :: ParserPrefs -> Int
-- | A single option of a parser.
data Option a
Option :: OptReader a -> OptProperties -> Option a
-- | reader for this option
[optMain] :: Option a -> OptReader a
-- | properties of this option
[optProps] :: Option a -> OptProperties
data OptName
OptShort :: !Char -> OptName
OptLong :: !String -> OptName
isShortName :: OptName -> Bool
isLongName :: OptName -> Bool
-- | An OptReader defines whether an option matches an command line
-- argument.
data OptReader a
-- | option reader
OptReader :: [OptName] -> CReader a -> (String -> ParseError) -> OptReader a
-- | flag reader
FlagReader :: [OptName] -> !a -> OptReader a
-- | argument reader
ArgReader :: CReader a -> OptReader a
-- | command reader
CmdReader :: Maybe String -> [(String, ParserInfo a)] -> OptReader a
-- | Specification for an individual parser option.
data OptProperties
OptProperties :: OptVisibility -> Chunk Doc -> String -> Maybe String -> Bool -> Maybe (Doc -> Doc) -> OptProperties
-- | whether this flag is shown in the brief description
[propVisibility] :: OptProperties -> OptVisibility
-- | help text for this option
[propHelp] :: OptProperties -> Chunk Doc
-- | metavariable for this option
[propMetaVar] :: OptProperties -> String
-- | what to show in the help text as the default
[propShowDefault] :: OptProperties -> Maybe String
-- | whether the option is presented in global options text
[propShowGlobal] :: OptProperties -> Bool
-- | a function to run over the brief description
[propDescMod] :: OptProperties -> Maybe (Doc -> Doc)
-- | Visibility of an option in the help text.
data OptVisibility
-- | does not appear in the help text at all
Internal :: OptVisibility
-- | only visible in the full description
Hidden :: OptVisibility
-- | visible both in the full and brief descriptions
Visible :: OptVisibility
data Backtracking
Backtrack :: Backtracking
NoBacktrack :: Backtracking
SubparserInline :: Backtracking
-- | A newtype over 'ReaderT String Except', used by option readers.
newtype ReadM a
ReadM :: ReaderT String (Except ParseError) a -> ReadM a
[unReadM] :: ReadM a -> ReaderT String (Except ParseError) a
-- | Return the value being read.
readerAsk :: ReadM String
-- | Abort option reader by exiting with a ParseError.
readerAbort :: ParseError -> ReadM a
-- | Abort option reader by exiting with an error message.
readerError :: String -> ReadM a
data CReader a
CReader :: Completer -> ReadM a -> CReader a
[crCompleter] :: CReader a -> Completer
[crReader] :: CReader a -> ReadM a
-- | A Parser a is an option parser returning a value of type
-- a.
data Parser a
NilP :: Maybe a -> Parser a
OptP :: Option a -> Parser a
MultP :: Parser (x -> a) -> Parser x -> Parser a
AltP :: Parser a -> Parser a -> Parser a
BindP :: Parser x -> (x -> Parser a) -> Parser a
newtype ParserM r
ParserM :: (forall x. (r -> Parser x) -> Parser x) -> ParserM r
[runParserM] :: ParserM r -> forall x. (r -> Parser x) -> Parser x
-- | A shell complete function.
newtype Completer
Completer :: (String -> IO [String]) -> Completer
[runCompleter] :: Completer -> String -> IO [String]
-- | Smart constructor for a Completer
mkCompleter :: (String -> IO [String]) -> Completer
newtype CompletionResult
CompletionResult :: (String -> IO String) -> CompletionResult
[execCompletion] :: CompletionResult -> String -> IO String
newtype ParserFailure h
ParserFailure :: (String -> (h, ExitCode, Int)) -> ParserFailure h
[execFailure] :: ParserFailure h -> String -> (h, ExitCode, Int)
-- | Result of execParserPure.
data ParserResult a
Success :: a -> ParserResult a
Failure :: ParserFailure ParserHelp -> ParserResult a
CompletionInvoked :: CompletionResult -> ParserResult a
overFailure :: (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a
type Args = [String]
-- | Policy for how to handle options within the parse
data ArgPolicy
-- | The default policy, options and arguments can be interspersed. A `--`
-- option can be passed to ensure all following commands are treated as
-- arguments.
Intersperse :: ArgPolicy
-- | Options must all come before arguments, once a single positional
-- argument or subcommand is parsed, all remaining arguments are treated
-- as positionals. A `--` option can be passed if the first positional
-- one needs starts with -.
NoIntersperse :: ArgPolicy
-- | No options are parsed at all, all arguments are treated as
-- positionals. Is the policy used after `--` is encountered.
AllPositionals :: ArgPolicy
-- | Options and arguments can be interspersed, but if a given option is
-- not found, it is treated as a positional argument. This is sometimes
-- useful if one is passing through most options to another tool, but are
-- supplying just a few of their own options.
ForwardOptions :: ArgPolicy
newtype ArgumentReachability
ArgumentReachability :: Bool -> ArgumentReachability
-- | If the result is a positional, if it can't be accessed in the current
-- parser position ( first arg )
[argumentIsUnreachable] :: ArgumentReachability -> Bool
-- | This type encapsulates whether an AltNode of an OptTree
-- should be displayed with brackets around it.
data AltNodeType
MarkDefault :: AltNodeType
NoDefault :: AltNodeType
data OptTree a
Leaf :: a -> OptTree a
MultNode :: [OptTree a] -> OptTree a
AltNode :: AltNodeType -> [OptTree a] -> OptTree a
BindNode :: OptTree a -> OptTree a
data ParserHelp
ParserHelp :: Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> ParserHelp
[helpError] :: ParserHelp -> Chunk Doc
[helpSuggestions] :: ParserHelp -> Chunk Doc
[helpHeader] :: ParserHelp -> Chunk Doc
[helpUsage] :: ParserHelp -> Chunk Doc
[helpDescription] :: ParserHelp -> Chunk Doc
[helpBody] :: ParserHelp -> Chunk Doc
[helpGlobals] :: ParserHelp -> Chunk Doc
[helpFooter] :: ParserHelp -> Chunk Doc
data SomeParser
SomeParser :: Parser a -> SomeParser
-- | Subparser context, containing the name of the subparser and
-- its parser info. Used by parserFailure to display relevant usage
-- information when parsing inside a subparser fails.
data Context
Context :: String -> ParserInfo a -> Context
data IsCmdStart
CmdStart :: IsCmdStart
CmdCont :: IsCmdStart
fromM :: ParserM a -> Parser a
oneM :: Parser a -> ParserM a
manyM :: Parser a -> ParserM [a]
someM :: Parser a -> ParserM [a]
filterOptional :: OptTree a -> OptTree a
optVisibility :: Option a -> OptVisibility
optMetaVar :: Option a -> String
optHelp :: Option a -> Chunk Doc
optShowDefault :: Option a -> Maybe String
optDescMod :: Option a -> Maybe (Doc -> Doc)
instance GHC.Show.Show Options.Applicative.Types.IsCmdStart
instance GHC.Show.Show Options.Applicative.Types.Backtracking
instance GHC.Classes.Eq Options.Applicative.Types.Backtracking
instance GHC.Show.Show Options.Applicative.Types.ParserPrefs
instance GHC.Classes.Eq Options.Applicative.Types.ParserPrefs
instance GHC.Show.Show Options.Applicative.Types.OptName
instance GHC.Classes.Ord Options.Applicative.Types.OptName
instance GHC.Classes.Eq Options.Applicative.Types.OptName
instance GHC.Show.Show Options.Applicative.Types.OptVisibility
instance GHC.Classes.Ord Options.Applicative.Types.OptVisibility
instance GHC.Classes.Eq Options.Applicative.Types.OptVisibility
instance GHC.Show.Show a => GHC.Show.Show (Options.Applicative.Types.ParserResult a)
instance GHC.Show.Show Options.Applicative.Types.ArgPolicy
instance GHC.Classes.Ord Options.Applicative.Types.ArgPolicy
instance GHC.Classes.Eq Options.Applicative.Types.ArgPolicy
instance GHC.Show.Show Options.Applicative.Types.ArgumentReachability
instance GHC.Classes.Eq Options.Applicative.Types.ArgumentReachability
instance GHC.Classes.Eq Options.Applicative.Types.AltNodeType
instance GHC.Show.Show Options.Applicative.Types.AltNodeType
instance GHC.Show.Show a => GHC.Show.Show (Options.Applicative.Types.OptTree a)
instance GHC.Base.Monad Options.Applicative.Types.ParserM
instance GHC.Base.Functor Options.Applicative.Types.ParserM
instance GHC.Base.Applicative Options.Applicative.Types.ParserM
instance GHC.Base.Monoid Options.Applicative.Types.ParseError
instance GHC.Base.Semigroup Options.Applicative.Types.ParseError
instance GHC.Base.Functor Options.Applicative.Types.ParserInfo
instance GHC.Show.Show (Options.Applicative.Types.Option a)
instance GHC.Base.Functor Options.Applicative.Types.Option
instance GHC.Base.Functor Options.Applicative.Types.ReadM
instance GHC.Base.Applicative Options.Applicative.Types.ReadM
instance GHC.Base.Alternative Options.Applicative.Types.ReadM
instance GHC.Base.Monad Options.Applicative.Types.ReadM
instance Control.Monad.Fail.MonadFail Options.Applicative.Types.ReadM
instance GHC.Base.MonadPlus Options.Applicative.Types.ReadM
instance GHC.Base.Functor Options.Applicative.Types.CReader
instance GHC.Base.Functor Options.Applicative.Types.OptReader
instance GHC.Base.Functor Options.Applicative.Types.Parser
instance GHC.Base.Applicative Options.Applicative.Types.Parser
instance GHC.Base.Alternative Options.Applicative.Types.Parser
instance GHC.Base.Functor Options.Applicative.Types.ParserResult
instance GHC.Base.Applicative Options.Applicative.Types.ParserResult
instance GHC.Base.Monad Options.Applicative.Types.ParserResult
instance GHC.Show.Show h => GHC.Show.Show (Options.Applicative.Types.ParserFailure h)
instance GHC.Base.Functor Options.Applicative.Types.ParserFailure
instance GHC.Show.Show Options.Applicative.Types.CompletionResult
instance GHC.Base.Semigroup Options.Applicative.Types.Completer
instance GHC.Base.Monoid Options.Applicative.Types.Completer
instance GHC.Show.Show Options.Applicative.Types.OptProperties
module Options.Applicative.NonEmpty
-- | Sequences an action one or more times.
--
-- Functionally identical to some1, but is preferred as it gives a
-- nicer help text.
some1 :: Parser a -> Parser (NonEmpty a)
module Options.Applicative.Internal
data P a
class (Alternative m, MonadPlus m) => MonadP m
enterContext :: MonadP m => String -> ParserInfo a -> m ()
exitContext :: MonadP m => m ()
getPrefs :: MonadP m => m ParserPrefs
missingArgP :: MonadP m => ParseError -> Completer -> m a
errorP :: MonadP m => ParseError -> m a
exitP :: MonadP m => IsCmdStart -> ArgPolicy -> Parser b -> Maybe a -> m a
data ParseError
ErrorMsg :: String -> ParseError
InfoMsg :: String -> ParseError
ShowHelpText :: Maybe String -> ParseError
UnknownError :: ParseError
MissingError :: IsCmdStart -> SomeParser -> ParseError
ExpectsArgError :: String -> ParseError
UnexpectedError :: String -> SomeParser -> ParseError
uncons :: [a] -> Maybe (a, [a])
hoistMaybe :: MonadPlus m => Maybe a -> m a
hoistEither :: MonadP m => Either ParseError a -> m a
runReadM :: MonadP m => ReadM a -> String -> m a
withReadM :: (String -> String) -> ReadM a -> ReadM a
runP :: P a -> ParserPrefs -> (Either ParseError a, [Context])
data Completion a
runCompletion :: Completion r -> ParserPrefs -> Maybe (Either (SomeParser, ArgPolicy) Completer)
contextNames :: [Context] -> [String]
data ListT m a
takeListT :: Monad m => Int -> ListT m a -> ListT m a
runListT :: Monad m => ListT m a -> m [a]
hoistList :: Alternative m => [a] -> m a
data NondetT m a
cut :: Monad m => NondetT m ()
() :: Monad m => NondetT m a -> NondetT m a -> NondetT m a
disamb :: Monad m => Bool -> NondetT m a -> m (Maybe a)
instance GHC.Base.Monad m => GHC.Base.Functor (Options.Applicative.Internal.NondetT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Options.Applicative.Internal.NondetT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Options.Applicative.Internal.NondetT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Options.Applicative.Internal.NondetT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Options.Applicative.Internal.NondetT m)
instance Control.Monad.Trans.Class.MonadTrans Options.Applicative.Internal.NondetT
instance GHC.Base.Monad m => GHC.Base.Functor (Options.Applicative.Internal.ListT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Options.Applicative.Internal.ListT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Options.Applicative.Internal.ListT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Options.Applicative.Internal.ListT m)
instance Control.Monad.Trans.Class.MonadTrans Options.Applicative.Internal.ListT
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Options.Applicative.Internal.ListT m)
instance GHC.Base.Functor Options.Applicative.Internal.Completion
instance GHC.Base.Applicative Options.Applicative.Internal.Completion
instance GHC.Base.Alternative Options.Applicative.Internal.Completion
instance GHC.Base.Monad Options.Applicative.Internal.Completion
instance GHC.Base.MonadPlus Options.Applicative.Internal.Completion
instance Options.Applicative.Internal.MonadP Options.Applicative.Internal.Completion
instance GHC.Base.Functor Options.Applicative.Internal.ComplResult
instance GHC.Base.Applicative Options.Applicative.Internal.ComplResult
instance GHC.Base.Monad Options.Applicative.Internal.ComplResult
instance GHC.Base.Functor Options.Applicative.Internal.P
instance GHC.Base.Applicative Options.Applicative.Internal.P
instance GHC.Base.Alternative Options.Applicative.Internal.P
instance GHC.Base.Monad Options.Applicative.Internal.P
instance GHC.Base.MonadPlus Options.Applicative.Internal.P
instance Options.Applicative.Internal.MonadP Options.Applicative.Internal.P
module Options.Applicative.Common
-- | A Parser a is an option parser returning a value of type
-- a.
data Parser a
-- | Create a parser composed of a single option.
liftOpt :: Option a -> Parser a
showOption :: OptName -> String
-- | A full description for a runnable Parser for a program.
data ParserInfo a
ParserInfo :: Parser a -> Bool -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Int -> ArgPolicy -> ParserInfo a
-- | the option parser for the program
[infoParser] :: ParserInfo a -> Parser a
-- | whether the help text should contain full documentation
[infoFullDesc] :: ParserInfo a -> Bool
-- | brief parser description
[infoProgDesc] :: ParserInfo a -> Chunk Doc
-- | header of the full parser description
[infoHeader] :: ParserInfo a -> Chunk Doc
-- | footer of the full parser description
[infoFooter] :: ParserInfo a -> Chunk Doc
-- | exit code for a parser failure
[infoFailureCode] :: ParserInfo a -> Int
-- | allow regular options and flags to occur after arguments (default:
-- InterspersePolicy)
[infoPolicy] :: ParserInfo a -> ArgPolicy
-- | Global preferences for a top-level Parser.
data ParserPrefs
ParserPrefs :: String -> Bool -> Bool -> Bool -> Backtracking -> Int -> Bool -> Bool -> Int -> ParserPrefs
-- | metavar suffix for multiple options
[prefMultiSuffix] :: ParserPrefs -> String
-- | automatically disambiguate abbreviations (default: False)
[prefDisambiguate] :: ParserPrefs -> Bool
-- | always show help text on parse errors (default: False)
[prefShowHelpOnError] :: ParserPrefs -> Bool
-- | show the help text for a command or subcommand if it fails with no
-- input (default: False)
[prefShowHelpOnEmpty] :: ParserPrefs -> Bool
-- | backtrack to parent parser when a subcommand fails (default:
-- Backtrack)
[prefBacktrack] :: ParserPrefs -> Backtracking
-- | number of columns in the terminal, used to format the help page
-- (default: 80)
[prefColumns] :: ParserPrefs -> Int
-- | when displaying long names in usage and help, use an '=' sign for long
-- names, rather than a single space (default: False)
[prefHelpLongEquals] :: ParserPrefs -> Bool
-- | when displaying subparsers' usage help, show parent options under a
-- "global options" section (default: False)
[prefHelpShowGlobal] :: ParserPrefs -> Bool
-- | Indentation width for tables
[prefTabulateFill] :: ParserPrefs -> Int
runParserInfo :: MonadP m => ParserInfo a -> Args -> m a
runParserFully :: MonadP m => ArgPolicy -> Parser a -> Args -> m a
runParserStep :: MonadP m => ArgPolicy -> Parser a -> String -> Args -> m (Maybe (Parser a), Args)
-- | Apply a Parser to a command line, and return a result and
-- leftover arguments. This function returns an error if any parsing
-- error occurs, or if any options are missing and don't have a default
-- value.
runParser :: MonadP m => ArgPolicy -> IsCmdStart -> Parser a -> Args -> m (a, Args)
-- | The default value of a Parser. This function returns an error
-- if any of the options don't have a default value.
evalParser :: Parser a -> Maybe a
-- | Map a polymorphic function over all the options of a parser, and
-- collect the results in a list.
mapParser :: (forall x. ArgumentReachability -> Option x -> b) -> Parser a -> [b]
-- | Like mapParser, but collect the results in a tree structure.
treeMapParser :: (forall x. ArgumentReachability -> Option x -> b) -> Parser a -> OptTree b
optionNames :: OptReader a -> [OptName]
module Options.Applicative.Help.Core
-- | Generate descriptions for commands.
cmdDesc :: ParserPrefs -> Parser a -> [(Maybe String, Chunk Doc)]
-- | Generate a brief help text for a parser.
briefDesc :: ParserPrefs -> Parser a -> Chunk Doc
-- | Generate a brief help text for a parser, only including mandatory
-- options and arguments.
missingDesc :: ParserPrefs -> Parser a -> Chunk Doc
-- | Generate a full help text for a parser
fullDesc :: ParserPrefs -> Parser a -> Chunk Doc
-- | Generate a help text for the parser, showing only what is relevant in
-- the "Global options: section"
globalDesc :: ParserPrefs -> Parser a -> Chunk Doc
data ParserHelp
ParserHelp :: Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> ParserHelp
[helpError] :: ParserHelp -> Chunk Doc
[helpSuggestions] :: ParserHelp -> Chunk Doc
[helpHeader] :: ParserHelp -> Chunk Doc
[helpUsage] :: ParserHelp -> Chunk Doc
[helpDescription] :: ParserHelp -> Chunk Doc
[helpBody] :: ParserHelp -> Chunk Doc
[helpGlobals] :: ParserHelp -> Chunk Doc
[helpFooter] :: ParserHelp -> Chunk Doc
errorHelp :: Chunk Doc -> ParserHelp
headerHelp :: Chunk Doc -> ParserHelp
suggestionsHelp :: Chunk Doc -> ParserHelp
usageHelp :: Chunk Doc -> ParserHelp
descriptionHelp :: Chunk Doc -> ParserHelp
bodyHelp :: Chunk Doc -> ParserHelp
footerHelp :: Chunk Doc -> ParserHelp
globalsHelp :: Chunk Doc -> ParserHelp
-- | Generate the help text for a program.
parserHelp :: ParserPrefs -> Parser a -> ParserHelp
-- | Generate option summary.
parserUsage :: ParserPrefs -> Parser a -> String -> Doc
parserGlobals :: ParserPrefs -> Parser a -> ParserHelp
instance GHC.Show.Show Options.Applicative.Help.Core.Parenthetic
instance GHC.Classes.Ord Options.Applicative.Help.Core.Parenthetic
instance GHC.Classes.Eq Options.Applicative.Help.Core.Parenthetic
module Options.Applicative.Help
module Options.Applicative.Builder.Internal
-- | An option modifier.
--
-- Option modifiers are values that represent a modification of the
-- properties of an option.
--
-- The type parameter a is the return type of the option, while
-- f is a record containing its properties (e.g.
-- OptionFields for regular options, FlagFields for flags,
-- etc...).
--
-- An option modifier consists of 3 elements:
--
--
-- - A field modifier, of the form f a -> f a. These are
-- essentially (compositions of) setters for some of the properties
-- supported by f.
-- - An optional default value and function to display it.
-- - A property modifier, of the form OptProperties ->
-- OptProperties. This is just like the field modifier, but for
-- properties applicable to any option.
--
--
-- Modifiers are instances of Monoid, and can be composed as such.
--
-- One rarely needs to deal with modifiers directly, as most of the times
-- it is sufficient to pass them to builders (such as strOption
-- or flag) to create options (see Builder).
data Mod f a
Mod :: (f a -> f a) -> DefaultProp a -> (OptProperties -> OptProperties) -> Mod f a
class HasName f
name :: HasName f => OptName -> f a -> f a
class HasCompleter f
modCompleter :: HasCompleter f => (Completer -> Completer) -> f a -> f a
class HasValue f
hasValueDummy :: HasValue f => f a -> ()
class HasMetavar f
hasMetavarDummy :: HasMetavar f => f a -> ()
data OptionFields a
OptionFields :: [OptName] -> Completer -> (String -> ParseError) -> OptionFields a
[optNames] :: OptionFields a -> [OptName]
[optCompleter] :: OptionFields a -> Completer
[optNoArgError] :: OptionFields a -> String -> ParseError
data FlagFields a
FlagFields :: [OptName] -> a -> FlagFields a
[flagNames] :: FlagFields a -> [OptName]
[flagActive] :: FlagFields a -> a
data CommandFields a
CommandFields :: [(String, ParserInfo a)] -> Maybe String -> CommandFields a
[cmdCommands] :: CommandFields a -> [(String, ParserInfo a)]
[cmdGroup] :: CommandFields a -> Maybe String
data ArgumentFields a
ArgumentFields :: Completer -> ArgumentFields a
[argCompleter] :: ArgumentFields a -> Completer
data DefaultProp a
DefaultProp :: Maybe a -> Maybe (a -> String) -> DefaultProp a
optionMod :: (OptProperties -> OptProperties) -> Mod f a
fieldMod :: (f a -> f a) -> Mod f a
-- | Base default properties.
baseProps :: OptProperties
mkCommand :: Mod CommandFields a -> (Maybe String, [(String, ParserInfo a)])
mkParser :: DefaultProp a -> (OptProperties -> OptProperties) -> OptReader a -> Parser a
mkOption :: DefaultProp a -> (OptProperties -> OptProperties) -> OptReader a -> Option a
mkProps :: DefaultProp a -> (OptProperties -> OptProperties) -> OptProperties
-- | Hide this option completely from the help text
--
-- Use hidden if the option should remain visible in the full
-- description.
internal :: Mod f a
-- | Suppress this option from appearing in global options
noGlobal :: Mod f a
instance GHC.Base.Monoid (Options.Applicative.Builder.Internal.Mod f a)
instance GHC.Base.Semigroup (Options.Applicative.Builder.Internal.Mod f a)
instance GHC.Base.Monoid (Options.Applicative.Builder.Internal.DefaultProp a)
instance GHC.Base.Semigroup (Options.Applicative.Builder.Internal.DefaultProp a)
instance Options.Applicative.Builder.Internal.HasMetavar Options.Applicative.Builder.Internal.OptionFields
instance Options.Applicative.Builder.Internal.HasMetavar Options.Applicative.Builder.Internal.ArgumentFields
instance Options.Applicative.Builder.Internal.HasMetavar Options.Applicative.Builder.Internal.CommandFields
instance Options.Applicative.Builder.Internal.HasValue Options.Applicative.Builder.Internal.OptionFields
instance Options.Applicative.Builder.Internal.HasValue Options.Applicative.Builder.Internal.ArgumentFields
instance Options.Applicative.Builder.Internal.HasCompleter Options.Applicative.Builder.Internal.OptionFields
instance Options.Applicative.Builder.Internal.HasCompleter Options.Applicative.Builder.Internal.ArgumentFields
instance Options.Applicative.Builder.Internal.HasName Options.Applicative.Builder.Internal.OptionFields
instance Options.Applicative.Builder.Internal.HasName Options.Applicative.Builder.Internal.FlagFields
module Options.Applicative.Builder.Completer
-- | A shell complete function.
data Completer
-- | Smart constructor for a Completer
mkCompleter :: (String -> IO [String]) -> Completer
-- | Create a Completer from an IO action
listIOCompleter :: IO [String] -> Completer
-- | Create a Completer from a constant list of strings.
listCompleter :: [String] -> Completer
-- | Run a compgen completion action.
--
-- Common actions include file and directory. See
-- http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins
-- for a complete list.
bashCompleter :: String -> Completer
-- | Strongly quote the string we pass to compgen.
--
-- We need to do this so bash doesn't expand out any ~ or other chars we
-- want to complete on, or emit an end of line error when seeking the
-- close to the quote.
requote :: String -> String
module Options.Applicative.Builder
-- | Builder for a command parser. The command modifier can be used
-- to specify individual commands.
--
-- By default, sub-parsers allow backtracking to their parent's options
-- when they are completed. To allow full mixing of parent and sub-parser
-- options, turn on subparserInline; otherwise, to disable
-- backtracking completely, use noBacktrack.
subparser :: Mod CommandFields a -> Parser a
-- | Builder for a String argument.
strArgument :: IsString s => Mod ArgumentFields s -> Parser s
-- | Builder for an argument parser.
argument :: ReadM a -> Mod ArgumentFields a -> Parser a
-- | Builder for a flag parser.
--
-- A flag that switches from a "default value" to an "active value" when
-- encountered. For a simple boolean value, use switch instead.
--
-- Note: Because this parser will never fail, it can not be used
-- with combinators such as some or many, as these
-- combinators continue until a failure occurs. See flag'.
flag :: a -> a -> Mod FlagFields a -> Parser a
-- | Builder for a flag parser without a default value.
--
-- Same as flag, but with no default value. In particular, this
-- flag will never parse successfully by itself.
--
-- It still makes sense to use it as part of a composite parser. For
-- example
--
--
-- length <$> many (flag' () (short 't'))
--
--
-- is a parser that counts the number of "-t" arguments on the command
-- line, alternatively
--
--
-- flag' True (long "on") <|> flag' False (long "off")
--
--
-- will require the user to enter '--on' or '--off' on the command line.
flag' :: a -> Mod FlagFields a -> Parser a
-- | Builder for a boolean flag.
--
-- Note: Because this parser will never fail, it can not be used
-- with combinators such as some or many, as these
-- combinators continue until a failure occurs. See flag'.
--
--
-- switch = flag False True
--
switch :: Mod FlagFields Bool -> Parser Bool
-- | An option that always fails.
--
-- When this option is encountered, the option parser immediately aborts
-- with the given parse error. If you simply want to output a message,
-- use infoOption instead.
abortOption :: ParseError -> Mod OptionFields (a -> a) -> Parser (a -> a)
-- | An option that always fails and displays a message.
infoOption :: String -> Mod OptionFields (a -> a) -> Parser (a -> a)
-- | Builder for an option taking a String argument.
strOption :: IsString s => Mod OptionFields s -> Parser s
-- | Builder for an option using the given reader.
--
-- This is a regular option, and should always have either a
-- long or short name specified in the modifiers (or
-- both).
--
--
-- nameParser = option str ( long "name" <> short 'n' )
--
option :: ReadM a -> Mod OptionFields a -> Parser a
-- | Specify a short name for an option.
short :: HasName f => Char -> Mod f a
-- | Specify a long name for an option.
long :: HasName f => String -> Mod f a
-- | Specify the help text for an option.
help :: String -> Mod f a
-- | Specify the help text for an option as a Doc value.
helpDoc :: Maybe Doc -> Mod f a
-- | Specify a default value for an option.
--
-- Note: Because this modifier means the parser will never fail,
-- do not use it with combinators such as some or many, as
-- these combinators continue until a failure occurs. Careless use will
-- thus result in a hang.
--
-- To display the default value, combine with showDefault or
-- showDefaultWith.
value :: HasValue f => a -> Mod f a
-- | Specify a function to show the default value for an option.
showDefaultWith :: (a -> String) -> Mod f a
-- | Show the default value for this option using its Show instance.
showDefault :: Show a => Mod f a
-- | Specify a metavariable for the argument.
--
-- Metavariables have no effect on the actual parser, and only serve to
-- specify the symbolic name for an argument to be displayed in the help
-- text.
metavar :: HasMetavar f => String -> Mod f a
-- | Specify the error to display when no argument is provided to this
-- option.
noArgError :: ParseError -> Mod OptionFields a
data ParseError
ErrorMsg :: String -> ParseError
InfoMsg :: String -> ParseError
ShowHelpText :: Maybe String -> ParseError
UnknownError :: ParseError
MissingError :: IsCmdStart -> SomeParser -> ParseError
ExpectsArgError :: String -> ParseError
UnexpectedError :: String -> SomeParser -> ParseError
-- | Hide this option from the brief description.
--
-- Use internal to hide the option from the help text too.
hidden :: Mod f a
-- | Hide this option completely from the help text
--
-- Use hidden if the option should remain visible in the full
-- description.
internal :: Mod f a
-- | Apply a function to the option description in the usage text.
--
--
-- import Options.Applicative.Help
-- flag' () (short 't' <> style bold)
--
--
-- NOTE: This builder is more flexible than its name and example
-- allude. One of the motivating examples for its addition was to use
-- const to completely replace the usage text of an option.
style :: (Doc -> Doc) -> Mod f a
-- | Add a command to a subparser option.
--
-- Suggested usage for multiple commands is to add them to a single
-- subparser. e.g.
--
--
-- sample :: Parser Sample
-- sample = subparser
-- ( command "hello"
-- (info hello (progDesc "Print greeting"))
-- <> command "goodbye"
-- (info goodbye (progDesc "Say goodbye"))
-- )
--
command :: String -> ParserInfo a -> Mod CommandFields a
-- | Add a description to a group of commands.
--
-- Advanced feature for separating logical groups of commands on the
-- parse line.
--
-- If using the same metavar for each group of commands, it may
-- yield a more attractive usage text combined with hidden for
-- some groups.
commandGroup :: String -> Mod CommandFields a
-- | Add a list of possible completion values.
completeWith :: HasCompleter f => [String] -> Mod f a
-- | Add a bash completion action. Common actions include file and
-- directory. See
-- http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins
-- for a complete list.
action :: HasCompleter f => String -> Mod f a
-- | Add a completer to an argument.
--
-- A completer is a function String -> IO String which, given a
-- partial argument, returns all possible completions for that argument.
completer :: HasCompleter f => Completer -> Mod f a
-- | Trivial option modifier.
idm :: Monoid m => m
-- | An associative operation
--
-- NOTE: This method is redundant and has the default
-- implementation mappend = (<>) since
-- base-4.11.0.0. Should it be implemented manually, since
-- mappend is a synonym for (<>), it is expected that
-- the two functions are defined the same way. In a future GHC release
-- mappend will be removed from Monoid.
mappend :: Monoid a => a -> a -> a
-- | Option reader based on the Read type class.
auto :: Read a => ReadM a
-- | String Option reader.
--
-- Polymorphic over the IsString type class since 0.14.
str :: IsString s => ReadM s
-- | Convert a function producing a Maybe into a reader.
maybeReader :: (String -> Maybe a) -> ReadM a
-- | Convert a function producing an Either into a reader.
--
-- As an example, one can create a ReadM from an attoparsec Parser easily
-- with
--
--
-- import qualified Data.Attoparsec.Text as A
-- import qualified Data.Text as T
-- attoparsecReader :: A.Parser a -> ReadM a
-- attoparsecReader p = eitherReader (A.parseOnly p . T.pack)
--
eitherReader :: (String -> Either String a) -> ReadM a
-- | Null Option reader. All arguments will fail validation.
disabled :: ReadM a
-- | Abort option reader by exiting with a ParseError.
readerAbort :: ParseError -> ReadM a
-- | Abort option reader by exiting with an error message.
readerError :: String -> ReadM a
-- | Modifier for ParserInfo.
data InfoMod a
-- | Show a full description in the help text of this parser (default).
fullDesc :: InfoMod a
-- | Only show a brief description in the help text of this parser.
briefDesc :: InfoMod a
-- | Specify a header for this parser.
header :: String -> InfoMod a
-- | Specify a header for this parser as a Doc value.
headerDoc :: Maybe Doc -> InfoMod a
-- | Specify a footer for this parser.
footer :: String -> InfoMod a
-- | Specify a footer for this parser as a Doc value.
footerDoc :: Maybe Doc -> InfoMod a
-- | Specify a short program description.
progDesc :: String -> InfoMod a
-- | Specify a short program description as a Doc value.
progDescDoc :: Maybe Doc -> InfoMod a
-- | Specify an exit code if a parse error occurs.
failureCode :: Int -> InfoMod a
-- | Disable parsing of regular options after arguments. After a positional
-- argument is parsed, all remaining options and arguments will be
-- treated as a positional arguments. Not recommended in general as users
-- often expect to be able to freely intersperse regular options and
-- flags within command line options.
noIntersperse :: InfoMod a
-- | Intersperse matched options and arguments normally, but allow
-- unmatched options to be treated as positional arguments. This is
-- sometimes useful if one is wrapping a third party cli tool and needs
-- to pass options through, while also providing a handful of their own
-- options. Not recommended in general as typos by the user may not yield
-- a parse error and cause confusion.
forwardOptions :: InfoMod a
-- | Disable parsing of regular options completely. All options and
-- arguments will be treated as a positional arguments. Obviously not
-- recommended in general as options will be unreachable. This is the
-- same behaviour one sees after the "--" pseudo-argument.
allPositional :: InfoMod a
-- | Create a ParserInfo given a Parser and a modifier.
info :: Parser a -> InfoMod a -> ParserInfo a
data PrefsMod
-- | Include a suffix to attach to the metavar when multiple values can be
-- entered.
multiSuffix :: String -> PrefsMod
-- | Turn on disambiguation.
--
-- See
-- https://github.com/pcapriotti/optparse-applicative#disambiguation
disambiguate :: PrefsMod
-- | Show full help text on any error.
showHelpOnError :: PrefsMod
-- | Show the help text if the user enters only the program name or
-- subcommand.
--
-- This will suppress a "Missing:" error and show the full usage instead
-- if a user just types the name of the program.
showHelpOnEmpty :: PrefsMod
-- | Turn off backtracking after subcommand is parsed.
noBacktrack :: PrefsMod
-- | Allow full mixing of subcommand and parent arguments by inlining
-- selected subparsers into the parent parser.
--
-- NOTE: When this option is used, preferences for the subparser
-- which effect the parser behaviour (such as noIntersperse) are ignored.
subparserInline :: PrefsMod
-- | Set the maximum width of the generated help text.
columns :: Int -> PrefsMod
-- | Show equals sign, rather than space, in usage and help text for
-- options with long names.
helpLongEquals :: PrefsMod
-- | Show global help information in subparser usage.
helpShowGlobals :: PrefsMod
-- | Set fill width in help text presentation.
helpIndent :: Int -> PrefsMod
-- | Create a ParserPrefs given a modifier
prefs :: PrefsMod -> ParserPrefs
-- | Default preferences.
defaultPrefs :: ParserPrefs
-- | An option modifier.
--
-- Option modifiers are values that represent a modification of the
-- properties of an option.
--
-- The type parameter a is the return type of the option, while
-- f is a record containing its properties (e.g.
-- OptionFields for regular options, FlagFields for flags,
-- etc...).
--
-- An option modifier consists of 3 elements:
--
--
-- - A field modifier, of the form f a -> f a. These are
-- essentially (compositions of) setters for some of the properties
-- supported by f.
-- - An optional default value and function to display it.
-- - A property modifier, of the form OptProperties ->
-- OptProperties. This is just like the field modifier, but for
-- properties applicable to any option.
--
--
-- Modifiers are instances of Monoid, and can be composed as such.
--
-- One rarely needs to deal with modifiers directly, as most of the times
-- it is sufficient to pass them to builders (such as strOption
-- or flag) to create options (see Builder).
data Mod f a
-- | A newtype over 'ReaderT String Except', used by option readers.
data ReadM a
data OptionFields a
data FlagFields a
data ArgumentFields a
data CommandFields a
class HasName f
class HasCompleter f
class HasValue f
class HasMetavar f
instance GHC.Base.Monoid Options.Applicative.Builder.PrefsMod
instance GHC.Base.Semigroup Options.Applicative.Builder.PrefsMod
instance GHC.Base.Monoid (Options.Applicative.Builder.InfoMod a)
instance GHC.Base.Semigroup (Options.Applicative.Builder.InfoMod a)
-- | You don't need to import this module to enable bash completion.
--
-- See the wiki for more information on bash completion.
module Options.Applicative.BashCompletion
bashCompletionParser :: ParserInfo a -> ParserPrefs -> Parser CompletionResult
-- | Generated bash shell completion script
bashCompletionScript :: String -> String -> String
-- | Generated fish shell completion script
fishCompletionScript :: String -> String -> String
-- | Generated zsh shell completion script
zshCompletionScript :: String -> String -> String
instance GHC.Show.Show Options.Applicative.BashCompletion.Richness
instance GHC.Classes.Ord Options.Applicative.BashCompletion.Richness
instance GHC.Classes.Eq Options.Applicative.BashCompletion.Richness
module Options.Applicative.Extra
-- | A hidden "helper" option which always fails.
--
-- A common usage pattern is to apply this applicatively when creating a
-- ParserInfo
--
--
-- opts :: ParserInfo Sample
-- opts = info (sample <**> helper) mempty
--
helper :: Parser (a -> a)
-- | Like helper, but with a minimal set of modifiers that can be extended
-- as desired.
--
--
-- opts :: ParserInfo Sample
-- opts = info (sample <**> helperWith (mconcat [
-- long "help",
-- short 'h',
-- help "Show this help text",
-- hidden
-- ])) mempty
--
helperWith :: Mod OptionFields (a -> a) -> Parser (a -> a)
-- | Builder for a command parser with a "helper" option attached. Used in
-- the same way as subparser, but includes a "--help|-h" inside
-- the subcommand.
hsubparser :: Mod CommandFields a -> Parser a
-- | A hidden "--version" option that displays the version.
--
--
-- opts :: ParserInfo Sample
-- opts = info (sample <**> simpleVersioner "v1.2.3") mempty
--
simpleVersioner :: String -> Parser (a -> a)
-- | Run a program description.
--
-- Parse command line arguments. Display help text and exit if any parse
-- error occurs.
execParser :: ParserInfo a -> IO a
-- | Run a program description with custom preferences.
customExecParser :: ParserPrefs -> ParserInfo a -> IO a
-- | The most general way to run a program description in pure code.
execParserPure :: ParserPrefs -> ParserInfo a -> [String] -> ParserResult a
-- | Extract the actual result from a ParserResult value.
--
-- This function returns Nothing in case of errors. Possible error
-- messages or completion actions are simply discarded.
--
-- If you want to display error messages and invoke completion actions
-- appropriately, use handleParseResult instead.
getParseResult :: ParserResult a -> Maybe a
-- | Handle ParserResult.
handleParseResult :: ParserResult a -> IO a
-- | Generate a ParserFailure from a ParseError in a given
-- Context.
--
-- This function can be used, for example, to show the help text for a
-- parser:
--
--
-- handleParseResult . Failure $ parserFailure pprefs pinfo (ShowHelpText Nothing) mempty
--
parserFailure :: ParserPrefs -> ParserInfo a -> ParseError -> [Context] -> ParserFailure ParserHelp
renderFailure :: ParserFailure ParserHelp -> String -> (String, ExitCode)
newtype ParserFailure h
ParserFailure :: (String -> (h, ExitCode, Int)) -> ParserFailure h
[execFailure] :: ParserFailure h -> String -> (h, ExitCode, Int)
overFailure :: (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a
-- | Result of execParserPure.
data ParserResult a
Success :: a -> ParserResult a
Failure :: ParserFailure ParserHelp -> ParserResult a
CompletionInvoked :: CompletionResult -> ParserResult a
-- | Global preferences for a top-level Parser.
data ParserPrefs
ParserPrefs :: String -> Bool -> Bool -> Bool -> Backtracking -> Int -> Bool -> Bool -> Int -> ParserPrefs
-- | metavar suffix for multiple options
[prefMultiSuffix] :: ParserPrefs -> String
-- | automatically disambiguate abbreviations (default: False)
[prefDisambiguate] :: ParserPrefs -> Bool
-- | always show help text on parse errors (default: False)
[prefShowHelpOnError] :: ParserPrefs -> Bool
-- | show the help text for a command or subcommand if it fails with no
-- input (default: False)
[prefShowHelpOnEmpty] :: ParserPrefs -> Bool
-- | backtrack to parent parser when a subcommand fails (default:
-- Backtrack)
[prefBacktrack] :: ParserPrefs -> Backtracking
-- | number of columns in the terminal, used to format the help page
-- (default: 80)
[prefColumns] :: ParserPrefs -> Int
-- | when displaying long names in usage and help, use an '=' sign for long
-- names, rather than a single space (default: False)
[prefHelpLongEquals] :: ParserPrefs -> Bool
-- | when displaying subparsers' usage help, show parent options under a
-- "global options" section (default: False)
[prefHelpShowGlobal] :: ParserPrefs -> Bool
-- | Indentation width for tables
[prefTabulateFill] :: ParserPrefs -> Int
newtype CompletionResult
CompletionResult :: (String -> IO String) -> CompletionResult
[execCompletion] :: CompletionResult -> String -> IO String
module Options.Applicative
-- | A Parser a is an option parser returning a value of type
-- a.
data Parser a
-- | Builder for a flag parser.
--
-- A flag that switches from a "default value" to an "active value" when
-- encountered. For a simple boolean value, use switch instead.
--
-- Note: Because this parser will never fail, it can not be used
-- with combinators such as some or many, as these
-- combinators continue until a failure occurs. See flag'.
flag :: a -> a -> Mod FlagFields a -> Parser a
-- | Builder for a flag parser without a default value.
--
-- Same as flag, but with no default value. In particular, this
-- flag will never parse successfully by itself.
--
-- It still makes sense to use it as part of a composite parser. For
-- example
--
--
-- length <$> many (flag' () (short 't'))
--
--
-- is a parser that counts the number of "-t" arguments on the command
-- line, alternatively
--
--
-- flag' True (long "on") <|> flag' False (long "off")
--
--
-- will require the user to enter '--on' or '--off' on the command line.
flag' :: a -> Mod FlagFields a -> Parser a
-- | Builder for a boolean flag.
--
-- Note: Because this parser will never fail, it can not be used
-- with combinators such as some or many, as these
-- combinators continue until a failure occurs. See flag'.
--
--
-- switch = flag False True
--
switch :: Mod FlagFields Bool -> Parser Bool
-- | Builder for an option taking a String argument.
strOption :: IsString s => Mod OptionFields s -> Parser s
-- | Builder for an option using the given reader.
--
-- This is a regular option, and should always have either a
-- long or short name specified in the modifiers (or
-- both).
--
--
-- nameParser = option str ( long "name" <> short 'n' )
--
option :: ReadM a -> Mod OptionFields a -> Parser a
-- | Builder for a String argument.
strArgument :: IsString s => Mod ArgumentFields s -> Parser s
-- | Builder for an argument parser.
argument :: ReadM a -> Mod ArgumentFields a -> Parser a
-- | Builder for a command parser. The command modifier can be used
-- to specify individual commands.
--
-- By default, sub-parsers allow backtracking to their parent's options
-- when they are completed. To allow full mixing of parent and sub-parser
-- options, turn on subparserInline; otherwise, to disable
-- backtracking completely, use noBacktrack.
subparser :: Mod CommandFields a -> Parser a
-- | Builder for a command parser with a "helper" option attached. Used in
-- the same way as subparser, but includes a "--help|-h" inside
-- the subcommand.
hsubparser :: Mod CommandFields a -> Parser a
-- | An option that always fails.
--
-- When this option is encountered, the option parser immediately aborts
-- with the given parse error. If you simply want to output a message,
-- use infoOption instead.
abortOption :: ParseError -> Mod OptionFields (a -> a) -> Parser (a -> a)
-- | An option that always fails and displays a message.
infoOption :: String -> Mod OptionFields (a -> a) -> Parser (a -> a)
-- | A hidden "helper" option which always fails.
--
-- A common usage pattern is to apply this applicatively when creating a
-- ParserInfo
--
--
-- opts :: ParserInfo Sample
-- opts = info (sample <**> helper) mempty
--
helper :: Parser (a -> a)
-- | A hidden "--version" option that displays the version.
--
--
-- opts :: ParserInfo Sample
-- opts = info (sample <**> simpleVersioner "v1.2.3") mempty
--
simpleVersioner :: String -> Parser (a -> a)
-- | An option modifier.
--
-- Option modifiers are values that represent a modification of the
-- properties of an option.
--
-- The type parameter a is the return type of the option, while
-- f is a record containing its properties (e.g.
-- OptionFields for regular options, FlagFields for flags,
-- etc...).
--
-- An option modifier consists of 3 elements:
--
--
-- - A field modifier, of the form f a -> f a. These are
-- essentially (compositions of) setters for some of the properties
-- supported by f.
-- - An optional default value and function to display it.
-- - A property modifier, of the form OptProperties ->
-- OptProperties. This is just like the field modifier, but for
-- properties applicable to any option.
--
--
-- Modifiers are instances of Monoid, and can be composed as such.
--
-- One rarely needs to deal with modifiers directly, as most of the times
-- it is sufficient to pass them to builders (such as strOption
-- or flag) to create options (see Builder).
data Mod f a
-- | Specify a short name for an option.
short :: HasName f => Char -> Mod f a
-- | Specify a long name for an option.
long :: HasName f => String -> Mod f a
-- | Specify the help text for an option.
help :: String -> Mod f a
-- | Specify the help text for an option as a Doc value.
helpDoc :: Maybe Doc -> Mod f a
-- | Specify a default value for an option.
--
-- Note: Because this modifier means the parser will never fail,
-- do not use it with combinators such as some or many, as
-- these combinators continue until a failure occurs. Careless use will
-- thus result in a hang.
--
-- To display the default value, combine with showDefault or
-- showDefaultWith.
value :: HasValue f => a -> Mod f a
-- | Specify a function to show the default value for an option.
showDefaultWith :: (a -> String) -> Mod f a
-- | Show the default value for this option using its Show instance.
showDefault :: Show a => Mod f a
-- | Specify a metavariable for the argument.
--
-- Metavariables have no effect on the actual parser, and only serve to
-- specify the symbolic name for an argument to be displayed in the help
-- text.
metavar :: HasMetavar f => String -> Mod f a
-- | Specify the error to display when no argument is provided to this
-- option.
noArgError :: ParseError -> Mod OptionFields a
-- | Hide this option from the brief description.
--
-- Use internal to hide the option from the help text too.
hidden :: Mod f a
-- | Hide this option completely from the help text
--
-- Use hidden if the option should remain visible in the full
-- description.
internal :: Mod f a
-- | Apply a function to the option description in the usage text.
--
--
-- import Options.Applicative.Help
-- flag' () (short 't' <> style bold)
--
--
-- NOTE: This builder is more flexible than its name and example
-- allude. One of the motivating examples for its addition was to use
-- const to completely replace the usage text of an option.
style :: (Doc -> Doc) -> Mod f a
-- | Add a command to a subparser option.
--
-- Suggested usage for multiple commands is to add them to a single
-- subparser. e.g.
--
--
-- sample :: Parser Sample
-- sample = subparser
-- ( command "hello"
-- (info hello (progDesc "Print greeting"))
-- <> command "goodbye"
-- (info goodbye (progDesc "Say goodbye"))
-- )
--
command :: String -> ParserInfo a -> Mod CommandFields a
-- | Add a description to a group of commands.
--
-- Advanced feature for separating logical groups of commands on the
-- parse line.
--
-- If using the same metavar for each group of commands, it may
-- yield a more attractive usage text combined with hidden for
-- some groups.
commandGroup :: String -> Mod CommandFields a
-- | Add a list of possible completion values.
completeWith :: HasCompleter f => [String] -> Mod f a
-- | Add a bash completion action. Common actions include file and
-- directory. See
-- http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins
-- for a complete list.
action :: HasCompleter f => String -> Mod f a
-- | Add a completer to an argument.
--
-- A completer is a function String -> IO String which, given a
-- partial argument, returns all possible completions for that argument.
completer :: HasCompleter f => Completer -> Mod f a
-- | Trivial option modifier.
idm :: Monoid m => m
-- | An associative operation
--
-- NOTE: This method is redundant and has the default
-- implementation mappend = (<>) since
-- base-4.11.0.0. Should it be implemented manually, since
-- mappend is a synonym for (<>), it is expected that
-- the two functions are defined the same way. In a future GHC release
-- mappend will be removed from Monoid.
mappend :: Monoid a => a -> a -> a
data OptionFields a
data FlagFields a
data ArgumentFields a
data CommandFields a
class HasName f
class HasCompleter f
class HasValue f
class HasMetavar f
-- | A newtype over 'ReaderT String Except', used by option readers.
data ReadM a
-- | Option reader based on the Read type class.
auto :: Read a => ReadM a
-- | String Option reader.
--
-- Polymorphic over the IsString type class since 0.14.
str :: IsString s => ReadM s
-- | Convert a function producing a Maybe into a reader.
maybeReader :: (String -> Maybe a) -> ReadM a
-- | Convert a function producing an Either into a reader.
--
-- As an example, one can create a ReadM from an attoparsec Parser easily
-- with
--
--
-- import qualified Data.Attoparsec.Text as A
-- import qualified Data.Text as T
-- attoparsecReader :: A.Parser a -> ReadM a
-- attoparsecReader p = eitherReader (A.parseOnly p . T.pack)
--
eitherReader :: (String -> Either String a) -> ReadM a
-- | Null Option reader. All arguments will fail validation.
disabled :: ReadM a
-- | Abort option reader by exiting with a ParseError.
readerAbort :: ParseError -> ReadM a
-- | Abort option reader by exiting with an error message.
readerError :: String -> ReadM a
-- | Create a ParserInfo given a Parser and a modifier.
info :: Parser a -> InfoMod a -> ParserInfo a
-- | A full description for a runnable Parser for a program.
data ParserInfo a
ParserInfo :: Parser a -> Bool -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Int -> ArgPolicy -> ParserInfo a
-- | the option parser for the program
[infoParser] :: ParserInfo a -> Parser a
-- | whether the help text should contain full documentation
[infoFullDesc] :: ParserInfo a -> Bool
-- | brief parser description
[infoProgDesc] :: ParserInfo a -> Chunk Doc
-- | header of the full parser description
[infoHeader] :: ParserInfo a -> Chunk Doc
-- | footer of the full parser description
[infoFooter] :: ParserInfo a -> Chunk Doc
-- | exit code for a parser failure
[infoFailureCode] :: ParserInfo a -> Int
-- | allow regular options and flags to occur after arguments (default:
-- InterspersePolicy)
[infoPolicy] :: ParserInfo a -> ArgPolicy
-- | Modifier for ParserInfo.
data InfoMod a
-- | Show a full description in the help text of this parser (default).
fullDesc :: InfoMod a
-- | Only show a brief description in the help text of this parser.
briefDesc :: InfoMod a
-- | Specify a header for this parser.
header :: String -> InfoMod a
-- | Specify a header for this parser as a Doc value.
headerDoc :: Maybe Doc -> InfoMod a
-- | Specify a footer for this parser.
footer :: String -> InfoMod a
-- | Specify a footer for this parser as a Doc value.
footerDoc :: Maybe Doc -> InfoMod a
-- | Specify a short program description.
progDesc :: String -> InfoMod a
-- | Specify a short program description as a Doc value.
progDescDoc :: Maybe Doc -> InfoMod a
-- | Specify an exit code if a parse error occurs.
failureCode :: Int -> InfoMod a
-- | Disable parsing of regular options after arguments. After a positional
-- argument is parsed, all remaining options and arguments will be
-- treated as a positional arguments. Not recommended in general as users
-- often expect to be able to freely intersperse regular options and
-- flags within command line options.
noIntersperse :: InfoMod a
-- | Intersperse matched options and arguments normally, but allow
-- unmatched options to be treated as positional arguments. This is
-- sometimes useful if one is wrapping a third party cli tool and needs
-- to pass options through, while also providing a handful of their own
-- options. Not recommended in general as typos by the user may not yield
-- a parse error and cause confusion.
forwardOptions :: InfoMod a
-- | Run a program description.
--
-- Parse command line arguments. Display help text and exit if any parse
-- error occurs.
execParser :: ParserInfo a -> IO a
-- | Run a program description with custom preferences.
customExecParser :: ParserPrefs -> ParserInfo a -> IO a
-- | The most general way to run a program description in pure code.
execParserPure :: ParserPrefs -> ParserInfo a -> [String] -> ParserResult a
-- | Extract the actual result from a ParserResult value.
--
-- This function returns Nothing in case of errors. Possible error
-- messages or completion actions are simply discarded.
--
-- If you want to display error messages and invoke completion actions
-- appropriately, use handleParseResult instead.
getParseResult :: ParserResult a -> Maybe a
-- | Handle ParserResult.
handleParseResult :: ParserResult a -> IO a
-- | Generate a ParserFailure from a ParseError in a given
-- Context.
--
-- This function can be used, for example, to show the help text for a
-- parser:
--
--
-- handleParseResult . Failure $ parserFailure pprefs pinfo (ShowHelpText Nothing) mempty
--
parserFailure :: ParserPrefs -> ParserInfo a -> ParseError -> [Context] -> ParserFailure ParserHelp
renderFailure :: ParserFailure ParserHelp -> String -> (String, ExitCode)
overFailure :: (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a
-- | Create a ParserPrefs given a modifier
prefs :: PrefsMod -> ParserPrefs
-- | Global preferences for a top-level Parser.
data ParserPrefs
ParserPrefs :: String -> Bool -> Bool -> Bool -> Backtracking -> Int -> Bool -> Bool -> Int -> ParserPrefs
-- | metavar suffix for multiple options
[prefMultiSuffix] :: ParserPrefs -> String
-- | automatically disambiguate abbreviations (default: False)
[prefDisambiguate] :: ParserPrefs -> Bool
-- | always show help text on parse errors (default: False)
[prefShowHelpOnError] :: ParserPrefs -> Bool
-- | show the help text for a command or subcommand if it fails with no
-- input (default: False)
[prefShowHelpOnEmpty] :: ParserPrefs -> Bool
-- | backtrack to parent parser when a subcommand fails (default:
-- Backtrack)
[prefBacktrack] :: ParserPrefs -> Backtracking
-- | number of columns in the terminal, used to format the help page
-- (default: 80)
[prefColumns] :: ParserPrefs -> Int
-- | when displaying long names in usage and help, use an '=' sign for long
-- names, rather than a single space (default: False)
[prefHelpLongEquals] :: ParserPrefs -> Bool
-- | when displaying subparsers' usage help, show parent options under a
-- "global options" section (default: False)
[prefHelpShowGlobal] :: ParserPrefs -> Bool
-- | Indentation width for tables
[prefTabulateFill] :: ParserPrefs -> Int
data PrefsMod
-- | Include a suffix to attach to the metavar when multiple values can be
-- entered.
multiSuffix :: String -> PrefsMod
-- | Turn on disambiguation.
--
-- See
-- https://github.com/pcapriotti/optparse-applicative#disambiguation
disambiguate :: PrefsMod
-- | Show full help text on any error.
showHelpOnError :: PrefsMod
-- | Show the help text if the user enters only the program name or
-- subcommand.
--
-- This will suppress a "Missing:" error and show the full usage instead
-- if a user just types the name of the program.
showHelpOnEmpty :: PrefsMod
-- | Turn off backtracking after subcommand is parsed.
noBacktrack :: PrefsMod
-- | Allow full mixing of subcommand and parent arguments by inlining
-- selected subparsers into the parent parser.
--
-- NOTE: When this option is used, preferences for the subparser
-- which effect the parser behaviour (such as noIntersperse) are ignored.
subparserInline :: PrefsMod
-- | Set the maximum width of the generated help text.
columns :: Int -> PrefsMod
-- | Show equals sign, rather than space, in usage and help text for
-- options with long names.
helpLongEquals :: PrefsMod
-- | Show global help information in subparser usage.
helpShowGlobals :: PrefsMod
-- | Set fill width in help text presentation.
helpIndent :: Int -> PrefsMod
-- | Default preferences.
defaultPrefs :: ParserPrefs
-- | A shell complete function.
data Completer
-- | Smart constructor for a Completer
mkCompleter :: (String -> IO [String]) -> Completer
-- | Create a Completer from an IO action
listIOCompleter :: IO [String] -> Completer
-- | Create a Completer from a constant list of strings.
listCompleter :: [String] -> Completer
-- | Run a compgen completion action.
--
-- Common actions include file and directory. See
-- http://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins
-- for a complete list.
bashCompleter :: String -> Completer
data ParseError
ErrorMsg :: String -> ParseError
InfoMsg :: String -> ParseError
ShowHelpText :: Maybe String -> ParseError
UnknownError :: ParseError
MissingError :: IsCmdStart -> SomeParser -> ParseError
ExpectsArgError :: String -> ParseError
UnexpectedError :: String -> SomeParser -> ParseError
data ParserHelp
ParserHelp :: Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> Chunk Doc -> ParserHelp
[helpError] :: ParserHelp -> Chunk Doc
[helpSuggestions] :: ParserHelp -> Chunk Doc
[helpHeader] :: ParserHelp -> Chunk Doc
[helpUsage] :: ParserHelp -> Chunk Doc
[helpDescription] :: ParserHelp -> Chunk Doc
[helpBody] :: ParserHelp -> Chunk Doc
[helpGlobals] :: ParserHelp -> Chunk Doc
[helpFooter] :: ParserHelp -> Chunk Doc
newtype ParserFailure h
ParserFailure :: (String -> (h, ExitCode, Int)) -> ParserFailure h
[execFailure] :: ParserFailure h -> String -> (h, ExitCode, Int)
-- | Result of execParserPure.
data ParserResult a
Success :: a -> ParserResult a
Failure :: ParserFailure ParserHelp -> ParserResult a
CompletionInvoked :: CompletionResult -> ParserResult a
newtype CompletionResult
CompletionResult :: (String -> IO String) -> CompletionResult
[execCompletion] :: CompletionResult -> String -> IO String
-- | This module contains an arrow interface for option parsers, which
-- allows to define and combine parsers using the arrow notation and
-- arrow combinators.
--
-- The arrow syntax is particularly useful to create parsers of nested
-- structures, or records where the order of fields is different from the
-- order in which the parsers should be applied.
--
-- For example, an arguments parser often needs to be applied
-- last, and that makes it inconvenient to use it for a field which is
-- not the last one in a record.
--
-- Using the arrow syntax and the functions in this module, one can
-- write, e.g.:
--
--
-- data Options = Options
-- { optArgs :: [String]
-- , optVerbose :: Bool }
--
-- opts :: Parser Options
-- opts = runA $ proc () -> do
-- verbose <- asA (switch (short 'v')) -< ()
-- args <- asA (arguments str idm) -< ()
-- returnA -< Options args verbose
--
--
-- Parser arrows, created out of regular Parser values using the
-- asA function, are arrows taking () as argument and
-- returning the parsed value.
module Options.Applicative.Arrows
-- | For any Applicative functor f, A f is the
-- Arrow instance associated to f.
--
-- The A constructor can be used to convert a value of type f
-- (a -> b) into an arrow.
newtype A f a b
A :: f (a -> b) -> A f a b
[unA] :: A f a b -> f (a -> b)
-- | Convert a value of type f a into an arrow taking ()
-- as argument.
--
-- Applied to a value of type Parser, it turns it into an arrow
-- that can be used inside an arrow command, or passed to arrow
-- combinators.
asA :: Applicative f => f a -> A f () a
-- | Convert an arrow back to an applicative value.
--
-- This function can be used to return a result of type Parser
-- from an arrow command.
runA :: Applicative f => A f () a -> f a
-- | The type of arrows associated to the applicative Parser
-- functor.
type ParserA = A Parser
instance GHC.Base.Applicative f => Control.Category.Category (Options.Applicative.Arrows.A f)
instance GHC.Base.Applicative f => Control.Arrow.Arrow (Options.Applicative.Arrows.A f)