-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Declarative command-line option parsing and documentation library.
--   
--   CmdTheLine aims to remove tedium from the definition of command-line
--   programs, producing usage and help with little effort.
--   
--   The inspiration was found in Daniel Bunzli's
--   <a>http://erratique.ch/software/cmdliner</a> library.
--   
--   CmdTheLine uses applicative functors to provide a declarative,
--   compositional mechanism for defining command-line programs by lifting
--   regular Haskell functions over argument parsers.
--   
--   A tutorial can be found at
--   <a>http://elifrey.com/2012/07/23/CmdTheLine-Tutorial/</a>.
--   
--   Suggestions, comments, and bug reports are appreciated. Please see the
--   bug and issue tracker at <a>http://github.com/eli-frey/cmdtheline</a>.
--   
--   Changes since 0.1:
--   
--   <ul>
--   <li>More type safety: Types in CmdTheLine.Arg have been made more
--   explicit to disalow unwanted behavior. Positional argument information
--   and optional argument information are distinguished from each other.
--   As well <a>Arg</a>s must be transformed into <a>Term</a> before use,
--   as some operations make since to perform on <a>Arg</a> but not on
--   <a>Term</a>.</li>
--   <li>ArgVal has only one method: <a>parser</a> and <a>pp</a> have been
--   fused into a tuple, so that instantiation of <a>ArgVal</a> can be
--   simplified for all parties.</li>
--   <li>Err is an instance of MonadIO: The <a>Err</a> monad now supports
--   IO action.</li>
--   <li>File and Directory path validation: Taking advantage of new
--   <a>Err</a> capabilities, the library provides new functions for
--   validating <a>String</a>s inside of <a>Term</a>s as being
--   valid/existent file/directory paths.</li>
--   </ul>
--   
--   Changes since 0.2.0:
--   
--   <ul>
--   <li>Test friendly <a>unwrap</a> functions: To allow the testing of
--   terms, there are now two new functions exported with
--   System.Console.CmdTheLine.Term, <a>unwrap</a> and <a>unwrapChoice</a>.
--   As well a datatype representing cause of early exit, <a>EvalExit</a>
--   is exported.</li>
--   </ul>
--   
--   Changes since 0.2.1
--   
--   <ul>
--   <li>Added adapter for interfacing with Getopt in module
--   <a>System.Console.CmdTheLine</a>.</li>
--   </ul>
@package cmdtheline
@version 0.2.3

module System.Console.CmdTheLine.Util

-- | <a>fileExists</a> <tt>term</tt> checks that <a>String</a> in
--   <tt>term</tt> is a path to an existing <i>file</i>. If it is not, exit
--   with an explanatory message for the user.
fileExists :: Term String -> Term String

-- | <a>dirExists</a> <tt>term</tt> checks that <a>String</a> in
--   <tt>term</tt> is a path to an existing <i>directory</i>. If it is not,
--   exit with an explanatory message for the user.
dirExists :: Term String -> Term String

-- | <a>pathExists</a> <tt>term</tt> checks that <a>String</a> in
--   <tt>term</tt> is a path to an existing <i>file or directory</i>. If it
--   is not, exit with an explanatory message for the user.
pathExists :: Term String -> Term String

-- | <a>filesExist</a> <tt>term</tt> is as <a>fileExists</a> but for a
--   <tt>term</tt> containing a list of file paths.
filesExist :: Term [String] -> Term [String]

-- | <a>dirsExist</a> <tt>term</tt> is as <a>dirExists</a> but for a
--   <tt>term</tt> containing a list of directory paths.
dirsExist :: Term [String] -> Term [String]

-- | <a>pathsExist</a> <tt>term</tt> is as <a>pathExists</a> but for a
--   <tt>term</tt> containing a list of paths.
pathsExist :: Term [String] -> Term [String]

-- | <a>validPath</a> <tt>term</tt> checks that <a>String</a> in
--   <tt>term</tt> is a valid path under the current operating system. If
--   it is not, exit with an explanatory message for the user.
validPath :: Term String -> Term String

module System.Console.CmdTheLine.ArgVal

-- | The type of parsers of individual command line argument values.
type ArgParser a = String -> Either Doc a

-- | The type of printers of values retrieved from the command line.
type ArgPrinter a = a -> Doc

