-- 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 -- http://erratique.ch/software/cmdliner 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 -- http://elifrey.com/2012/07/23/CmdTheLine-Tutorial/. -- -- Suggestions, comments, and bug reports are appreciated. Please see the -- bug and issue tracker at http://github.com/eli-frey/cmdtheline. -- -- Changes since 0.1: -- -- -- -- Changes since 0.2.0: -- -- -- -- Changes since 0.2.1 -- -- @package cmdtheline @version 0.2.3 module System.Console.CmdTheLine.Util -- | fileExists term checks that String in -- term is a path to an existing file. If it is not, exit -- with an explanatory message for the user. fileExists :: Term String -> Term String -- | dirExists term checks that String in -- term is a path to an existing directory. If it is not, -- exit with an explanatory message for the user. dirExists :: Term String -> Term String -- | pathExists term checks that String in -- term is a path to an existing file or directory. If it -- is not, exit with an explanatory message for the user. pathExists :: Term String -> Term String -- | filesExist term is as fileExists but for a -- term containing a list of file paths. filesExist :: Term [String] -> Term [String] -- | dirsExist term is as dirExists but for a -- term containing a list of directory paths. dirsExist :: Term [String] -> Term [String] -- | pathsExist term is as pathExists but for a -- term containing a list of paths. pathsExist :: Term [String] -> Term [String] -- | validPath term checks that String in -- term 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 converter. pp :: ArgVal a => ArgPrinter a -- | The parsing part of a converter. parser :: ArgVal a => ArgParser a -- | fromParsec onErr p makes an ArgParser from -- p using onErr to produce meaningful error messages. -- On failure, onErr 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 -- ( string, value ) pairs. Unambiguous prefixes of -- string map to value. enum :: Eq a => [(String, a)] -> Converter a -- | A converter of Maybe values of ArgVal instances. -- -- Parses as: -- -- 
--   fmap Just . parser
--
-- -- Pretty prints as: -- -- 
--   maybe empty pp
--
just :: ArgVal a => Converter (Maybe a) -- | list sep creates a converter of lists of an -- ArgVal instance separated by sep. list :: ArgVal a => Char -> Converter [a] -- | pair sep creates a converter of pairs of ArgVal -- instances separated by sep. pair :: (ArgVal a, ArgVal b) => Char -> Converter (a, b) -- | triple sep creates a converter of triples of -- ArgVal instances separated by sep. triple :: (ArgVal a, ArgVal b, ArgVal c) => Char -> Converter (a, b, c) -- | quadruple sep creates a converter of quadruples of -- ArgVal instances separated by sep. quadruple :: (ArgVal a, ArgVal b, ArgVal c, ArgVal d) => Char -> Converter (a, b, c, d) -- | quintuple sep creates a converter of quintuples of -- ArgVal instances separated by sep. 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. -- -- data OptInfo -- | Information about a positional argument. Exposes the folowing fields. -- -- data PosInfo -- | Initialize an OptInfo by providing a list of names. The fields -- optName, optDoc, and optSec can then be -- manipulated post-mortem, as in -- -- 
--   inf =(optInfo    [ "i", "insufflation" ])
--       { optName = "INSUFFERABLE"
--       , optDoc  = "in the haunted house's harrow"
--       , optSec  = "NOT FOR AUGHT"
--       }
--
-- -- Names of one character in length will be prefixed by - on the -- command line, while longer names will be prefixed by --. -- -- It is considered a programming error to provide an empty list of names -- to optInfo. optInfo :: [String] -> OptInfo -- | Initialize a PosInfo. The fields posName, -- posDoc, and posSec can then be manipulated -- post-mortem, as in -- -- 
--   inf = posInfo
--       { posName = "DEST"
--       , posDoc  = "A destination for the operation."
--       , posSec  = "DESTINATIONS"
--       }
--
-- -- The fields posName and posDoc must be non-empty -- strings for the argument to be listed with its documentation under the -- section posSec of generated help. posInfo :: PosInfo -- | Create a command line flag that can appear at most once on the command -- line. Yields False in absence and True in presence. flag :: OptInfo -> Arg Bool -- | As flag but may appear an infinity of times. Yields a list of -- Trues as long as the number of times present. flagAll :: OptInfo -> Arg [Bool] -- | vFlag v [ ( v1, ai1 ), ... ] is an argument that can -- be present at most once on the command line. It takes on the value -- vn when appearing as ain. vFlag :: a -> [(a, OptInfo)] -> Arg a -- | vFlagAll vs assoc is as vFlag except that it -- can be present an infinity of times. In absence, vs is -- yielded. When present, each value is collected in the order they -- appear. vFlagAll :: [a] -> [(a, OptInfo)] -> Arg [a] -- | opt v ai is an optional argument that yields -- v 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 -- | defaultOpt def v ai is as opt except if it is -- present and no value is assigned on the command line, def is -- the result. defaultOpt :: ArgVal a => a -> a -> OptInfo -> Arg a -- | optAll vs ai is like opt except that it yields -- vs 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] -- | defaultOptAll def vs ai is like optAll except -- that if it is present without being assigned a value, the value -- def takes its place in the list of results. defaultOptAll :: (ArgVal a, Ord a) => a -> [a] -> OptInfo -> Arg [a] -- | pos n v ai is an argument defined by the nth -- positional argument on the command line. If absent the value -- v is returned. pos :: ArgVal a => Int -> a -> PosInfo -> Arg a -- | revPos n v ai is as pos but counting from the -- end of the command line to the front. revPos :: ArgVal a => Int -> a -> PosInfo -> Arg a -- | posAny vs ai yields a list of all positional arguments -- or vs if none are present. posAny :: ArgVal a => [a] -> PosInfo -> Arg [a] -- | posLeft n vs ai yield a list of all positional -- arguments to the left of the nth positional argument or -- vs if there are none. posLeft :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a] -- | posRight n vs ai is as posLeft except yielding -- all values to the right of the nth positional argument. posRight :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a] -- | revPosLeft n vs ai is as posLeft except -- n counts from the end of the command line to the front. revPosLeft :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a] -- | revPosRight n vs ai is as posRight except -- n counts from the end of the command line to the front. revPosRight :: ArgVal a => Int -> [a] -> PosInfo -> Arg [a] -- | value arg makes arg into a Term. value :: Arg a -> Term a -- | required arg converts arg into a Term -- such that it fails in the Nothing and yields a in the -- Just. -- -- 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 -- | nonEmpty arg is a Term that fails if its result -- is empty. Intended for non-empty lists of positional arguments. nonEmpty :: Arg [a] -> Term [a] -- | lastOf arg is a Term 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 -- | eval args ( term, termInfo ) allows the user to pass -- args 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 exec or -- run. On failure the program exits. eval :: [String] -> (Term a, TermInfo) -> IO a -- | exec ( term, termInfo ) executes a command line -- program, directly grabbing the command line arguments from the -- environment and returning the result upon successful evaluation of -- term. On failure the program exits. exec :: (Term a, TermInfo) -> IO a -- | run ( term, termInfo ) runs a term containing -- an IO action, performs the action, and returns the result on -- success. On failure the program exits. run :: (Term (IO a), TermInfo) -> IO a -- | unwrap args ( term, termInfo ) unwraps a Term -- 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) -- | evalChoice args mainTerm choices is analogous to -- eval, but for programs that provide a choice of commands. evalChoice :: [String] -> (Term a, TermInfo) -> [(Term a, TermInfo)] -> IO a -- | Analogous to exec, but for programs that provide a choice of -- commands. execChoice :: (Term a, TermInfo) -> [(Term a, TermInfo)] -> IO a -- | Analogous to run, but for programs that provide a choice of -- commands. runChoice :: (Term (IO a), TermInfo) -> [(Term (IO a), TermInfo)] -> IO a -- | Analogous to unwrap, 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 Term exited early. Obtained by -- either unwraping or unwrapChoiceing 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 Term represents -- a value in the context of being computed from the command line -- arguments. data Term a -- | Information about a Term. It is recommended that -- TermInfos be created by customizing defTI, as in -- -- 
--   termInfo = defTI
--     { termName = "caroline-no"
--     , termDoc  = "carry a line off"
--     }
--
data TermInfo TermInfo :: String -> String -> String -> String -> String -> [ManBlock] -> TermInfo -- | The name of the command or program represented by the term. Defaults -- to "". termName :: TermInfo -> String -- | Documentation for the term. Defaults to "". termDoc :: TermInfo -> String -- | The section under which to place the terms documentation. Defaults to -- "COMMANDS". termSec :: TermInfo -> String -- | The section under which to place a term's argument's documentation by -- default. Defaults to "OPTIONS". stdOptSec :: TermInfo -> String -- | A version string. Must be left blank for commands. Defaults to -- "". version :: TermInfo -> String -- | A list of ManBlocks to append to the default -- [ManBlock]. Defaults to []. man :: TermInfo -> [ManBlock] -- | A default TermInfo. defTI :: TermInfo -- | Any String argument to a ManBlock constructor may -- contain the following significant forms for a limited kind of -- meta-programing. -- -- -- -- Additionally, text inside the content portion of an I -- constructor may contain one of the following significant forms. -- -- 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 P or an I. 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 Nothing is supplied, help will be printed -- for the currently evaluating term. helpFail :: HelpFormat -> Maybe String -> Err a -- | ret term folds term's Err 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 System.Console.GetOpt. module System.Console.CmdTheLine.GetOpt -- | Sequence a list of OptDescrs into a term. Absent flags -- (specified with NoArg) are filtered out. optDescrsTerm :: [OptDescr a] -> Term [a] -- | Convert an OptDescr into a Term which returns -- Nothing if NoArg is specified and the flag is absent or -- Just the argument otherwise. optDescrToTerm :: OptDescr a -> Term (Maybe a)