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


-- | Command line parsing framework for console applications
--   
--   Provides a combinator library for defining a command line parser.
@package argparser
@version 0.3.3


-- | Base types shared by several EasyConsole modules.
module System.Console.ArgParser.BaseType

-- | Simple command line arg
type Arg = String

-- | List of args provided
type Args = [Arg]

-- | Flag collection with corresponding args
type Flags = Map Arg Args

-- | Structured args to be parsed. Pair of (positionnal arguments, flag
--   arguments)
type NiceArgs = (Args, Flags)

-- | Type representing the result of the parse. Right val in case of
--   success or Left msg if there was an error.
type ParseResult a = Either String a

-- | Data structure describing a parameter
data ParamDescr
ParamDescr :: (String -> String) -> String -> (String -> String) -> String -> String -> ParamDescr

-- | Short description of the parameter format
argUsageFmt :: ParamDescr -> String -> String

-- | Category of parameter (optional/mandatory)
argCategory :: ParamDescr -> String

-- | Format of the parameter to provide
argFormat :: ParamDescr -> String -> String

-- | Description of the parameter
argDescr :: ParamDescr -> String

-- | Description of the parameter in the usage
argMetaVar :: ParamDescr -> String

-- | Returns a short description of the input format of a parameter.
argUsage :: ParamDescr -> String

-- | Returns a long description of the input format of a parameter.
getArgFormat :: ParamDescr -> String

-- | A parser actual function
data Parser a
Parser :: (NiceArgs -> (ParseResult a, NiceArgs)) -> Parser a

-- | Represent a full parameter spec
data ParserSpec a
ParserSpec :: [ParamDescr] -> Parser a -> ParserSpec a
getParserParams :: ParserSpec a -> [ParamDescr]
getParserFun :: ParserSpec a -> Parser a

-- | A special action with more possibilities. The full arg list will be
--   provided, with the command line spec itself.
type SpecialAction a = CmdLnInterface a -> NiceArgs -> ParseResult a

-- | A special parser allowing to perform standard actions. Used for
--   version<i>help</i>subparsers.
type SpecialFlag a = (ParserSpec Bool, SpecialAction a)

-- | A command line application, with a parser and a description
data CmdLnInterface a
CmdLnInterface :: ParserSpec a -> [SpecialFlag a] -> String -> Maybe String -> Maybe String -> Maybe String -> CmdLnInterface a

-- | The argument parser
cmdArgParser :: CmdLnInterface a -> ParserSpec a

-- | The special flags
specialFlags :: CmdLnInterface a -> [SpecialFlag a]

-- | The application name. Usally the binary name.
getAppName :: CmdLnInterface a -> String

-- | Optional application version
getAppVersion :: CmdLnInterface a -> Maybe String

-- | Optional description
getAppDescr :: CmdLnInterface a -> Maybe String

-- | Optional epilog
getAppEpilog :: CmdLnInterface a -> Maybe String
instance Applicative Parser
instance Functor Parser
instance Applicative ParserSpec
instance Functor ParserSpec


-- | Functions used to specify a parser for command line arguments.
module System.Console.ArgParser.Parser

-- | interface allowing to define a basic block of a command line parser
class ParamSpec spec
getParser :: ParamSpec spec => spec res -> Parser res
getParamDescr :: ParamSpec spec => spec res -> [ParamDescr]

-- | Converts any <a>ParamSpec</a> to a <a>ParserSpec</a>
liftParam :: ParamSpec spec => spec res -> ParserSpec res

-- | Build a parser from a type constructor and a <a>ParamSpec</a>
--   
--   <pre>
--   MyApp `parsedBy` myparamspec
--   </pre>
parsedBy :: ParamSpec spec => (a -> b) -> spec a -> ParserSpec b

-- | Build a parser from a parser and a <a>ParamSpec</a>
--   
--   <pre>
--   MyApp `parsedBy` myparamspec `andBy` myotherparamspec
--   </pre>
andBy :: ParamSpec spec => ParserSpec (a -> b) -> spec a -> ParserSpec b

-- | This is <a>parsedBy</a> with a different fixity.
subParser :: ParamSpec spec => (a -> b) -> spec a -> ParserSpec b
instance ParamSpec ParserSpec


-- | Parameters are basic building blocks of a command line parser.
module System.Console.ArgParser.Params

