Safe Haskell	None
Language	Haskell2010

WithCli

Contents

Modifiers
Useful Re-exports

Synopsis

withCli :: WithCli main => main -> IO ()
class WithCli main
class HasArguments a where
- argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized a)
atomicArgumentsParser :: Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)
class Argument a where
- argumentType :: Proxy a -> String
- parseArgument :: String -> Maybe a
withCliModified :: WithCli main => [Modifier] -> main -> IO ()
data Modifier
- = AddShortOption String Char
- | RenameOption String String
- | RenameOptions (String -> Maybe String)
- | UseForPositionalArguments String String
- | AddOptionHelp String String
- | AddVersionFlag String
class Generic a
class Typeable (a :: k)
data Proxy (t :: k) = Proxy

Documentation

withCli :: WithCli main => main -> IO () Source #

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

class WithCli main Source #

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.

Minimal complete definition

run

Instances

Instances details

WithCli (IO ()) Source #
Instance details Defined in WithCli Methods run :: Modifiers -> Result (Parser Unnormalized a) -> (a -> IO ()) -> [String] -> IO ()
(HasArguments a, WithCli rest) => WithCli (a -> rest) Source #
Instance details Defined in WithCli Methods run :: Modifiers -> Result (Parser Unnormalized a0) -> (a0 -> a -> rest) -> [String] -> IO ()

class HasArguments a where Source #

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

Minimal complete definition

Nothing

Methods

argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized a) Source #

default argumentsParser :: (Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => Modifiers -> Maybe String -> Result (Parser Unnormalized a) Source #

Instances

Instances details

HasArguments String Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized String) Source #
HasArguments Bool Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized Bool) Source #
HasArguments Double Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized Double) Source #
HasArguments Float Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized Float) Source #
HasArguments Int Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized Int) Source #
Argument a => HasArguments (Maybe a) Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized (Maybe a)) Source #
Argument a => HasArguments [a] Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized [a]) Source #
(HasArguments a, HasArguments b) => HasArguments (a, b) Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized (a, b)) Source #
(HasArguments a, HasArguments b, HasArguments c) => HasArguments (a, b, c) Source #
Instance details Defined in WithCli.HasArguments Methods argumentsParser :: Modifiers -> Maybe String -> Result (Parser Unnormalized (a, b, c)) Source #

atomicArgumentsParser :: Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a) Source #

Useful for implementing your own instances of HasArguments on top of a custom Argument instance.

class Argument a where Source #

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"

Methods

argumentType :: Proxy a -> String Source #

parseArgument :: String -> Maybe a Source #

Instances

Instances details

Argument Integer Source #
Instance details Defined in WithCli.Argument Methods argumentType :: Proxy Integer -> String Source # parseArgument :: String -> Maybe Integer Source #
Argument String Source #
Instance details Defined in WithCli.Argument Methods argumentType :: Proxy String -> String Source # parseArgument :: String -> Maybe String Source #
Argument Double Source #
Instance details Defined in WithCli.Argument Methods argumentType :: Proxy Double -> String Source # parseArgument :: String -> Maybe Double Source #
Argument Float Source #
Instance details Defined in WithCli.Argument Methods argumentType :: Proxy Float -> String Source # parseArgument :: String -> Maybe Float Source #
Argument Int Source #
Instance details Defined in WithCli.Argument Methods argumentType :: Proxy Int -> String Source # parseArgument :: String -> Maybe Int Source #

Modifiers

withCliModified :: WithCli main => [Modifier] -> main -> IO () Source #

This is a variant of withCli that allows tweaking the generated command line interface by providing a list of Modifiers.

data Modifier Source #

Modifiers can be used to customize the command line parser.

Constructors

AddShortOption String Char	`AddShortOption fieldName c` adds the `Char` `c` as a short option for the field addressed by `fieldName`.
RenameOption String String	`RenameOption fieldName customName` renames the option generated through the `fieldName` by `customName`.
RenameOptions (String -> Maybe String)	`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`.
UseForPositionalArguments String String	`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.
AddOptionHelp String String	`AddOptionHelp fieldName helpText` adds a help text for the option `fieldName`.
AddVersionFlag String	`AddVersionFlag version` adds a `--version` flag.

Useful Re-exports

class Generic a Source #

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

Minimal complete definition

from, to

Instances

Instances details

Generic Void

Instance details