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


-- | Create command line interfaces with ease
--   
--   Create command line interfaces with ease
@package getopt-generics
@version 0.13.0.3

module WithCli.Pure

-- | Pure variant of <a>withCliModified</a>.
withCliPure :: WithCliPure function a => String -> [Modifier] -> [String] -> function -> Result a
class WithCliPure function output

-- | Type to wrap results from <a>withCliPure</a>.
data Result a

-- | The CLI was used correctly and a value of type <tt>a</tt> was
--   successfully constructed.
Success :: a -> Result a

-- | The CLI was used incorrectly. The <a>Result</a> contains error
--   messages.
--   
--   It can also happen that the data type you're trying to use isn't
--   supported. See the <a>README</a> for details.
Errors :: String -> Result a

-- | The CLI was used with <tt>--help</tt>. The <a>Result</a> contains the
--   help message.
OutputAndExit :: String -> Result a

-- | Handles an input of type <tt><a>Result</a> a</tt>:
--   
--   <ul>
--   <li>On <tt><a>Success</a> a</tt> it returns the value <tt>a</tt>.</li>
--   <li>On <tt><a>OutputAndExit</a> message</tt> it writes the message to
--   <a>stdout</a> and throws <a>ExitSuccess</a>.</li>
--   <li>On <tt><a>Errors</a> errs</tt> it writes the error messages to
--   <a>stderr</a> and throws <tt><a>ExitFailure</a> 1</tt>.</li>
--   </ul>
--   
--   This is used by <a>withCli</a> to handle parse results.
handleResult :: Result a -> IO a

