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


-- | A modern command-line parser for Haskell.
--   
--   A modern command-line parser for Haskell.
@package lambda-options
@version 0.2.0.0

module Text.LambdaOptions

-- | A monad transformer for parsing options.
data Options m a

-- | An option keyword, such as <tt>"--help"</tt>
--   
--   NB: In the future, this will become a proper data type that contains a
--   list of aliases and help descriptions.
type Keyword = String

-- | The callback to be called for a successfully parsed option.
--   
--   This function (or value) can have any arity and ultimately returns a
--   value with type <tt>Monad m =&gt; m ()</tt>
--   
--   Each of the callback's arguments must have a type <tt>t</tt> which
--   implements <a>Parseable</a> and <a>Typeable</a>.
--   
--   Think of this as the following constraint synonym:
--   
--   <pre>
--   type OptionCallback m f = (Monad m, f ~ (Parseable t*, Typeable t*) =&gt; t0 -&gt; t1 -&gt; ... -&gt; tN -&gt; m ())
--   </pre>
--   
--   Example callbacks:
--   
--   <pre>
--   putStrLn "Option parsed!" :: IO ()
--   put :: String -&gt; State String ()
--   \n -&gt; liftIO (print n) :: (MonadIO m) =&gt; Int -&gt; m ()
--   \name year ratio -&gt; lift (print (name, year, ratio)) :: (MonadTrans m) =&gt; String -&gt; Int -&gt; Float -&gt; m IO ()
--   </pre>
type OptionCallback m f = (Monad m, GetOpaqueParsers f, WrapCallback m f)

-- | Adds the supplied option to the <tt>Options m ()</tt> context.
--   
--   If the keyword is matched and the types of the callback's parameters
--   can successfully be parsed, the callback is called with the parsed
--   arguments.
addOption :: OptionCallback m f => Keyword -> f -> Options m ()

-- | Contains information about what went wrong during an unsuccessful
--   options parse.
data OptionsError

-- | Contains <tt>(error-message)</tt> <tt>(begin-args-index)</tt>
--   <tt>(end-args-index)</tt>
ParseFailed :: String -> Int -> Int -> OptionsError

-- | Tries to parse the supplied options against input arguments. If
--   successful, parsed option callbacks are executed. Otherwise
--   <b><i>none</i></b> of the callbacks are executed.
--   
--   Example:
--   
--   <pre>
--   options :: Options IO ()
--   options = do
--       addOption "--help" $ do
--           putStrLn "--user NAME [AGE]"
--       addOption "--user" $ name -&gt; do
--           putStrLn $ <a>Name:</a> ++ name
--       addOption "--user" $ name age -&gt; do
--           putStrLn $ <a>Name:</a> ++ name ++ " Age:" ++ show (age :: Int)
--   
--   main :: IO ()
--   main = do
--       args &lt;- getArgs
--       mError &lt;- runOptions options args
--       case mError of
--           Just (ParseFailed _ _ _) -&gt; exitFailure
--           Nothing -&gt; exitSuccess
--   </pre>
runOptions :: Monad m => Options m a -> [String] -> m (Maybe OptionsError)

-- | Class describing parseable values. Much like the <a>Read</a> class.
class Parseable a
parse :: Parseable a => [String] -> (Maybe a, Int)

-- | A simple wrapper over <tt>[a]</tt>. Used to avoid overlapping
--   instances for <tt>Parseable [a]</tt> and <tt>Parseable String</tt>
newtype List a
List :: [a] -> List a
instance Show a => Show (List a)
instance Read a => Read (List a)
instance Eq a => Eq (List a)
instance Ord a => Ord (List a)
instance (Monad m, Functor m) => Applicative (Options m)
instance Functor m => Functor (Options m)
instance Monad m => Monad (Options m)
instance Monad m => MonadState (OptionsState m) (Options m)
instance MonadIO m => MonadIO (Options m)
instance Show OptionsError
instance MonadTrans Options
instance (Typeable a, WrapCallback m b) => WrapCallback m (a -> b)
instance WrapCallback m (m ())
instance Monad m => GetOpaqueParsers (m ())
instance (Parseable a, Typeable a, GetOpaqueParsers b) => GetOpaqueParsers (a -> b)
instance Parseable a => Parseable (List a)
instance Parseable a => Parseable (Maybe a)
instance Parseable Float
instance Parseable String
instance Parseable Int