-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Simple command line argument parsing
--
@package getopt-generics
@version 0.7
-- | getopt-generics tries to make it very simple to create
-- command line argument parsers. An introductory example can be found in
-- the README.
module System.Console.GetOpt.Generics
-- | Parses command line arguments (gotten from withArgs) and
-- returns the parsed value. This function should be enough for simple
-- use-cases.
--
-- 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.
--
getArguments :: (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => IO a
-- | Like getArguments but allows you to pass in Modifiers.
modifiedGetArguments :: (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => [Modifier] -> IO a
-- | Pure variant of getArguments.
--
-- Does not throw any exceptions.
parseArguments :: (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => String -> [Modifier] -> [String] -> Result a
-- | Type to wrap results from the pure parsing functions.
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 a list of
-- 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
-- | 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
-- | 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
-- | Derives AddShortOptions for all fields of the datatype that
-- start with a unique character.
deriveShortOptions :: (HasDatatypeInfo a, SingI (Code a)) => Proxy a -> [Modifier]
-- | Type class for all allowed field types.
--
-- If you want to use custom field types you should implement an
-- instance Option YourCustomType containing implementations of
-- argumentType and parseArgument (the minimal complete
-- definition). For an example see the README.
class Typeable a => Option a where _toOption = ReqArg parseAsFieldState (argumentType (Proxy :: Proxy a)) _emptyOption flagName = Unset ("missing option: --" ++ flagName ++ "=" ++ argumentType (Proxy :: Proxy a)) _accumulate _ x = x
argumentType :: Option a => Proxy a -> String
parseArgument :: Option a => String -> Maybe a
_toOption :: Option a => ArgDescr (FieldState a)
_emptyOption :: Option a => String -> FieldState a
_accumulate :: Option a => a -> a -> a
-- | The class of representable datatypes.
--
-- The SOP approach to generic programming is based on viewing datatypes
-- as a representation (Rep) built from the sum of products of its
-- components. The components of are datatype are specified using the
-- Code type family.
--
-- The isomorphism between the original Haskell datatype and its
-- representation is witnessed by the methods of this class, from
-- and to. So for instances of this class, the following laws
-- should (in general) hold:
--
--
-- to . from === id :: a -> a
-- from . to === id :: Rep a -> Rep a
--
--
-- You typically don't define instances of this class by hand, but rather
-- derive the class instance automatically.
--
-- Option 1: Derive via the built-in GHC-generics. For this, you
-- need to use the DeriveGeneric extension to first derive an
-- instance of the Generic class from module GHC.Generics.
-- With this, you can then give an empty instance for Generic, and
-- the default definitions will just work. The pattern looks as follows:
--
--
-- import qualified GHC.Generics as GHC
-- import Generics.SOP
--
-- ...
--
-- data T = ... deriving (GHC.Generic, ...)
--
-- instance Generic T -- empty
-- instance HasDatatypeInfo T -- empty, if you want/need metadata
--
--
-- Option 2: Derive via Template Haskell. For this, you need to
-- enable the TemplateHaskell extension. You can then use
-- deriveGeneric from module Generics.SOP.TH to have the
-- instance generated for you. The pattern looks as follows:
--
--
-- import Generics.SOP
-- import Generics.SOP.TH
--
-- ...
--
-- data T = ...
--
-- deriveGeneric ''T -- derives HasDatatypeInfo as well
--
--
-- Tradeoffs: Whether to use Option 1 or 2 is mainly a matter of
-- personal taste. The version based on Template Haskell probably has
-- less run-time overhead.
--
-- Non-standard instances: It is possible to give Generic
-- instances manually that deviate from the standard scheme, as long as
-- at least
--
--
-- to . from === id :: a -> a
--
--
-- still holds.
class (SingI [[*]] (Code a), All [*] (SingI [*]) (Code a)) => Generic a
-- | A class of datatypes that have associated metadata.
--
-- It is possible to use the sum-of-products approach to generic
-- programming without metadata. If you need metadata in a function, an
-- additional constraint on this class is in order.
--
-- You typically don't define instances of this class by hand, but rather
-- derive the class instance automatically. See the documentation of
-- Generic for the options.
class HasDatatypeInfo a
-- | A concrete, poly-kinded proxy type
data Proxy (t :: k) :: k -> *
Proxy :: Proxy
instance [overlap ok] Typeable FieldState
instance [overlap ok] Option Double
instance [overlap ok] Option Float
instance [overlap ok] Option Integer
instance [overlap ok] Option Int
instance [overlap ok] Option String
instance [overlap ok] Option Bool
instance [overlap ok] Option a => Option (Maybe a)
instance [overlap ok] Option a => Option [a]