-- | Everything that can be used as an argument to your <tt>main</tt>
--   function (see <tt>withCli</tt>) needs to have a <a>HasArguments</a>
--   instance.
--   
--   <a>HasArguments</a> also allows to conjure up instances for record
--   types to create more complex command line interfaces. Here's an
--   example:
--   
--   <pre>
--   {-# 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 -&gt; IO ()
--   run = print
--   </pre>
--   
--   In a shell this program behaves like this:
--   
--   <pre>
--   $ 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
--   </pre>
class HasArguments a
argumentsParser :: HasArguments a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)
argumentsParser :: (HasArguments a, Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | Useful for implementing your own instances of <a>HasArguments</a> on
--   top of a custom <a>Argument</a> instance.
atomicArgumentsParser :: forall a. Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | <a>Argument</a> 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:
--   
--   <pre>
--   {-# 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 -&gt; IO ()
--   run = print
--   </pre>
--   
--   And this is how the above program behaves:
--   
--   <pre>
--   $ program --help
--   program [OPTIONS] custom-file-type
--     -h  --help  show help and exit
--   $ program some/file
--   File "some/file"
--   </pre>
class Argument a
argumentType :: Argument a => Proxy a -> String
parseArgument :: Argument a => String -> Maybe a

-- | <a>Modifier</a>s can be used to customize the command line parser.
data Modifier

-- | <tt>AddShortOption fieldName c</tt> adds the <a>Char</a> <tt>c</tt> as
--   a short option for the field addressed by <tt>fieldName</tt>.
AddShortOption :: String -> Char -> Modifier

-- | <tt>RenameOption fieldName customName</tt> renames the option
--   generated through the <tt>fieldName</tt> by <tt>customName</tt>.
RenameOption :: String -> String -> Modifier

-- | <tt>RenameOptions f</tt> renames all options with the given functions.
--   In case the function returns <tt>Nothing</tt> the original field name
--   is used.
--   
--   Can be used together with <a>stripPrefix</a>.
RenameOptions :: (String -> Maybe String) -> Modifier

-- | <tt>UseForPositionalArguments fieldName argumentType</tt> fills the
--   field addressed by <tt>fieldName</tt> with the positional arguments
--   (i.e. arguments that don't correspond to a flag). The field has to
--   have type <tt>[<a>String</a>]</tt>.
--   
--   <tt>argumentType</tt> is used as the type of the positional arguments
--   in the help output.
UseForPositionalArguments :: String -> String -> Modifier

-- | <tt>AddOptionHelp fieldName helpText</tt> adds a help text for the
--   option <tt>fieldName</tt>.
AddOptionHelp :: String -> String -> Modifier

-- | <tt>AddVersionFlag version</tt> adds a <tt>--version</tt> flag.
AddVersionFlag :: String -> Modifier

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <tt>id</tt>
--   <a>to</a> . <a>from</a> ≡ <tt>id</tt>
--   </pre>
class Generic a

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | <a>Proxy</a> is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, <tt><a>Proxy</a> :: <a>Proxy</a> a</tt> is a safer
--   alternative to the <tt>'undefined :: a'</tt> idiom.
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy (Void, Int -&gt; Int)
--   Proxy
--   </pre>
--   
--   Proxy can even hold types of higher kinds,
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Either
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Functor
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy complicatedStructure
--   Proxy
--   </pre>
data Proxy (t :: k) :: forall k. () => k -> Type
Proxy :: Proxy

module WithCli

-- | <a>withCli</a> converts an IO operation into a program with a proper
--   CLI. Retrieves command line arguments through <a>withArgs</a>.
--   <tt>main</tt> (the given IO operation) can have arbitrarily many
--   parameters provided all parameters have instances for
--   <a>HasArguments</a>.
--   
--   May throw the following exceptions:
--   
--   <ul>
--   <li><tt><tt>ExitFailure</tt> 1</tt> in case of invalid options. Error
--   messages are written to <tt>stderr</tt>.</li>
--   <li><tt><tt>ExitSuccess</tt></tt> in case <tt>--help</tt> is given.
--   (<tt><tt>ExitSuccess</tt></tt> behaves like a normal exception, except
--   that -- if uncaught -- the process will exit with exit-code
--   <tt>0</tt>.) Help output is written to <tt>stdout</tt>.</li>
--   </ul>
--   
--   Example:
--   
--   <pre>
--   import WithCli
--   
--   main :: IO ()
--   main = withCli run
--   
--   run :: String -&gt; Int -&gt; Bool -&gt; IO ()
--   run s i b = print (s, i, b)
--   </pre>
--   
--   Using the above program in a shell:
--   
--   <pre>
--   $ 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
--   </pre>
withCli :: WithCli main => main -> IO ()

-- | Everything that can be used as a <tt>main</tt> function with
--   <a>withCli</a> needs to have an instance of <a>WithCli</a>. You
--   shouldn't need to implement your own instances.
class WithCli main

-- | Everything that can be used as an argument to your <tt>main</tt>
--   function (see <tt>withCli</tt>) needs to have a <a>HasArguments</a>
--   instance.
--   
--   <a>HasArguments</a> also allows to conjure up instances for record
--   types to create more complex command line interfaces. Here's an
--   example:
--   
--   <pre>
--   {-# 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 -&gt; IO ()
--   run = print
--   </pre>
--   
--   In a shell this program behaves like this:
--   
--   <pre>
--   $ 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
--   </pre>
class HasArguments a
argumentsParser :: HasArguments a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)
argumentsParser :: (HasArguments a, Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | Useful for implementing your own instances of <a>HasArguments</a> on
--   top of a custom <a>Argument</a> instance.
atomicArgumentsParser :: forall a. Argument a => Modifiers -> Maybe String -> Result (Parser Unnormalized a)

-- | <a>Argument</a> 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:
--   
--   <pre>
--   {-# 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 -&gt; IO ()
--   run = print
--   </pre>
--   
--   And this is how the above program behaves:
--   
--   <pre>
--   $ program --help
--   program [OPTIONS] custom-file-type
--     -h  --help  show help and exit
--   $ program some/file
--   File "some/file"
--   </pre>
class Argument a
argumentType :: Argument a => Proxy a -> String
parseArgument :: Argument a => String -> Maybe a

-- | This is a variant of <a>withCli</a> that allows to tweak the generated
--   command line interface by providing a list of <a>Modifier</a>s.
withCliModified :: WithCli main => [Modifier] -> main -> IO ()

-- | <a>Modifier</a>s can be used to customize the command line parser.
data Modifier

-- | <tt>AddShortOption fieldName c</tt> adds the <a>Char</a> <tt>c</tt> as
--   a short option for the field addressed by <tt>fieldName</tt>.
AddShortOption :: String -> Char -> Modifier

-- | <tt>RenameOption fieldName customName</tt> renames the option
--   generated through the <tt>fieldName</tt> by <tt>customName</tt>.
RenameOption :: String -> String -> Modifier

-- | <tt>RenameOptions f</tt> renames all options with the given functions.
--   In case the function returns <tt>Nothing</tt> the original field name
--   is used.
--   
--   Can be used together with <a>stripPrefix</a>.
RenameOptions :: (String -> Maybe String) -> Modifier

-- | <tt>UseForPositionalArguments fieldName argumentType</tt> fills the
--   field addressed by <tt>fieldName</tt> with the positional arguments
--   (i.e. arguments that don't correspond to a flag). The field has to
--   have type <tt>[<a>String</a>]</tt>.
--   
--   <tt>argumentType</tt> is used as the type of the positional arguments
--   in the help output.
UseForPositionalArguments :: String -> String -> Modifier

-- | <tt>AddOptionHelp fieldName helpText</tt> adds a help text for the
--   option <tt>fieldName</tt>.
AddOptionHelp :: String -> String -> Modifier

-- | <tt>AddVersionFlag version</tt> adds a <tt>--version</tt> flag.
AddVersionFlag :: String -> Modifier

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <tt>id</tt>
--   <a>to</a> . <a>from</a> ≡ <tt>id</tt>
--   </pre>
class Generic a

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | <a>Proxy</a> is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, <tt><a>Proxy</a> :: <a>Proxy</a> a</tt> is a safer
--   alternative to the <tt>'undefined :: a'</tt> idiom.
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy (Void, Int -&gt; Int)
--   Proxy
--   </pre>
--   
--   Proxy can even hold types of higher kinds,
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Either
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Functor
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy complicatedStructure
--   Proxy
--   </pre>
data Proxy (t :: k) :: forall k. () => k -> Type
Proxy :: Proxy
instance WithCli.WithCli (GHC.Types.IO ())
instance (WithCli.HasArguments.HasArguments a, WithCli.WithCli rest) => WithCli.WithCli (a -> rest)
