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


-- | A "System.Console.GetOpt" wrapper to make simple use case easy.
--   
--   There's no need to invoke full <a>getOpt</a> power in everyday use.
--   So, here it is a most common use case implemented to be as painless as
--   possible while retaining some functionality. It's divided into three
--   layers, each built upon another. You can start at highest and peel of
--   layers to gradually unlock more <a>getOpt</a> features.
@package getopt-simple
@version 0.1.0.2


-- | There's no need to invoke full <a>getOpt</a> power in everyday use.
--   So, here it is a most common use case implemented to be as painless as
--   possible while retaining some functionality. It's divided into three
--   layers, each built upon another. You can start at highest and peel of
--   layers to gradually unlock more <a>getOpt</a> features.
module System.Console.GetOpt.Simple

-- | A result of all those musings is a plain string-to-string dictionary.
type Options = Map String String

-- | An option is a string-tagged string value to be processed with
--   <a>Data.Map</a> functions.
type Flag = (String, String)

-- | We are using a no-processing, grab and run away <tt>ArgDesc</tt>. All
--   options' arguments are required.
type FlagMaker = String -> ArgDescr Flag

-- | Make an option with a value. Option argument value will be captured
--   and “tagged” with an option name.
--   
--   <pre>
--   arg "user"
--   </pre>
arg :: FlagMaker

-- | Make a valueless option. The value captured will be an empty string.
--   
--   <pre>
--   noArg "debug"
--   </pre>
noArg :: FlagMaker

-- | Generate and show usage example using <a>getProgName</a> and lists of
--   required options and arguments.
showUsage :: [String] -> [String] -> IO ()

-- | An option list which will result in a assoc list of options.
type FlagDescr = OptDescr Flag

-- | Run getOpt against option list. Show errors and usage notice if
--   something goes wrong.
processOpts :: [FlagDescr] -> [String] -> [String] -> [String] -> IO (Options, [String])

-- | Extract values and validate against lists of mandatory arguments and
--   options. This adds a default '-h/--help' option.
--   
--   Low level uses getOpt's facilities to prepare option list and offers
--   maximum flexibility:
--   
--   <pre>
--   options = [ Option ['v'] ["verbose", "debug"] (noArg "debug")   "Dump all the stuff flying."
--             , Option ['d'] ["date"]             (arg   "date")    "Report date."
--             , Option ['c'] ["conf"]             (arg   "conf")    "Configuration file."
--             , Option ['s'] ["section"]          (arg   "section") "Configuration section."
--             ]
--   
--   (opts, args) &lt;- getOptsArgs options ["conf", "section"] ["command"]
--   </pre>
getOptsArgs :: [FlagDescr] -> [String] -> [String] -> IO (Options, [String])

-- | A validation flag. Ignored when building a option list but stored for
--   future reference.
data Mode
Required :: Mode
Optional :: Mode
Default :: String -> Mode

-- | <a>Conf</a>iguration type used to construct Option list and, later,
--   check for mandatory options and arguments.
type Conf = [(FlagMaker, String, Mode, String)]

-- | Process a <a>Conf</a>iguration into a list of <a>getOpt</a> options.
--   Required options and arguments are enforced, but defaults aren't being
--   into a result.
--   
--   <pre>
--   let options = makeOptions [ (noArg, "verbose", Optional,   "Dump all the stuff flying.")
--                             , (arg,   "date",    Required,   "Report date.")]
--                             , (arg,   "conf",    Required,   "Configuration file.")
--                             , (arg,   "section", Default "", "Configuration section.")
--                             ]
--   
--   (opts, args) &lt;- getOptsArgs (makeOptions options) ["conf", "section"] ["command"]
--   </pre>
makeOptions :: Conf -> [FlagDescr]

-- | Construct an <a>Option</a> from a less verbose list of values.
option :: FlagMaker -> String -> String -> FlagDescr

-- | Magic.
--   
--   <pre>
--   &gt;&gt;&gt; (opts, args) &lt;- getUsingConf options ["command"]
--   
--   &gt;&gt;&gt; print opts
--   fromList [("date", "2012-08-23"), ("conf", "/usr/local/etc/service.conf"), ("section", "")]
--   </pre>
getUsingConf :: Conf -> [String] -> IO (Options, [String])

-- | Process configuration into function arguments.
fromConf :: Conf -> ([FlagDescr], [String], [(String, String)])
instance Eq Mode
instance Show Mode