-- | A converter is just a pair of a parser and a printer.
type Converter a = (ArgParser a, ArgPrinter a)

-- | The class of values that can be converted from the command line.
class ArgVal a
converter :: ArgVal a => Converter a

-- | The pretty printing part of a <a>converter</a>.
pp :: ArgVal a => ArgPrinter a

-- | The parsing part of a <a>converter</a>.
parser :: ArgVal a => ArgParser a

-- | <a>fromParsec</a> <tt>onErr p</tt> makes an <a>ArgParser</a> from
--   <tt>p</tt> using <tt>onErr</tt> to produce meaningful error messages.
--   On failure, <tt>onErr</tt> will receive a raw string of the value
--   found on the command line.
fromParsec :: (String -> Doc) -> Parsec String () a -> ArgParser a

-- | A converter of enumerated values conveyed as an association list of
--   <tt>( string, value )</tt> pairs. Unambiguous prefixes of
--   <tt>string</tt> map to <tt>value</tt>.
enum :: Eq a => [(String, a)] -> Converter a

-- | A converter of <a>Maybe</a> values of <a>ArgVal</a> instances.
--   
--   Parses as:
--   
--   <pre>
--   fmap Just . parser
--   </pre>
--   
--   Pretty prints as:
--   
--   <pre>
--   maybe empty pp
--   </pre>
just :: ArgVal a => Converter (Maybe a)

-- | <tt><a>list</a> sep</tt> creates a converter of lists of an
--   <a>ArgVal</a> instance separated by <tt>sep</tt>.
list :: ArgVal a => Char -> Converter [a]

-- | <tt><a>pair</a> sep</tt> creates a converter of pairs of <a>ArgVal</a>
--   instances separated by <tt>sep</tt>.
pair :: (ArgVal a, ArgVal b) => Char -> Converter (a, b)

-- | <tt><a>triple</a> sep</tt> creates a converter of triples of
--   <a>ArgVal</a> instances separated by <tt>sep</tt>.
triple :: (ArgVal a, ArgVal b, ArgVal c) => Char -> Converter (a, b, c)

-- | <tt><a>quadruple</a> sep</tt> creates a converter of quadruples of
--   <a>ArgVal</a> instances separated by <tt>sep</tt>.
quadruple :: (ArgVal a, ArgVal b, ArgVal c, ArgVal d) => Char -> Converter (a, b, c, d)

-- | <tt><a>quintuple</a> sep</tt> creates a converter of quintuples of
--   <a>ArgVal</a> instances separated by <tt>sep</tt>.
quintuple :: (ArgVal a, ArgVal b, ArgVal c, ArgVal d, ArgVal e) => Char -> Converter (a, b, c, d, e)
instance ArgVal (Maybe HelpFormat)
instance ArgVal HelpFormat
instance ArgVal (Maybe (Ratio Integer))
instance ArgVal (Ratio Integer)
instance ArgVal (Maybe Double)
instance ArgVal Double
instance ArgVal (Maybe Float)
instance ArgVal Float
instance ArgVal (Maybe Integer)
instance ArgVal Integer
instance ArgVal (Maybe Int)
instance ArgVal Int
instance ArgVal (Maybe [Char])
instance ArgVal [Char]
instance ArgVal (Maybe Bool)
instance ArgVal Bool

module System.Console.CmdTheLine.Arg

-- | The type of command line arguments.
data Arg a

-- | Information about an optional argument. Exposes the folowing fields.
--   
--   <ul>
--   <li><i><tt>optName</tt></i> :: String: defaults to <tt>""</tt>.</li>
--   <li><i><tt>optDoc</tt></i> :: String: defaults to <tt>""</tt>.</li>
--   <li><i><tt>optSec</tt></i> :: String: defaults to
--   <tt>"OPTIONS"</tt>.</li>
--   </ul>
data OptInfo

-- | Information about a positional argument. Exposes the folowing fields.
--   
--   <ul>
--   <li><i><tt>posName</tt></i> :: String: defaults to <tt>""</tt>.</li>
--   <li><i><tt>posDoc</tt></i> :: String: defaults to <tt>""</tt>.</li>
--   <li><i><tt>posSec</tt></i> :: String: defautts to
--   <tt>"ARGUMENTS"</tt>.</li>
--   </ul>
data PosInfo

