-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Auto-generate a command-line parser for your datatype
--   
--   This library auto-generates an
--   <tt>optparse-applicative</tt>-compatible <tt>Parser</tt> from any data
--   type that derives the <tt>Generic</tt> interface.
--   
--   See the documentation in <a>Options.Generic</a> for an example of how
--   to use this library
@package optparse-generic
@version 1.1.1


-- | This library auto-generates command-line parsers for data types using
--   Haskell's built-in support for generic programming. The best way to
--   understand how this library works is to walk through a few examples.
--   
--   For example, suppose that you want to parse a record with named fields
--   like this:
--   
--   <pre>
--   -- Example.hs
--   
--   {-# LANGUAGE DeriveGeneric     #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Options.Generic
--   
--   data Example = Example { foo :: Int, bar :: Double }
--       deriving (Generic, Show)
--   
--   instance ParseRecord Example
--   
--   main = do
--       x &lt;- getRecord "Test program"
--       print (x :: Example)
--   </pre>
--   
--   Named fields translate to flags which you can provide in any order:
--   
--   <pre>
--   $ stack build optparse-generic
--   $ stack runghc Example.hs -- --bar 2.5 --foo 1
--   Example {foo = 1, bar = 2.5}
--   </pre>
--   
--   This also auto-generates <tt>--help</tt> output:
--   
--   <pre>
--   $ stack runghc Example.hs -- --help
--   Test program
--   
--   Usage: Example.hs --foo INT --bar DOUBLE
--   
--   Available options:
--     -h,--help                Show this help text
--   </pre>
--   
--   You can also add help descriptions to each field, like this:
--   
--   <pre>
--   {-# LANGUAGE DataKinds         #-}
--   {-# LANGUAGE DeriveGeneric     #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE TypeOperators     #-}
--   
--   import Options.Generic
--   
--   data Example = Example
--       { foo :: Int    &lt;?&gt; "Documentation for the foo flag"
--       , bar :: Double &lt;?&gt; "Documentation for the bar flag"
--       } deriving (Generic, Show)
--   
--   instance ParseRecord Example
--   
--   main = do
--       x &lt;- getRecord "Test program"
--       print (x :: Example)
--   </pre>
--   
--   ... which produces the following <tt>--help</tt> output:
--   
--   <pre>
--   $ stack runghc Example.hs -- --help
--   Test program
--   
--   Usage: Example.hs --foo INT --bar DOUBLE
--   
--   Available options:
--     -h,--help                Show this help text
--     --foo INT                Documentation for the foo flag
--     --bar DOUBLE             Documentation for the bar flag
--   </pre>
--   
--   However, any fields you document will be wrapped in the <a>Helpful</a>
--   constructor:
--   
--   <pre>
--   $ stack runghc Example.hs -- --foo 1 --bar 2.5
--   Example {foo = Helpful {unHelpful = 1}, bar = Helpful {unHelpful = 2.5}}
--   </pre>
--   
--   For the following examples I encourage you to test what
--   <tt>--help</tt> output they generate.
--   
--   This library will also do the right thing if the fields have no
--   labels:
--   
--   <pre>
--   data Example = Example Int Double deriving (Generic, Show)
--   </pre>
--   
--   Fields without labels translate into positional command-line
--   arguments:
--   
--   <pre>
--   $ stack runghc Example.hs -- 1 2.5
--   Example 1 2.5
--   </pre>
--   
--   Certain types of fields are given special treatment, such as in this
--   example:
--   
--   <pre>
--   data Example = Example
--       { switch   :: Bool
--       , list     :: [Int]
--       , optional :: Maybe   Int
--       , first    :: First   Int
--       , last     :: Last    Int
--       , sum      :: Sum     Int
--       , product  :: Product Int
--       } deriving (Generic, Show)
--   </pre>
--   
--   This gives the following behavior:
--   
--   <pre>
--   $ stack runghc Example.hs --
--         --switch
--         --optional 1
--         --list    1 --list    2
--         --first   1 --first   2
--         --last    1 --last    2
--         --sum     1 --sum     2
--         --product 1 --product 2
--   Example {switch = True, list = [1,2], optional = Just 1, first = First 
--   {getFirst = Just 1}, last = Last {getLast = Just 2}, sum = Sum {getSum =
--   3}, product = Product {getProduct = 2}}
--   
--   $ stack runghc Example.hs
--   Example {switch = False, list = [], optional = Nothing, first = First
--   {getFirst = Nothing}, second = Last {getLast = Nothing}, sum = Sum {getSum
--   = 0}, product = Product {getProduct = 1}}
--   </pre>
--   
--   If a datatype has multiple constructors:
--   
--   <pre>
--   data Example
--       = Create { name :: Text, duration :: Maybe Int }
--       | Kill   { name :: Text }
--       deriving (Generic, Show)
--   </pre>
--   
--   ... then they will translate into subcommands named after each
--   constructor:
--   
--   <pre>
--   $ stack runghc Example.hs -- create --name foo --duration=60
--   Create {name = "foo", duration = Just 60}
--   $ stack runghc Example.hs -- kill --name foo
--   Kill {name = "foo"}
--   </pre>
--   
--   This library also provides out-of-the-box support for many existing
--   types, like tuples and <a>Either</a>.
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric     #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Options.Generic
--   
--   main = do
--       x &lt;- getRecord "Test program"
--       print (x :: Either Double Int)
--   </pre>
--   
--   <pre>
--   $ stack runghc Example.hs -- left 1.0
--   Left 1.0
--   $ stack runghc Example.hs -- right 2
--   Right 2
--   </pre>
--   
--   <pre>
--   main = do
--       x &lt;- getRecord "Test program"
--       print (x :: (Double, Int))
--   </pre>
--   
--   <pre>
--   $ stack runghc Example.hs -- 1.0 2
--   (1.0,2)
--   </pre>
--   
--   ... and you can also just parse a single value:
--   
--   <pre>
--   main = do
--       x &lt;- getRecord "Test program"
--       print (x :: Int)
--   </pre>
--   
--   <pre>
--   $ stack runghc Example.hs -- 2
--   2
--   </pre>
--   
--   However, there are some types that this library cannot generate
--   sensible command-line parsers for, such as:
--   
--   <ul>
--   <li>recursive types:<pre>data Example = Example { foo :: Example
--   }</pre></li>
--   <li>records whose fields are other records<pre>data Outer = Outer {
--   foo :: Inner } deriving (Show, Generic) data Inner = Inner { bar ::
--   Int } deriving (Show, Generic)</pre></li>
--   <li>record fields with nested <a>Maybe</a>s or nested lists<pre>data
--   Example = Example { foo :: Maybe (Maybe Int) } data Example = Example
--   { foo :: [[Int]] }</pre></li>
--   </ul>
--   
--   If you try to auto-generate a parser for these types you will get an
--   error at compile time that will look something like this:
--   
--   <pre>
--   No instance for (ParseFields TheTypeOfYourField)
--     arising from a use of ‘Options.Generic.$gdmparseRecord’
--   In the expression: Options.Generic.$gdmparseRecord
--   In an equation for ‘parseRecord’:
--       parseRecord = Options.Generic.$gdmparseRecord
--   In the instance declaration for ‘ParseRecord TheTypeOfYourRecord’
--   </pre>
module Options.Generic

-- | Marshal any value that implements <a>ParseRecord</a> from the command
--   line
getRecord :: (MonadIO io, ParseRecord a) => Text -> io a

-- | Pure version of <a>getRecord</a>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; getRecordPure ["1"] :: Maybe Int
--   Just 1
--   
--   &gt;&gt;&gt; getRecordPure ["1", "2"] :: Maybe [Int]
--   Just [1,2]
--   
--   &gt;&gt;&gt; getRecordPure ["Foo"] :: Maybe Int
--   Nothing
--   </pre>
getRecordPure :: ParseRecord a => [Text] -> Maybe a

-- | A class for types that can be parsed from the command line
--   
--   This class has a default implementation for any type that implements
--   <a>Generic</a> and you can derive <a>Generic</a> for many types by
--   enabling the <tt>DeriveGeneric</tt> language extension
--   
--   You can also use <a>getOnly</a> to create a <a>ParseRecord</a>
--   instance from a <a>ParseFields</a> instance:
--   
--   <pre>
--   instance ParseRecord MyType where
--       parseRecord = fmap getOnly parseRecord
--   </pre>
class ParseRecord a where parseRecord = fmap to (genericParseRecord defaultModifiers)
parseRecord :: ParseRecord a => Parser a
parseRecord :: (ParseRecord a, Generic a, GenericParseRecord (Rep a)) => Parser a

-- | A class for all types that can be parsed from zero or more
--   arguments/options on the command line
--   
--   <a>parseFields</a> has a default implementation for any type that
--   implements <a>ParseField</a>
class ParseRecord a => ParseFields a where parseFields = parseField
parseFields :: ParseFields a => Maybe Text -> Maybe Text -> Parser a
parseFields :: (ParseFields a, ParseField a) => Maybe Text -> Maybe Text -> Parser a

-- | A class for all record fields that can be parsed from exactly one
--   option or argument on the command line
--   
--   <a>parseField</a> has a default implementation for any type that
--   implements <a>Read</a> and <a>Typeable</a>. You can derive <a>Read</a>
--   for many types and you can derive <a>Typeable</a> for any type if you
--   enable the <tt>DeriveDataTypeable</tt> language extension
class ParseField a where parseField h m = do { let metavar = map toUpper (show (typeOf (undefined :: a))); case m of { Nothing -> do { let fs = metavar metavar <> maybe mempty (help . unpack) h; argument auto fs } Just name -> do { let fs = metavar metavar <> long (unpack name) <> maybe mempty (help . unpack) h; option auto fs } } } parseListOfField h m = many (parseField h m)
parseField :: ParseField a => Maybe Text -> Maybe Text -> Parser a
parseField :: (ParseField a, Typeable a, Read a) => Maybe Text -> Maybe Text -> Parser a

-- | The only reason for this method is to provide a special case for
--   handling <a>String</a>s. All other instances should just fall back on
--   the default implementation for <a>parseListOfField</a>
parseListOfField :: ParseField a => Maybe Text -> Maybe Text -> Parser [a]

-- | A 1-tuple, used solely to translate <a>ParseFields</a> instances into
--   <a>ParseRecord</a> instances
newtype Only a
Only :: a -> Only a

-- | This is a convenience function that you can use if you want to create
--   a <a>ParseRecord</a> instance that just defers to the
--   <a>ParseFields</a> instance for the same type:
--   
--   <pre>
--   instance ParseRecord MyType where
--       parseRecord = fmap getOnly parseRecord
--   </pre>
getOnly :: Only a -> a
data Modifiers
Modifiers :: (String -> String) -> (String -> String) -> Modifiers
[fieldNameModifier] :: Modifiers -> String -> String
[constructorNameModifier] :: Modifiers -> String -> String
parseRecordWithModifiers :: (Generic a, GenericParseRecord (Rep a)) => Modifiers -> Parser a
defaultModifiers :: Modifiers

-- | Use this to annotate a field with a type-level string (i.e. a
--   <a>Symbol</a>) representing the help description for that field:
--   
--   <pre>
--   data Example = Example
--       { foo :: Int    &lt;?&gt; "Documentation for the foo flag"
--       , bar :: Double &lt;?&gt; "Documentation for the bar flag"
--       } deriving (Generic, Show)
--   </pre>
newtype (<?>) (field :: *) (help :: Symbol)
Helpful :: field -> (<?>)
[unHelpful] :: (<?>) -> field

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

-- | A space efficient, packed, unboxed Unicode text type.
data Text :: *

-- | Boolean monoid under conjunction (<a>&amp;&amp;</a>).
newtype All :: *
All :: Bool -> All
[getAll] :: All -> Bool

-- | Boolean monoid under disjunction (<a>||</a>).
newtype Any :: *
Any :: Bool -> Any
[getAny] :: Any -> Bool

-- | Maybe monoid returning the leftmost non-Nothing value.
--   
--   <tt><a>First</a> a</tt> is isomorphic to <tt><a>Alt</a> <a>Maybe</a>
--   a</tt>, but precedes it historically.
newtype First a :: * -> *
First :: Maybe a -> First a
[getFirst] :: First a -> Maybe a

-- | Maybe monoid returning the rightmost non-Nothing value.
--   
--   <tt><a>Last</a> a</tt> is isomorphic to <tt><a>Dual</a> (<a>First</a>
--   a)</tt>, and thus to <tt><a>Dual</a> (<a>Alt</a> <a>Maybe</a> a)</tt>
newtype Last a :: * -> *
Last :: Maybe a -> Last a
[getLast] :: Last a -> Maybe a

-- | Monoid under addition.
newtype Sum a :: * -> *
Sum :: a -> Sum a
[getSum] :: Sum a -> a

-- | Monoid under multiplication.
newtype Product a :: * -> *
Product :: a -> Product a
[getProduct] :: Product a -> a
instance GHC.Show.Show a => GHC.Show.Show (Options.Generic.Only a)
instance GHC.Generics.Generic (Options.Generic.Only a)
instance GHC.Show.Show field => GHC.Show.Show (field Options.Generic.<?> help)
instance GHC.Generics.Generic (field Options.Generic.<?> help)
instance Options.Generic.ParseField GHC.Types.Bool
instance Options.Generic.ParseField GHC.Types.Double
instance Options.Generic.ParseField GHC.Types.Float
instance Options.Generic.ParseField GHC.Types.Int
instance Options.Generic.ParseField GHC.Integer.Type.Integer
instance Options.Generic.ParseField GHC.Types.Ordering
instance Options.Generic.ParseField ()
instance Options.Generic.ParseField Data.Void.Void
instance Options.Generic.ParseField GHC.Base.String
instance Options.Generic.ParseField GHC.Types.Char
instance Options.Generic.ParseField Data.Monoid.Any
instance Options.Generic.ParseField Data.Monoid.All
instance Options.Generic.ParseField Data.Text.Internal.Text
instance Options.Generic.ParseField Data.ByteString.Internal.ByteString
instance Options.Generic.ParseField Data.Text.Internal.Lazy.Text
instance Options.Generic.ParseField Data.ByteString.Lazy.Internal.ByteString
instance Options.Generic.ParseField Filesystem.Path.Internal.FilePath
instance Options.Generic.ParseField Data.Time.Calendar.Days.Day
instance Options.Generic.ParseFields GHC.Types.Char
instance Options.Generic.ParseFields GHC.Types.Double
instance Options.Generic.ParseFields GHC.Types.Float
instance Options.Generic.ParseFields GHC.Types.Int
instance Options.Generic.ParseFields GHC.Integer.Type.Integer
instance Options.Generic.ParseFields GHC.Types.Ordering
instance Options.Generic.ParseFields Data.Void.Void
instance Options.Generic.ParseFields Data.ByteString.Internal.ByteString
instance Options.Generic.ParseFields Data.ByteString.Lazy.Internal.ByteString
instance Options.Generic.ParseFields Data.Text.Internal.Text
instance Options.Generic.ParseFields Data.Text.Internal.Lazy.Text
instance Options.Generic.ParseFields Filesystem.Path.Internal.FilePath
instance Options.Generic.ParseFields Data.Time.Calendar.Days.Day
instance Options.Generic.ParseFields GHC.Types.Bool
instance Options.Generic.ParseFields ()
instance Options.Generic.ParseFields Data.Monoid.Any
instance Options.Generic.ParseFields Data.Monoid.All
instance Options.Generic.ParseField a => Options.Generic.ParseFields (GHC.Base.Maybe a)
instance Options.Generic.ParseField a => Options.Generic.ParseFields (Data.Monoid.First a)
instance Options.Generic.ParseField a => Options.Generic.ParseFields (Data.Monoid.Last a)
instance (GHC.Num.Num a, Options.Generic.ParseField a) => Options.Generic.ParseFields (Data.Monoid.Sum a)
instance (GHC.Num.Num a, Options.Generic.ParseField a) => Options.Generic.ParseFields (Data.Monoid.Product a)
instance Options.Generic.ParseField a => Options.Generic.ParseFields [a]
instance (Options.Generic.ParseField a, GHC.TypeLits.KnownSymbol h) => Options.Generic.ParseField (a Options.Generic.<?> h)
instance (Options.Generic.ParseFields a, GHC.TypeLits.KnownSymbol h) => Options.Generic.ParseFields (a Options.Generic.<?> h)
instance (Options.Generic.ParseFields a, GHC.TypeLits.KnownSymbol h) => Options.Generic.ParseRecord (a Options.Generic.<?> h)
instance Options.Generic.ParseFields a => Options.Generic.ParseRecord (Options.Generic.Only a)
instance Options.Generic.ParseRecord GHC.Types.Char
instance Options.Generic.ParseRecord GHC.Types.Double
instance Options.Generic.ParseRecord GHC.Types.Float
instance Options.Generic.ParseRecord GHC.Types.Int
instance Options.Generic.ParseRecord GHC.Types.Ordering
instance Options.Generic.ParseRecord Data.Void.Void
instance Options.Generic.ParseRecord ()
instance Options.Generic.ParseRecord GHC.Types.Bool
instance Options.Generic.ParseRecord GHC.Integer.Type.Integer
instance Options.Generic.ParseRecord Data.Text.Internal.Text
instance Options.Generic.ParseRecord Data.Text.Internal.Lazy.Text
instance Options.Generic.ParseRecord Data.Monoid.Any
instance Options.Generic.ParseRecord Data.Monoid.All
instance Options.Generic.ParseRecord Filesystem.Path.Internal.FilePath
instance Options.Generic.ParseRecord Data.ByteString.Internal.ByteString
instance Options.Generic.ParseRecord Data.ByteString.Lazy.Internal.ByteString
instance Options.Generic.ParseRecord Data.Time.Calendar.Days.Day
instance Options.Generic.ParseField a => Options.Generic.ParseRecord (GHC.Base.Maybe a)
instance Options.Generic.ParseField a => Options.Generic.ParseRecord (Data.Monoid.First a)
instance Options.Generic.ParseField a => Options.Generic.ParseRecord (Data.Monoid.Last a)
instance (GHC.Num.Num a, Options.Generic.ParseField a) => Options.Generic.ParseRecord (Data.Monoid.Sum a)
instance (GHC.Num.Num a, Options.Generic.ParseField a) => Options.Generic.ParseRecord (Data.Monoid.Product a)
instance Options.Generic.ParseField a => Options.Generic.ParseRecord [a]
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b) => Options.Generic.ParseRecord (a, b)
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b, Options.Generic.ParseFields c) => Options.Generic.ParseRecord (a, b, c)
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b, Options.Generic.ParseFields c, Options.Generic.ParseFields d) => Options.Generic.ParseRecord (a, b, c, d)
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b, Options.Generic.ParseFields c, Options.Generic.ParseFields d, Options.Generic.ParseFields e) => Options.Generic.ParseRecord (a, b, c, d, e)
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b, Options.Generic.ParseFields c, Options.Generic.ParseFields d, Options.Generic.ParseFields e, Options.Generic.ParseFields f) => Options.Generic.ParseRecord (a, b, c, d, e, f)
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b, Options.Generic.ParseFields c, Options.Generic.ParseFields d, Options.Generic.ParseFields e, Options.Generic.ParseFields f, Options.Generic.ParseFields g) => Options.Generic.ParseRecord (a, b, c, d, e, f, g)
instance (Options.Generic.ParseFields a, Options.Generic.ParseFields b) => Options.Generic.ParseRecord (Data.Either.Either a b)
instance Options.Generic.GenericParseRecord GHC.Generics.U1
instance Options.Generic.GenericParseRecord f => Options.Generic.GenericParseRecord (GHC.Generics.M1 GHC.Generics.C c f)
instance (Options.Generic.GenericParseRecord (f GHC.Generics.:+: g), Options.Generic.GenericParseRecord (h GHC.Generics.:+: i)) => Options.Generic.GenericParseRecord ((f GHC.Generics.:+: g) GHC.Generics.:+: (h GHC.Generics.:+: i))
instance (GHC.Generics.Constructor c, Options.Generic.GenericParseRecord f, Options.Generic.GenericParseRecord (g GHC.Generics.:+: h)) => Options.Generic.GenericParseRecord (GHC.Generics.M1 GHC.Generics.C c f GHC.Generics.:+: (g GHC.Generics.:+: h))
instance (GHC.Generics.Constructor c, Options.Generic.GenericParseRecord (f GHC.Generics.:+: g), Options.Generic.GenericParseRecord h) => Options.Generic.GenericParseRecord ((f GHC.Generics.:+: g) GHC.Generics.:+: GHC.Generics.M1 GHC.Generics.C c h)
instance (GHC.Generics.Constructor c1, GHC.Generics.Constructor c2, Options.Generic.GenericParseRecord f1, Options.Generic.GenericParseRecord f2) => Options.Generic.GenericParseRecord (GHC.Generics.M1 GHC.Generics.C c1 f1 GHC.Generics.:+: GHC.Generics.M1 GHC.Generics.C c2 f2)
instance (Options.Generic.GenericParseRecord f, Options.Generic.GenericParseRecord g) => Options.Generic.GenericParseRecord (f GHC.Generics.:*: g)
instance Options.Generic.GenericParseRecord GHC.Generics.V1
instance (GHC.Generics.Selector s, Options.Generic.ParseFields a) => Options.Generic.GenericParseRecord (GHC.Generics.M1 GHC.Generics.S s (GHC.Generics.K1 i a))
instance Options.Generic.GenericParseRecord f => Options.Generic.GenericParseRecord (GHC.Generics.M1 GHC.Generics.D c f)