-- | Defines a parameter consuming arguments on the command line. The
--   source defines whether the arguments are positional:
--   
--   <pre>
--   myprog posarg1 posarg2 ...
--   </pre>
--   
--   ... or are taken from a flag:
--   
--   <pre>
--   myprog --myflag flagarg1 flagarg2 ...
--   </pre>
--   
--   short form:
--   
--   <pre>
--   myprog -m flagarg1 flagarg2 ...
--   </pre>
--   
--   One can provide two signatures of parsing function using the
--   'ArgParser type':
--   
--   <ul>
--   <li><a>SingleArgParser</a> means that the parameter expect exactly one
--   arg</li>
--   <li><a>MulipleArgParser</a> means that the parameter expect any number
--   of args</li>
--   </ul>
data StdArgParam a
StdArgParam :: (Optionality a) -> ArgSrc -> Key -> (ArgParser a) -> StdArgParam a

-- | Defines the source of a parameter: either positional or flag.
data ArgSrc
Flag :: ArgSrc
Pos :: ArgSrc

-- | Specify the format of a flag
data FlagFormat

-- | Possible short format ie <tt>-f</tt> or <tt>--foo</tt>
Short :: FlagFormat

-- | Only long format ie <tt>--foo</tt>
Long :: FlagFormat

-- | Defines the number of args consumed by a standard parameter
data ArgParser a

-- | Uses exactly one arg
SingleArgParser :: (Arg -> ParseResult a) -> ArgParser a

-- | Uses any number of args
MulipleArgParser :: (Args -> ParseResult a) -> ArgParser a

-- | Defines whether a parameter is mandatory or optional. When a parameter
--   is marked as Optional, a default value must be provided.
data Optionality a
Mandatory :: Optionality a
Optional :: a -> Optionality a

-- | identifier used to specify the name of a flag or a positional
--   argument.
type Key = String

-- | A simple command line flag. The parsing function will be passed True
--   if the flag is present, if the flag is provided to the command line,
--   and False otherwise. For a key <tt>foo</tt>, the flag can either be
--   <tt>--foo</tt> or <tt>-f</tt>
data FlagParam a
FlagParam :: FlagFormat -> Key -> (Bool -> a) -> FlagParam a

-- | Allows the user to provide a description for a particular parameter.
--   Can be used as an infix operator:
--   
--   <pre>
--   myparam `Descr` "this is my description"
--   </pre>
data Descr spec a
Descr :: spec a -> String -> Descr spec a
getdvalue :: Descr spec a -> spec a
getuserdescr :: Descr spec a -> String

-- | Allows the user to provide a description for a particular parameter.
--   Can be used as an infix operator:
--   
--   <pre>
--   myparam `Descr` "this is my description"
--   </pre>
data MetaVar spec a
MetaVar :: spec a -> String -> MetaVar spec a
getmvvalue :: MetaVar spec a -> spec a
getusermvar :: MetaVar spec a -> String
instance ParamSpec StdArgParam
instance ParamSpec spec => ParamSpec (MetaVar spec)
instance ParamSpec spec => ParamSpec (Descr spec)
instance ParamSpec FlagParam


-- | Collection of functions which are basically shortcuts of
--   <a>System.Console.EasyConsole.Params</a> versions. If you cannot find
--   a parameter fitting your needs, you should check this module.
--   
--   Values provided to <tt>parsedBy</tt> and <tt>andBy</tt> should be
--   created with the following functions. The types are inferred.
--   ArgParser will use <tt>readMaybe</tt> to convert the arguments to
--   haskell values, except for strings which will be passed unmodified.
--   
--   Flags can be passed in long form (<tt>--foo</tt>) or short form
--   (<tt>-f</tt>) You may also provide a prefix form such as
--   <tt>--fo</tt>.
--   
--   Mandatory parameters will fail if the argument is absent or invalid.
--   Optional parameters only fail if the argument is invalid (ie
--   <tt>foo</tt> passed as <tt>Int</tt>)
--   
--   Note that single arg parameters need exactly one arg, and that
--   multiple args parameters can have any number of args (0 included).
module System.Console.ArgParser.QuickParams

-- | A simple command line flag. The parsing function will return True if
--   the flag is present, if the flag is provided to the command line, and
--   False otherwise. For a key <tt>foo</tt>, the flag can either be
--   <tt>--foo</tt> or <tt>-f</tt>
boolFlag :: Key -> FlagParam Bool