-- | Initialize an <a>OptInfo</a> by providing a list of names. The fields
--   <tt>optName</tt>, <tt>optDoc</tt>, and <tt>optSec</tt> can then be
--   manipulated post-mortem, as in
--   
--   <pre>
--   inf =(optInfo    [ "i", "insufflation" ])
--       { optName = "INSUFFERABLE"
--       , optDoc  = "in the haunted house's harrow"
--       , optSec  = "NOT FOR AUGHT"
--       }
--   </pre>
--   
--   Names of one character in length will be prefixed by <tt>-</tt> on the
--   command line, while longer names will be prefixed by <tt>--</tt>.
--   
--   It is considered a programming error to provide an empty list of names
--   to optInfo.
optInfo :: [String] -> OptInfo

-- | Initialize a <a>PosInfo</a>. The fields <tt>posName</tt>,
--   <tt>posDoc</tt>, and <tt>posSec</tt> can then be manipulated
--   post-mortem, as in
--   
--   <pre>
--   inf = posInfo
--       { posName = "DEST"
--       , posDoc  = "A destination for the operation."
--       , posSec  = "DESTINATIONS"
--       }
--   </pre>
--   
--   The fields <tt>posName</tt> and <tt>posDoc</tt> must be non-empty
--   strings for the argument to be listed with its documentation under the
--   section <tt>posSec</tt> of generated help.
posInfo :: PosInfo

-- | Create a command line flag that can appear at most once on the command
--   line. Yields <tt>False</tt> in absence and <tt>True</tt> in presence.
flag :: OptInfo -> Arg Bool

-- | As <a>flag</a> but may appear an infinity of times. Yields a list of
--   <tt>True</tt>s as long as the number of times present.
flagAll :: OptInfo -> Arg [Bool]

-- | <a>vFlag</a> <tt>v [ ( v1, ai1 ), ... ]</tt> is an argument that can
--   be present at most once on the command line. It takes on the value
--   <tt>vn</tt> when appearing as <tt>ain</tt>.
vFlag :: a -> [(a, OptInfo)] -> Arg a

-- | <a>vFlagAll</a> <tt>vs assoc</tt> is as <a>vFlag</a> except that it
--   can be present an infinity of times. In absence, <tt>vs</tt> is
--   yielded. When present, each value is collected in the order they
--   appear.
vFlagAll :: [a] -> [(a, OptInfo)] -> Arg [a]

-- | <a>opt</a> <tt>v ai</tt> is an optional argument that yields
--   <tt>v</tt> in absence, or an assigned value in presence. If the option
--   is present, but no value is assigned, it is considered a user-error
--   and usage is printed on exit.
opt :: ArgVal a => a -> OptInfo -> Arg a

-- | <a>defaultOpt</a> <tt>def v ai</tt> is as <a>opt</a> except if it is
--   present and no value is assigned on the command line, <tt>def</tt> is
--   the result.
defaultOpt :: ArgVal a => a -> a -> OptInfo -> Arg a

-- | <a>optAll</a> <tt>vs ai</tt> is like <a>opt</a> except that it yields
--   <tt>vs</tt> in absence and can appear an infinity of times. The values
--   it is assigned on the command line are accumulated in the order they
--   appear.
optAll :: (ArgVal a, Ord a) => [a] -> OptInfo -> Arg [a]

-- | <a>defaultOptAll</a> <tt>def vs ai</tt> is like <a>optAll</a> except
--   that if it is present without being assigned a value, the value
--   <tt>def</tt> takes its place in the list of results.
defaultOptAll :: (ArgVal a, Ord a) => a -> [a] -> OptInfo -> Arg [a]

-- | <a>pos</a> <tt>n v ai</tt> is an argument defined by the <tt>n</tt>th
--   positional argument on the command line. If absent the value
--   <tt>v</tt> is returned.
pos :: ArgVal a => Int -> a -> PosInfo -> Arg a

-- | <a>revPos</a> <tt>n v ai</tt> is as <a>pos</a> but counting from the
--   end of the command line to the front.
revPos :: ArgVal a => Int -> a -> PosInfo -> Arg a

-- | <a>posAny</a> <tt>vs ai</tt> yields a list of all positional arguments
--   or <tt>vs</tt> if none are present.
posAny :: ArgVal a => [a] -> PosInfo -> Arg [a]

