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


-- | Simple Command Line Interface Library
--   
--   This package provides a simple Command Line Library
@package cli
@version 0.0.5


-- | Copyright : Copyright © 2014 Nicolas DI PRIMA
--   
--   Maintainer : Nicolas DI PRIMA <a>nicolas@di-prima.fr</a> Stability :
--   experimental Portability : unknown
--   
--   This module aimes to provide an easy and low-dependencies Command Line
--   configuration options.
--   
--   You can create a new command for your program by creating an object
--   And creating an instance of CLI of this object
--   
--   <pre>
--   data MyEchoCommand = MyEchoCommand
--   instance CLI MyCommand where
--      name _ = "cmd"
--      desc _ = "just echo the given arguments"
--      options _ = [ OptHelp [] (Just "string") "the message to print" ]
--      action _ _ =
--          withStr "string" $ str -&gt; exectute $ putStrLn str
--   </pre>
--   
--   And to create you application, you need 2 functions (initialize, with
--   and defaultMain). * <tt>initialize</tt>: only create the default
--   CLIContext with a default Help command and a default Usage function *
--   <tt>with</tt>: insert the Command into the CLIContext *
--   <tt>defaultMain</tt>: will trigger the right command
--   
--   <pre>
--   main :: IO ()
--   main = defaultMain $ with MyEchoCommand $ initialize "a message header in case the help command is triggered"
--   </pre>
module Application.CLI

-- | The default Main It will analyze the program's parameters and will
--   trigger the right command.
defaultMain :: CLIContext -> IO ()

-- | This is the CLI Class All command you want to add into the CLIContext
--   must be an instance of this class.
class CLI cli

-- | This is the name of the command. It is also the command line option
--   the action will be triggered every time this string is found to be the
--   first argument of the program
name :: CLI cli => cli -> String

-- | A description of this command Will be use in the default Usage and the
--   Help function
desc :: CLI cli => cli -> String

-- | The list of Options It is only for printing, the parser won't use this
--   to parse the command parameters.
options :: CLI cli => cli -> [OptHelp]

-- | The action to perfom every time the <tt>name</tt> is found to be the
--   first string of the program parameters
action :: CLI cli => cli -> CLIContext -> Options -> IO ()

-- | Option help
--   
--   It describes the Command parameters
data OptHelp
OptHelp :: [String] -> Maybe String -> String -> OptHelp

-- | an option can have multiple symbols, mainly a short option and a long
--   option for example [ "-h", "--help" ]
[optSymbols] :: OptHelp -> [String]

-- | an option can have an argument, or not
[optArgument] :: OptHelp -> Maybe String

-- | option description
[optDescription] :: OptHelp -> String

-- | This is the default help command
--   
--   It is triggered by the command "help" and also provides an option to
--   print a specific command options
data Help
Help :: Help

-- | Print all the Command's Option help
printHelp :: String -> String -> CLIContext -> String

-- | This is the Command Line Context This object embeds: * the commands to
--   trigger * a default command in case no command is given * a program
--   description * a Helper Command: the command to trigger in case of a
--   wrong command (example: Usage)
data CLIContext

-- | Program's description
getHeader :: CLIContext -> String

-- | Initialize a collection of command
initialize :: String -> CLIContext

-- | Initialize a collection of commands
initializeWithDefault :: CLI cliDefault => cliDefault -> String -> CLIContext

-- | Add a new Command into a collection of commands
with :: CLI cli => cli -> CLIContext -> CLIContext

-- | The Command Options parameter
type Options = [String]

-- | This function is to expect an argument at the Head of the
--   <tt>Options</tt> if the command is not found at the head, the program
--   fails and the description message is printed
withStr :: String -> (String -> Options -> IO a) -> Options -> IO a

-- | This function is to expect an optional argument of the command is not
--   found at the Head of the <tt>Options</tt> the function will be
--   executed with Nothing, otherwise it will be executed with (Just
--   <tt>String</tt>)
withOptionalStr :: (Maybe String -> Options -> IO a) -> Options -> IO a

-- | Look for a parameterized option The given list of flags are the
--   potential list of flags that can be use to find the position of the
--   options
--   
--   This parameter can be found anywhere in the Options list and the
--   argument of the function will be the string following one of this
--   Flags The parameter and its value are removed from the options before
--   being use into the function.
withParameterStr :: [String] -> (String -> Options -> IO a) -> Options -> IO a

-- | idem as <tt>withParameterStr</tt> but it is an optional parameter
withOptionalParameterStr :: [String] -> (Maybe String -> Options -> IO a) -> Options -> IO a

-- | This function is to expect Flag in the Options it will look into all
--   the options and will remove the string from the Options
withFlag :: [String] -> (Bool -> Options -> IO a) -> Options -> IO a

-- | This function makes the use of the other function easier and also
--   provide a verification that there is no "unused function". If there is
--   unexpected options remaining, the program will stop and an error
--   message will be printed
execute :: IO a -> Options -> IO a
instance Application.CLI.Class.CLI Application.CLI.Usage
instance Application.CLI.Class.CLI Application.CLI.Help