-- | A mandatory flag argument parameter
reqFlag :: RawRead a => Key -> StdArgParam a

-- | An optional flag argument parameter
optFlag :: RawRead a => a -> Key -> StdArgParam a

-- | A mandatory positional argument parameter
reqPos :: RawRead a => Key -> StdArgParam a

-- | An optional positional argument parameter
optPos :: RawRead a => a -> Key -> StdArgParam a

-- | A mandatory flag argument parameter taking multiple arguments
reqFlagArgs :: RawRead a => Key -> b -> (b -> a -> b) -> StdArgParam b

-- | An optional flag argument parameter taking multiple arguments
optFlagArgs :: RawRead a => b -> Key -> b -> (b -> a -> b) -> StdArgParam b

-- | A parameter consuming all the remaining positional parameters
posArgs :: RawRead a => Key -> b -> (b -> a -> b) -> StdArgParam b

-- | A typeclass used to define a way a converting string to specific
--   types. It is similar to read. The main difference is that strings are
--   parsed without quotes.
--   
--   <pre>
--   rawRead "foo" :: Maybe String == Just "foo"
--   </pre>
class RawRead a
instance RawRead Int
instance RawRead Float
instance RawRead a => RawRead [a]
instance RawRead Char


-- | Preprocess args from a list of words to a pair containing positional
--   args/flag arguments.
module System.Console.ArgParser.ArgsProcess

-- | Separate positional arguments from flag arguments
preprocess :: Args -> NiceArgs


-- | Module containing helpers to print information about a parser.
module System.Console.ArgParser.Format

-- | Prints a long usage such as
--   
--   <pre>
--   foo bar [bay]
--   </pre>
showCmdLineAppUsage :: CmdLineFormat -> CmdLnInterface a -> String

-- | Prints the application name and version
showCmdLineVersion :: CmdLnInterface a -> String

-- | Specification of the help layout
data CmdLineFormat
CmdLineFormat :: Int -> Int -> Int -> CmdLineFormat
maxKeyWidth :: CmdLineFormat -> Int
keyIndentWidth :: CmdLineFormat -> Int
maxDescrWidth :: CmdLineFormat -> Int

-- | Default specification for the help layout
defaultFormat :: CmdLineFormat


-- | Functions used to build and run command line applications.
module System.Console.ArgParser.Run

-- | Runs an apllication with the user provided arguments. It is a shorter
--   way of calling <a>mkApp</a> and <a>runApp</a>
withParseResult :: ParserSpec a -> (a -> IO ()) -> IO ()

-- | Runs a command line application with the user provided arguments. If
--   the parsing succeeds, run the application. Print the returned message
--   otherwise
runApp :: CmdLnInterface a -> (a -> IO ()) -> IO ()

-- | Parse the arguments with the parser provided to the function.
parseArgs :: Args -> CmdLnInterface a -> ParseResult a

-- | Parse the arguments with the parser provided to the function.
parseNiceArgs :: NiceArgs -> CmdLnInterface a -> ParseResult a

-- | Build an application with no version/description and with a name equal
--   to the file name.
mkApp :: ParserSpec a -> IO (CmdLnInterface a)

-- | Build an application with no version/description and with a name equal
--   to the provided String.
mkDefaultApp :: ParserSpec a -> String -> CmdLnInterface a

-- | default version and help special actions
defaultSpecialFlags :: [SpecialFlag a]

-- | Set the description of an interface
setAppDescr :: CmdLnInterface a -> String -> CmdLnInterface a

-- | Set the bottom text of an interface
setAppEpilog :: CmdLnInterface a -> String -> CmdLnInterface a

-- | Set the name of an interface
setAppName :: CmdLnInterface a -> String -> CmdLnInterface a


-- | Subparsers allows the creation of complex command line applications
--   organized around commands.
module System.Console.ArgParser.SubParser

-- | Create a parser composed of a list of subparsers.
--   
--   Each subparser is associated with a command which the user must type
--   to activate.
mkSubParser :: [(Arg, CmdLnInterface a)] -> IO (CmdLnInterface a)

-- | Same that <a>mkSubParser</a> but allows a custom name
mkSubParserWithName :: String -> [(Arg, CmdLnInterface a)] -> CmdLnInterface a
instance ParamSpec (CommandParam resT)
instance ParamSpec EmptyParam