-- | <a>posLeft</a> <tt>n vs ai</tt> yield a list of all positional
--   arguments to the left of the <tt>n</tt>th positional argument or
--   <tt>vs</tt> if there are none.
posLeft :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a]

-- | <a>posRight</a> <tt>n vs ai</tt> is as <a>posLeft</a> except yielding
--   all values to the right of the <tt>n</tt>th positional argument.
posRight :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a]

-- | <a>revPosLeft</a> <tt>n vs ai</tt> is as <a>posLeft</a> except
--   <tt>n</tt> counts from the end of the command line to the front.
revPosLeft :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a]

-- | <a>revPosRight</a> <tt>n vs ai</tt> is as <a>posRight</a> except
--   <tt>n</tt> counts from the end of the command line to the front.
revPosRight :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a]

-- | <a>value</a> <tt>arg</tt> makes <tt>arg</tt> into a <a>Term</a>.
value :: Arg a -> Term a

-- | <a>required</a> <tt>arg</tt> converts <tt>arg</tt> into a <a>Term</a>
--   such that it fails in the <a>Nothing</a> and yields <tt>a</tt> in the
--   <a>Just</a>.
--   
--   This is used for required positional arguments. There is nothing
--   stopping you from using it with optional arguments, except that they
--   would no longer be optional and it would be confusing from a user's
--   perspective.
required :: Arg (Maybe a) -> Term a

-- | <a>nonEmpty</a> <tt>arg</tt> is a <a>Term</a> that fails if its result
--   is empty. Intended for non-empty lists of positional arguments.
nonEmpty :: Arg [a] -> Term [a]

-- | <a>lastOf</a> <tt>arg</tt> is a <a>Term</a> that fails if its result
--   is empty and evaluates to the last element of the resulting list
--   otherwise. Intended for lists of flags or options where the last takes
--   precedence.
lastOf :: Arg [a] -> Term a

module System.Console.CmdTheLine.Term

-- | <a>eval</a> <tt>args ( term, termInfo )</tt> allows the user to pass
--   <tt>args</tt> directly to the evaluation mechanism. This is useful if
--   some kind of pre-processing is required. If you do not need to
--   pre-process command line arguments, use one of <a>exec</a> or
--   <a>run</a>. On failure the program exits.
eval :: [String] -> (Term a, TermInfo) -> IO a

-- | <a>exec</a> <tt>( term, termInfo )</tt> executes a command line
--   program, directly grabbing the command line arguments from the
--   environment and returning the result upon successful evaluation of
--   <tt>term</tt>. On failure the program exits.
exec :: (Term a, TermInfo) -> IO a

-- | <a>run</a> <tt>( term, termInfo )</tt> runs a <tt>term</tt> containing
--   an <a>IO</a> action, performs the action, and returns the result on
--   success. On failure the program exits.
run :: (Term (IO a), TermInfo) -> IO a

-- | <a>unwrap</a> <tt>args ( term, termInfo )</tt> unwraps a <a>Term</a>
--   without handling errors. The intent is for use in testing of Terms
--   where the programmer would like to consult error state without the
--   program exiting.
unwrap :: [String] -> (Term a, TermInfo) -> IO (Either EvalExit a)

-- | <a>evalChoice</a> <tt>args mainTerm choices</tt> is analogous to
--   <a>eval</a>, but for programs that provide a choice of commands.
evalChoice :: [String] -> (Term a, TermInfo) -> [(Term a, TermInfo)] -> IO a

-- | Analogous to <a>exec</a>, but for programs that provide a choice of
--   commands.
execChoice :: (Term a, TermInfo) -> [(Term a, TermInfo)] -> IO a

-- | Analogous to <a>run</a>, but for programs that provide a choice of
--   commands.
runChoice :: (Term (IO a), TermInfo) -> [(Term (IO a), TermInfo)] -> IO a

-- | Analogous to <a>unwrap</a>, but for programs that provide a choice of
--   commands.
unwrapChoice :: [String] -> (Term a, TermInfo) -> [(Term a, TermInfo)] -> IO (Either EvalExit a)

-- | Information about the way a <a>Term</a> exited early. Obtained by
--   either <a>unwrap</a>ing or <a>unwrapChoice</a>ing some Term. Handy for
--   testing programs when it is undesirable to exit execution of the
--   entire program when a Term exits early.
data EvalExit
Help :: HelpFormat -> (Maybe String) -> EvalExit
Usage :: Doc -> EvalExit
Msg :: Doc -> EvalExit
Version :: EvalExit
instance Error EvalExit

