Safe Haskell | None |
---|---|
Language | Haskell2010 |
getopt-generics
tries to make it very simple to create command line
argument parsers. An introductory example can be found in the
README.
- getArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => IO a
- modifiedGetArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => [Modifier] -> IO a
- parseArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => String -> [Modifier] -> [String] -> Result a
- data Result a
- = Success a
- | Errors [String]
- | OutputAndExit String
- data Modifier
- deriveShortOptions :: (HasDatatypeInfo a, SingI (Code a)) => Proxy a -> [Modifier]
- class Typeable a => Option a where
- argumentType :: Proxy a -> String
- parseArgument :: String -> Maybe a
- _toOption :: ArgDescr (FieldState a)
- _emptyOption :: String -> FieldState a
- _accumulate :: a -> a -> a
- class (SingI [[*]] (Code a), All [*] (SingI [*]) (Code a)) => Generic a
- class HasDatatypeInfo a
- data Proxy t :: k -> * = Proxy
IO API
getArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => IO a Source
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:
in case of invalid options. Error messages are written toExitFailure
1stderr
.
in caseExitSuccess
--help
is given. (
behaves like a normal exception, except that -- if uncaught -- the process will exit with exit-codeExitSuccess
0
.) Help output is written tostdout
.
modifiedGetArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => [Modifier] -> IO a Source
Like getArguments
but allows you to pass in Modifier
s.
Pure API
:: (Generic a, HasDatatypeInfo a, All2 Option (Code a)) | |
=> String | Name of the program (e.g. from |
-> [Modifier] | List of |
-> [String] | List of command line arguments to parse (e.g. from |
-> Result a |
Pure variant of getArguments
.
Does not throw any exceptions.
Type to wrap results from the pure parsing functions.
Success a | The CLI was used correctly and a value of type |
Errors [String] | The CLI was used incorrectly. The 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 |
Customizing the CLI
Modifier
s can be used to customize the command line parser.
AddShortOption String Char |
|
RenameOption String String |
|
UseForPositionalArguments String String |
|
AddOptionHelp String String |
|
AddVersionFlag String |
|
deriveShortOptions :: (HasDatatypeInfo a, SingI (Code a)) => Proxy a -> [Modifier] Source
Derives AddShortOption
s for all fields of the datatype that start with a
unique character.
Available Field Types
class Typeable a => Option a where Source
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.
argumentType :: Proxy a -> String Source
Name of the argument type, e.g. "bool" or "integer".
parseArgument :: String -> Maybe a Source
_toOption :: ArgDescr (FieldState a) Source
This is meant to be an internal function.
_emptyOption :: String -> FieldState a Source
This is meant to be an internal function.
_accumulate :: a -> a -> a Source
This is meant to be an internal function.
Re-exports from Generics.SOP
class (SingI [[*]] (Code a), All [*] (SingI [*]) (Code a)) => Generic 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 -> afrom
.
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
, ...) instanceGeneric
T -- empty instanceHasDatatypeInfo
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 -- derivesHasDatatypeInfo
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.
Generic Bool | |
Generic Ordering | |
Generic () | |
Generic FormatAdjustment | |
Generic FormatSign | |
Generic FieldFormat | |
Generic FormatParse | |
Generic DataRep | |
Generic ConstrRep | |
Generic Fixity | |
Generic Version | |
Generic IOMode | |
Generic PatternMatchFail | |
Generic RecSelError | |
Generic RecConError | |
Generic RecUpdError | |
Generic NoMethodError | |
Generic NonTermination | |
Generic NestedAtomically | |
Generic Errno | |
Generic BlockedIndefinitelyOnMVar | |
Generic BlockedIndefinitelyOnSTM | |
Generic Deadlock | |
Generic AssertionFailed | |
Generic AsyncException | |
Generic ArrayException | |
Generic ExitCode | |
Generic BufferMode | |
Generic Newline | |
Generic NewlineMode | |
Generic SeekMode | |
Generic GeneralCategory | |
Generic CChar | |
Generic CSChar | |
Generic CUChar | |
Generic CShort | |
Generic CUShort | |
Generic CInt | |
Generic CUInt | |
Generic CLong | |
Generic CULong | |
Generic CLLong | |
Generic CULLong | |
Generic CFloat | |
Generic CDouble | |
Generic CPtrdiff | |
Generic CSize | |
Generic CWchar | |
Generic CSigAtomic | |
Generic CClock | |
Generic CTime | |
Generic CUSeconds | |
Generic CSUSeconds | |
Generic CIntPtr | |
Generic CUIntPtr | |
Generic CIntMax | |
Generic CUIntMax | |
Generic MaskingState | |
Generic IOException | |
Generic ErrorCall | |
Generic ArithException | |
Generic All | |
Generic Any | |
Generic Lexeme | |
Generic Number | |
Generic [a0] | |
Generic (ArgOrder a0) | |
Generic (OptDescr a0) | |
Generic (ArgDescr a0) | |
Generic (Fixed a0) | |
Generic (Complex a0) | |
Generic (Dual a0) | |
Generic (Endo a0) | |
Generic (Sum a0) | |
Generic (Product a0) | |
Generic (First a0) | |
Generic (Last a0) | |
Generic (Down a0) | |
Generic (Maybe a0) | |
Generic (I a0) | |
Generic (Either a0 b0) | |
Generic (a0, b0) | |
Generic (Proxy * t0) | |
Typeable (* -> Constraint) Generic | |
Generic (a0, b0, c0) | |
Generic (K * a0 b0) | |
Generic (a0, b0, c0, d0) | |
Generic (a0, b0, c0, d0, e0) | |
Generic ((:.:) * * f0 g0 p0) | |
Generic (a0, b0, c0, d0, e0, f0) | |
Generic (a0, b0, c0, d0, e0, f0, g0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0, y0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0, y0, z0) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0, y0, z0, t280) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0, y0, z0, t280, t290) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0, y0, z0, t280, t290, t300) | |
Generic (a0, b0, c0, d0, e0, f0, g0, h0, i0, j0, k0, l0, m0, n0, o0, p0, q0, r0, s0, t0, u0, v0, w0, x0, y0, z0, t280, t290, t300, t310) |
class HasDatatypeInfo 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.
data Proxy t :: k -> *
A concrete, poly-kinded proxy type
Monad (Proxy *) | |
Functor (Proxy *) | |
Applicative (Proxy *) | |
Foldable (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 * s) | |
Generic (Proxy * t0) | |
HasDatatypeInfo (Proxy * t0) | |
Typeable (k -> *) (Proxy k) | |
type Rep (Proxy k t) = D1 D1Proxy (C1 C1_0Proxy U1) | |
type Code (Proxy * t0) = (:) [*] ([] *) ([] [*]) |