WithCli.Pure

Documentation

withCliPure

Arguments

:: WithCliPure function a

=> String

-> [Modifier]

-> [String]

-> function

The function parameter can be a function with arbitrary many parameters as long as they have an instance for HasArguments. You can choose the return type of function freely, withCliPure will return it wrapped in Result to account for parse errors, etc. (see Result).

-> Result a

Pure variant of withCliModified.

class WithCliPure function output

Minimal complete definition

run

Instances

WithCliPure output output

(HasArguments input, WithCliPure function output) => WithCliPure (input -> function) output

data Result a

Type to wrap results from withCliPure.

Constructors

Success a

The CLI was used correctly and a value of type a was successfully constructed.

Errors String

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.

OutputAndExit String

The CLI was used with --help. The Result contains the help message.

Instances

Monad Result

Functor Result

Applicative Result

Eq a => Eq (Result a)

Ord a => Ord (Result a)

Show a => Show (Result a)

handleResult :: Result a -> IO 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.

class HasArguments a where

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)

Instances

HasArguments Bool

HasArguments Double

HasArguments Float

HasArguments Int

HasArguments String

Argument a => HasArguments [a]

Argument a => HasArguments (Maybe a)

(HasArguments a, HasArguments b) => HasArguments (a, b)

(HasArguments a, HasArguments b, HasArguments c) => HasArguments (a, b, c)

atomicArgumentsParser :: forall a. Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

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

class Argument a where

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

parseArgument :: String -> Maybe a

Instances

Argument Double

Argument Float

Argument Int

Argument Integer

Argument String

Modifiers

data Modifier

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

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

Minimal complete definition

from, to

Instances

Generic Bool

Generic Char

Generic Double

Generic Float

Generic Int

Generic Ordering

Generic ()

Generic All

Generic Any

Generic Arity

Generic Fixity

Generic Associativity

Generic [a]

Generic (U1 p)

Generic (Par1 p)

Generic (ZipList a)

Generic (Dual a)

Generic (Endo a)

Generic (Sum a)

Generic (Product a)

Generic (First a)

Generic (Last a)

Generic (Maybe a)

Generic (I a)

Generic (Either a b)

Generic (Rec1 f p)

Generic (a, b)

Generic (Const a b)

Generic (WrappedMonad m a)

Generic (Proxy * t)

Generic (K1 i c p)

Generic ((:+:) f g p)

Generic ((:*:) f g p)

Generic ((:.:) f g p)

Generic (a, b, c)

Generic (WrappedArrow a b c)

Generic (Alt k f a)

Generic (K k a b)

Generic (M1 i c f p)

Generic (a, b, c, d)

Generic (a, b, c, d, e)

Generic ((:.:) l k f g p)

Generic (a, b, c, d, e, f)

Generic (a, b, c, d, e, f, g)

class Typeable a

The class Typeable allows a concrete representation of a type to be calculated.

Minimal complete definition

typeRep#

data Proxy t :: k -> *

A concrete, poly-kinded proxy type

Constructors

Proxy

Instances

Monad (Proxy *)

Functor (Proxy *)

Applicative (Proxy *)

Foldable (Proxy *)

Traversable (Proxy *)

Bounded (Proxy k s)

Enum (Proxy k s)

Eq (Proxy k s)

Data t => Data (Proxy * t)

Ord (Proxy k s)

Read (Proxy k s)

Show (Proxy k s)

Ix (Proxy k s)

Generic (Proxy * t)

Monoid (Proxy k s)

type Rep (Proxy k t) = D1 D1Proxy (C1 C1_0Proxy U1)

type Code (Proxy * t0) = (:) [*] ([] *) ([] [*])