module System.Console.CmdTheLine

-- | The underlying Applicative of the library. A <tt>Term</tt> represents
--   a value in the context of being computed from the command line
--   arguments.
data Term a

-- | Information about a <a>Term</a>. It is recommended that
--   <a>TermInfo</a>s be created by customizing <a>defTI</a>, as in
--   
--   <pre>
--   termInfo = defTI
--     { termName = "caroline-no"
--     , termDoc  = "carry a line off"
--     }
--   </pre>
data TermInfo
TermInfo :: String -> String -> String -> String -> String -> [ManBlock] -> TermInfo

-- | The name of the command or program represented by the term. Defaults
--   to <tt>""</tt>.
termName :: TermInfo -> String

-- | Documentation for the term. Defaults to <tt>""</tt>.
termDoc :: TermInfo -> String

-- | The section under which to place the terms documentation. Defaults to
--   <tt>"COMMANDS"</tt>.
termSec :: TermInfo -> String

-- | The section under which to place a term's argument's documentation by
--   default. Defaults to <tt>"OPTIONS"</tt>.
stdOptSec :: TermInfo -> String

-- | A version string. Must be left blank for commands. Defaults to
--   <tt>""</tt>.
version :: TermInfo -> String

-- | A list of <a>ManBlock</a>s to append to the default
--   <tt>[ManBlock]</tt>. Defaults to <tt>[]</tt>.
man :: TermInfo -> [ManBlock]

-- | A default <a>TermInfo</a>.
defTI :: TermInfo

-- | Any <a>String</a> argument to a <a>ManBlock</a> constructor may
--   contain the following significant forms for a limited kind of
--   meta-programing.
--   
--   <ul>
--   <li>$(i,text): italicizes <tt>text</tt>.</li>
--   <li>$(b,text): bolds <tt>text</tt>.</li>
--   <li>$(mname): evaluates to the name of the default term if there are
--   choices of commands, or the only term otherwise.</li>
--   <li>$(tname): evaluates to the name of the currently evaluating
--   term.</li>
--   </ul>
--   
--   Additionally, text inside the content portion of an <a>I</a>
--   constructor may contain one of the following significant forms.
--   
--   <ul>
--   <li>$(argName): evaluates to the name of the argument being
--   documented.</li>
--   </ul>
data ManBlock

-- | A section title.
S :: String -> ManBlock

-- | A paragraph.
P :: String -> ManBlock

-- | A label-content pair. As in an argument definition and its
--   accompanying documentation.
I :: String -> String -> ManBlock

-- | Suppress the normal blank line following a <a>P</a> or an <a>I</a>.
NoBlank :: ManBlock

-- | The format to print help in.
data HelpFormat
Pager :: HelpFormat
Plain :: HelpFormat
Groff :: HelpFormat

-- | A monad for values in the context of possibly failing with a helpful
--   message.
type Err = ErrorT Fail IO

-- | Fail with an arbitrary message on failure.
msgFail :: Doc -> Err a

-- | Fail with a message along with the usage on failure.
usageFail :: Doc -> Err a

-- | A format to print the help in and an optional name of the term to
--   print help for. If <a>Nothing</a> is supplied, help will be printed
--   for the currently evaluating term.
helpFail :: HelpFormat -> Maybe String -> Err a

-- | <a>ret</a> <tt>term</tt> folds <tt>term</tt>'s <a>Err</a> context into
--   the library to be handled internally and as seamlessly as other error
--   messages that are built in.
ret :: Term (Err a) -> Term a


-- | Adapter for <a>System.Console.GetOpt</a>.
module System.Console.CmdTheLine.GetOpt

-- | Sequence a list of <tt><a>OptDescr</a>s</tt> into a term. Absent flags
--   (specified with <a>NoArg</a>) are filtered out.
optDescrsTerm :: [OptDescr a] -> Term [a]

-- | Convert an <a>OptDescr</a> into a <a>Term</a> which returns
--   <a>Nothing</a> if <a>NoArg</a> is specified and the flag is absent or
--   <a>Just</a> the argument otherwise.
optDescrToTerm :: OptDescr a -> Term (Maybe a)