-- | Simple command line parsing library. This library provides a small
--   combinator dsl to specify a parser for a datatype. Running the parser
--   will automatically consume and convert command line arguments. Default
--   special action such as help/usage are automatically built from the
--   parser specification.
--   
--   Here is a quick example.
--   
--   <pre>
--   data MyTest =  -- First, we need a datatype
--     MyTest Int Int
--     deriving (Show) -- we will print the values
--   
--   myTestParser -- Then, we define a parser
--     :: ParserSpec MyTest
--   myTestParser = MyTest
--     `parsedBy` reqPos "pos1"
--     `andBy` optPos 0 "pos2"
--   
--   main = withParseResult myTestParser print
--   </pre>
--   
--   Building this app will produce an executable <tt>foo</tt> which will
--   behave like this:
--   
--   <pre>
--   $ foo 1 2
--   MyTest 1 2
--   $ foo 3
--   MyTest 3 0
--   $ foo -h
--   foo
--   usage : foo pos1 [pos2] [-h] [--version]
--   
--   mandatory arguments:
--    pos1
--   
--   optional arguments:
--    pos2
--    -h, --help                    show this help message and exit
--    --version                     print the program version and exit
--   </pre>
module System.Console.ArgParser

-- | Build a parser from a type constructor and a <a>ParamSpec</a>
--   
--   <pre>
--   MyApp `parsedBy` myparamspec
--   </pre>
parsedBy :: ParamSpec spec => (a -> b) -> spec a -> ParserSpec b

-- | Build a parser from a parser and a <a>ParamSpec</a>
--   
--   <pre>
--   MyApp `parsedBy` myparamspec `andBy` myotherparamspec
--   </pre>
andBy :: ParamSpec spec => ParserSpec (a -> b) -> spec a -> ParserSpec b

-- | Build an application with no version/description and with a name equal
--   to the file name.
mkApp :: ParserSpec a -> IO (CmdLnInterface a)

-- | Build an application with no version/description and with a name equal
--   to the provided String.
mkDefaultApp :: ParserSpec a -> String -> CmdLnInterface a

-- | Allows the user to provide a description for a particular parameter.
--   Can be used as an infix operator:
--   
--   <pre>
--   myparam `Descr` "this is my description"
--   </pre>
data Descr spec a
Descr :: spec a -> String -> Descr spec a

-- | Set the description of an interface
setAppDescr :: CmdLnInterface a -> String -> CmdLnInterface a

-- | Set the bottom text of an interface
setAppEpilog :: CmdLnInterface a -> String -> CmdLnInterface a

-- | Create a parser composed of a list of subparsers.
--   
--   Each subparser is associated with a command which the user must type
--   to activate.
mkSubParser :: [(Arg, CmdLnInterface a)] -> IO (CmdLnInterface a)

-- | Runs an apllication with the user provided arguments. It is a shorter
--   way of calling <a>mkApp</a> and <a>runApp</a>
withParseResult :: ParserSpec a -> (a -> IO ()) -> IO ()

-- | Runs a command line application with the user provided arguments. If
--   the parsing succeeds, run the application. Print the returned message
--   otherwise
runApp :: CmdLnInterface a -> (a -> IO ()) -> IO ()

-- | Parse the arguments with the parser provided to the function.
parseArgs :: Args -> CmdLnInterface a -> ParseResult a

-- | A simple command line flag. The parsing function will return True if
--   the flag is present, if the flag is provided to the command line, and
--   False otherwise. For a key <tt>foo</tt>, the flag can either be
--   <tt>--foo</tt> or <tt>-f</tt>
boolFlag :: Key -> FlagParam Bool

-- | A mandatory flag argument parameter
reqFlag :: RawRead a => Key -> StdArgParam a

-- | An optional flag argument parameter
optFlag :: RawRead a => a -> Key -> StdArgParam a

-- | A mandatory positional argument parameter
reqPos :: RawRead a => Key -> StdArgParam a

-- | An optional positional argument parameter
optPos :: RawRead a => a -> Key -> StdArgParam a

-- | A mandatory flag argument parameter taking multiple arguments
reqFlagArgs :: RawRead a => Key -> b -> (b -> a -> b) -> StdArgParam b

-- | An optional flag argument parameter taking multiple arguments
optFlagArgs :: RawRead a => b -> Key -> b -> (b -> a -> b) -> StdArgParam b

-- | A parameter consuming all the remaining positional parameters
posArgs :: RawRead a => Key -> b -> (b -> a -> b) -> StdArgParam b