-- 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
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:
--
--
--
-- 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 where argumentsParser = const . genericParser
argumentsParser :: HasArguments 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.
class Generic a
-- | The class Typeable allows a concrete representation of a type
-- to be calculated.
class Typeable (a :: k)
-- | A concrete, poly-kinded proxy type
data Proxy (t :: k) :: k -> *
Proxy :: Proxy
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 where argumentsParser = const . genericParser
argumentsParser :: HasArguments 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 to tweak 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.
class Generic a
-- | The class Typeable allows a concrete representation of a type
-- to be calculated.
class Typeable (a :: k)
-- | A concrete, poly-kinded proxy type
data Proxy (t :: k) :: k -> *
Proxy :: Proxy
instance WithCli.WithCli (GHC.Types.IO ())
instance (WithCli.HasArguments.HasArguments a, WithCli.WithCli rest) => WithCli.WithCli (a -> rest)