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

-- | Create command line interfaces with ease
--   
--   Create command line interfaces with ease
@package getopt-generics
@version 0.13.1.0

module WithCli.Pure

-- | Pure variant of withCliModified.
withCliPure :: WithCliPure function a => String -> [Modifier] -> [String] -> function -> Result a
class WithCliPure function output

-- | Type to wrap results from withCliPure.
data Result a

-- | The CLI was used correctly and a value of type a was
--   successfully constructed.
Success :: a -> Result a

-- | The CLI was used incorrectly. The Result contains error
--   messages.
--   
--   It can also happen that the data type you're trying to use isn't
--   supported. See the README for details.
Errors :: String -> Result a

-- | The CLI was used with --help. The Result contains the
--   help message.
OutputAndExit :: String -> Result a

-- | Handles an input of type Result a:
--   
--   
--   
- On Success a it returns the value a.
--   
- On OutputAndExit message it writes the message to
--   stdout and throws ExitSuccess.
--   
- On Errors errs it writes the error messages to
--   stderr and throws ExitFailure 1.
--   
--   
--   This is used by withCli to handle parse results.
handleResult :: Result a -> IO a

-- | Everything that can be used as an argument to your main
--   function (see withCli) needs to have a HasArguments
--   instance.
--   
--   HasArguments also allows to conjure up instances for record
--   types to create more complex command line interfaces. Here's an
--   example:
--   
--   
--   {-# LANGUAGE DeriveAnyClass #-}
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import WithCli
--   
--   data Options
--     = Options {
--       port :: Int,
--       daemonize :: Bool,
--       config :: Maybe FilePath
--     }
--     deriving (Show, Generic, HasArguments)
--   
--   main :: IO ()
--   main = withCli run
--   
--   run :: Options -> IO ()
--   run = print
--   
--   
--   In a shell this program behaves like this:
--   
--   
--   $ program --port 8080 --config some/path
--   Options {port = 8080, daemonize = False, config = Just "some/path"}
--   $ program  --port 8080 --daemonize
--   Options {port = 8080, daemonize = True, config = Nothing}
--   $ program --port foo
--   cannot parse as INTEGER: foo
--   # exit-code 1
--   $ program
--   missing option: --port=INTEGER
--   # exit-code 1
--   $ program --help
--   program [OPTIONS]
--         --port=INTEGER
--         --daemonize
--         --config=STRING (optional)
--     -h  --help                      show help and exit
--   
class HasArguments a
argumentsParser :: HasArguments a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)
($dmargumentsParser) :: (HasArguments a, Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | Useful for implementing your own instances of HasArguments on
--   top of a custom Argument instance.
atomicArgumentsParser :: Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | Argument is a typeclass for things that can be parsed as atomic
--   values from single command line arguments, e.g. strings (and
--   filenames) and numbers.
--   
--   Occasionally you might want to declare your own instance for
--   additional type safety and for providing a more informative command
--   argument type. Here's an example:
--   
--   
--   {-# LANGUAGE DeriveDataTypeable #-}
--   
--   import WithCli
--   
--   data File = File FilePath
--     deriving (Show, Typeable)
--   
--   instance Argument File where
--     argumentType Proxy = "custom-file-type"
--     parseArgument f = Just (File f)
--   
--   instance HasArguments File where
--     argumentsParser = atomicArgumentsParser
--   
--   main :: IO ()
--   main = withCli run
--   
--   run :: File -> IO ()
--   run = print
--   
--   
--   And this is how the above program behaves:
--   
--   
--   $ program --help
--   program [OPTIONS] custom-file-type
--     -h  --help  show help and exit
--   $ program some/file
--   File "some/file"
--   
class Argument a
argumentType :: Argument a => Proxy a -> String
parseArgument :: Argument a => String -> Maybe a

-- | Modifiers can be used to customize the command line parser.
data Modifier

-- | AddShortOption fieldName c adds the Char c as
--   a short option for the field addressed by fieldName.
AddShortOption :: String -> Char -> Modifier

-- | RenameOption fieldName customName renames the option
--   generated through the fieldName by customName.
RenameOption :: String -> String -> Modifier

-- | RenameOptions f renames all options with the given functions.
--   In case the function returns Nothing the original field name
--   is used.
--   
--   Can be used together with stripPrefix.
RenameOptions :: (String -> Maybe String) -> Modifier

-- | UseForPositionalArguments fieldName argumentType fills the
--   field addressed by fieldName with the positional arguments
--   (i.e. arguments that don't correspond to a flag). The field has to
--   have type [String].
--   
--   argumentType is used as the type of the positional arguments
--   in the help output.
UseForPositionalArguments :: String -> String -> Modifier

-- | AddOptionHelp fieldName helpText adds a help text for the
--   option fieldName.
AddOptionHelp :: String -> String -> Modifier

-- | AddVersionFlag version adds a --version flag.
AddVersionFlag :: String -> Modifier

-- | Representable types of kind *. This class is derivable in GHC
--   with the DeriveGeneric flag on.
--   
--   A Generic instance must satisfy the following laws:
--   
--   
--   from . to ≡ id
--   to . from ≡ id
--   
class Generic a

-- | The class Typeable allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | Proxy is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, Proxy :: Proxy a is a safer
--   alternative to the undefined :: a idiom.
--   
--   
--   >>> Proxy :: Proxy (Void, Int -> Int)
--   Proxy
--   
--   
--   Proxy can even hold types of higher kinds,
--   
--   
--   >>> Proxy :: Proxy Either
--   Proxy
--   
--   
--   
--   >>> Proxy :: Proxy Functor
--   Proxy
--   
--   
--   
--   >>> Proxy :: Proxy complicatedStructure
--   Proxy
--   
data Proxy (t :: k)
Proxy :: Proxy (t :: k)

module WithCli

-- | withCli converts an IO operation into a program with a proper
--   CLI. Retrieves command line arguments through withArgs.
--   main (the given IO operation) can have arbitrarily many
--   parameters provided all parameters have instances for
--   HasArguments.
--   
--   May throw the following exceptions:
--   
--   
--   
- ExitFailure 1 in case of invalid options. Error
--   messages are written to stderr.
--   
- ExitSuccess in case --help is given.
--   (ExitSuccess behaves like a normal exception, except
--   that -- if uncaught -- the process will exit with exit-code
--   0.) Help output is written to stdout.
--   
--   
--   Example:
--   
--   
--   import WithCli
--   
--   main :: IO ()
--   main = withCli run
--   
--   run :: String -> Int -> Bool -> IO ()
--   run s i b = print (s, i, b)
--   
--   
--   Using the above program in a shell:
--   
--   
--   $ program foo 42 true
--   ("foo",42,True)
--   $ program --help
--   program [OPTIONS] STRING INTEGER BOOL
--     -h  --help  show help and exit
--   $ program foo 42 bar
--   cannot parse as BOOL: bar
--   # exit-code 1
--   $ program
--   missing argument of type STRING
--   missing argument of type INTEGER
--   missing argument of type BOOL
--   # exit-code 1
--   $ program foo 42 yes bar
--   unknown argument: bar
--   # exit-code 1
--   
withCli :: WithCli main => main -> IO ()

-- | Everything that can be used as a main function with
--   withCli needs to have an instance of WithCli. You
--   shouldn't need to implement your own instances.
class WithCli main

-- | Everything that can be used as an argument to your main
--   function (see withCli) needs to have a HasArguments
--   instance.
--   
--   HasArguments also allows to conjure up instances for record
--   types to create more complex command line interfaces. Here's an
--   example:
--   
--   
--   {-# LANGUAGE DeriveAnyClass #-}
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import WithCli
--   
--   data Options
--     = Options {
--       port :: Int,
--       daemonize :: Bool,
--       config :: Maybe FilePath
--     }
--     deriving (Show, Generic, HasArguments)
--   
--   main :: IO ()
--   main = withCli run
--   
--   run :: Options -> IO ()
--   run = print
--   
--   
--   In a shell this program behaves like this:
--   
--   
--   $ program --port 8080 --config some/path
--   Options {port = 8080, daemonize = False, config = Just "some/path"}
--   $ program  --port 8080 --daemonize
--   Options {port = 8080, daemonize = True, config = Nothing}
--   $ program --port foo
--   cannot parse as INTEGER: foo
--   # exit-code 1
--   $ program
--   missing option: --port=INTEGER
--   # exit-code 1
--   $ program --help
--   program [OPTIONS]
--         --port=INTEGER
--         --daemonize
--         --config=STRING (optional)
--     -h  --help                      show help and exit
--   
class HasArguments a
argumentsParser :: HasArguments a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)
($dmargumentsParser) :: (HasArguments a, Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | Useful for implementing your own instances of HasArguments on
--   top of a custom Argument instance.
atomicArgumentsParser :: Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | Argument is a typeclass for things that can be parsed as atomic
--   values from single command line arguments, e.g. strings (and
--   filenames) and numbers.
--   
--   Occasionally you might want to declare your own instance for
--   additional type safety and for providing a more informative command
--   argument type. Here's an example:
--   
--   
--   {-# LANGUAGE DeriveDataTypeable #-}
--   
--   import WithCli
--   
--   data File = File FilePath
--     deriving (Show, Typeable)
--   
--   instance Argument File where
--     argumentType Proxy = "custom-file-type"
--     parseArgument f = Just (File f)
--   
--   instance HasArguments File where
--     argumentsParser = atomicArgumentsParser
--   
--   main :: IO ()
--   main = withCli run
--   
--   run :: File -> IO ()
--   run = print
--   
--   
--   And this is how the above program behaves:
--   
--   
--   $ program --help
--   program [OPTIONS] custom-file-type
--     -h  --help  show help and exit
--   $ program some/file
--   File "some/file"
--   
class Argument a
argumentType :: Argument a => Proxy a -> String
parseArgument :: Argument a => String -> Maybe a

-- | This is a variant of withCli that allows tweaking the generated
--   command line interface by providing a list of Modifiers.
withCliModified :: WithCli main => [Modifier] -> main -> IO ()

-- | Modifiers can be used to customize the command line parser.
data Modifier

-- | AddShortOption fieldName c adds the Char c as
--   a short option for the field addressed by fieldName.
AddShortOption :: String -> Char -> Modifier

-- | RenameOption fieldName customName renames the option
--   generated through the fieldName by customName.
RenameOption :: String -> String -> Modifier

-- | RenameOptions f renames all options with the given functions.
--   In case the function returns Nothing the original field name
--   is used.
--   
--   Can be used together with stripPrefix.
RenameOptions :: (String -> Maybe String) -> Modifier

-- | UseForPositionalArguments fieldName argumentType fills the
--   field addressed by fieldName with the positional arguments
--   (i.e. arguments that don't correspond to a flag). The field has to
--   have type [String].
--   
--   argumentType is used as the type of the positional arguments
--   in the help output.
UseForPositionalArguments :: String -> String -> Modifier

-- | AddOptionHelp fieldName helpText adds a help text for the
--   option fieldName.
AddOptionHelp :: String -> String -> Modifier

-- | AddVersionFlag version adds a --version flag.
AddVersionFlag :: String -> Modifier

-- | Representable types of kind *. This class is derivable in GHC
--   with the DeriveGeneric flag on.
--   
--   A Generic instance must satisfy the following laws:
--   
--   
--   from . to ≡ id
--   to . from ≡ id
--   
class Generic a

-- | The class Typeable allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | Proxy is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, Proxy :: Proxy a is a safer
--   alternative to the undefined :: a idiom.
--   
--   
--   >>> Proxy :: Proxy (Void, Int -> Int)
--   Proxy
--   
--   
--   Proxy can even hold types of higher kinds,
--   
--   
--   >>> Proxy :: Proxy Either
--   Proxy
--   
--   
--   
--   >>> Proxy :: Proxy Functor
--   Proxy
--   
--   
--   
--   >>> Proxy :: Proxy complicatedStructure
--   Proxy
--   
data Proxy (t :: k)
Proxy :: Proxy (t :: k)
instance (WithCli.HasArguments.HasArguments a, WithCli.WithCli rest) => WithCli.WithCli (a -> rest)
instance WithCli.WithCli (GHC.Types.IO ())
