libghc-options-doc 0.1.1-3build1 / usr / share / doc / libghc-options-doc / html / options.txt

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


-- | Parsing command-line options
--   
--   The <tt>options</tt> package lets library and application developers
--   easily work with command-line options.
--   
--   The following example is a full program that can accept two options,
--   <tt>--message</tt> and <tt>--quiet</tt>:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import Options
--   
--   defineOptions "MainOptions" $ do
--       stringOption "optMessage" "message" "Hello world!"
--           "A message to show the user."
--       boolOption "optQuiet" "quiet" False
--           "Whether to be quiet."
--    
--   main :: IO ()
--   main = runCommand $ \opts args -&gt; do
--       if optQuiet opts
--           then return ()
--           else putStrLn (optMessage opts)
--   </pre>
--   
--   <pre>
--   $ ./hello
--   Hello world!
--   $ ./hello --message='ciao mondo'
--   ciao mondo
--   $ ./hello --quiet
--   $
--   </pre>
--   
--   In addition, this library will automatically create documentation
--   options such as <tt>--help</tt> and <tt>--help-all</tt>:
--   
--   <pre>
--   $ ./hello --help
--   Help Options:
--     -h, --help                  Show option summary.
--     --help-all                  Show all help options.
--   
--   Application Options:
--     --message                   A message to show the user.
--     --quiet                     Whether to be quiet.
--   </pre>
@package options
@version 0.1.1


-- | The <tt>options</tt> package lets library and application developers
--   easily work with command-line options.
--   
--   The following example is a full program that can accept two options,
--   <tt>--message</tt> and <tt>--quiet</tt>:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import Options
--   
--   <a>defineOptions</a> "MainOptions" $ do
--       <a>stringOption</a> "optMessage" "message" "Hello world!"
--           "A message to show the user."
--       <a>boolOption</a> "optQuiet" "quiet" False
--           "Whether to be quiet."
--   
--   main :: IO ()
--   main = <a>runCommand</a> $ \opts args -&gt; do
--       if optQuiet opts
--           then return ()
--           else putStrLn (optMessage opts)
--   </pre>
--   
--   <pre>
--   $ ./hello
--   Hello world!
--   $ ./hello --message='ciao mondo'
--   ciao mondo
--   $ ./hello --quiet
--   $
--   </pre>
--   
--   In addition, this library will automatically create documentation
--   options such as <tt>--help</tt> and <tt>--help-all</tt>:
--   
--   <pre>
--   $ ./hello --help
--   Help Options:
--     -h, --help                  Show option summary.
--     --help-all                  Show all help options.
--   
--   Application Options:
--     --message                   A message to show the user.
--     --quiet                     Whether to be quiet.
--   </pre>
module Options

-- | Options are defined together in a single data type, which will be an
--   instance of <a>Options</a>.
--   
--   See <a>defineOptions</a> for details on defining instances of
--   <a>Options</a>.
--   
--   See <a>options</a> for details on including imported <a>Options</a>
--   types in locally defined options.
class Options a

-- | An options value containing only the default values for each option.
--   This is equivalent to the options value when parsing an empty argument
--   list.
defaultOptions :: Options a => a

-- | Retrieve <a>getArgs</a>, and attempt to parse it into a valid value of
--   an <a>Options</a> type plus a list of left-over arguments. The options
--   and arguments are then passed to the provided computation.
--   
--   If parsing fails, this computation will print an error and call
--   <a>exitFailure</a>.
--   
--   If parsing succeeds, and the user has passed a <tt>--help</tt> flag,
--   and the developer is using the default help flag definitions, then
--   this computation will print documentation and call <a>exitSuccess</a>.
--   
--   See <a>runSubcommand</a> for details on subcommand support.
runCommand :: (MonadIO m, Options opts) => (opts -> [String] -> m a) -> m a
data Subcommand cmdOpts action
subcommand :: (Options cmdOpts, Options subcmdOpts) => String -> (cmdOpts -> subcmdOpts -> [String] -> action) -> Subcommand cmdOpts action

-- | Used to run applications that are split into subcommands.
--   
--   Use <a>subcommand</a> to define available commands and their actions,
--   then pass them to this computation to select one and run it. If the
--   user specifies an invalid subcommand, this computation will print an
--   error and call <a>exitFailure</a>. In handling of invalid flags or
--   <tt>--help</tt>, <a>runSubcommand</a> acts like <a>runCommand</a>.
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import Control.Monad (unless)
--   import Options
--   
--   <a>defineOptions</a> "MainOptions" $ do
--       <a>boolOption</a> "optQuiet" "quiet" False "Whether to be quiet."
--   
--   <a>defineOptions</a> "HelloOpts" $ do
--       <a>stringOption</a> "optHello" "hello" "Hello!" "How to say hello."
--   
--   <a>defineOptions</a> "ByeOpts" $ do
--       <a>stringOption</a> "optName" "name" "" "The user's name."
--   
--   hello :: MainOptions -&gt; HelloOpts -&gt; [String] -&gt; IO ()
--   hello mainOpts opts args = unless (optQuiet mainOpts) $ do
--       putStrLn (optHello opts)
--   
--   bye :: MainOptions -&gt; ByeOpts -&gt; [String] -&gt; IO ()
--   bye mainOpts opts args = unless (optQuiet mainOpts) $ do
--       putStrLn ("Good bye " ++ optName opts)
--   
--   main :: IO ()
--   main = <a>runSubcommand</a>
--       [ <a>subcommand</a> "hello" hello
--       , <a>subcommand</a> "bye" bye
--       ]
--   </pre>
--   
--   <pre>
--   $ ./app hello
--   Hello!
--   $ ./app hello --hello='Allo!'
--   Allo!
--   $ ./app bye
--   Good bye 
--   $ ./app bye --name='John'
--   Good bye John
--   </pre>
runSubcommand :: (Options opts, MonadIO m) => [Subcommand opts (m a)] -> m a

-- | Defines a new data type, containing fields for application or library
--   options. The new type will be an instance of <a>Options</a>.
--   
--   Example: this use of <tt>defineOptions</tt>:
--   
--   <pre>
--   <a>defineOptions</a> "MainOptions" $ do
--       <a>stringOption</a> "optMessage" "message" "Hello world!" ""
--       <a>boolOption</a> "optQuiet" "quiet" False ""
--   </pre>
--   
--   expands to the following definition:
--   
--   <pre>
--   data MainOptions = MainOptions
--       { optMessage :: String
--       , optQuiet :: Bool
--       }
--   
--   instance Options MainOptions
--   </pre>
defineOptions :: String -> OptionsM () -> Q [Dec]

-- | Define an option of type <tt><a>Bool</a></tt>. This is a simple
--   wrapper around <a>option</a>.
boolOption :: String -> String -> Bool -> String -> OptionsM ()

-- | Define an option of type <tt><a>String</a></tt>. This is a simple
--   wrapper around <a>option</a>.
stringOption :: String -> String -> String -> String -> OptionsM ()

-- | Define an option of type <tt>[<a>String</a>]</tt>. This is a simple
--   wrapper around <a>option</a>. Items are comma-separated.
stringsOption :: String -> String -> [String] -> String -> OptionsM ()

-- | Define an option of type <tt><a>Text</a></tt>. This is a simple
--   wrapper around <a>option</a>.
textOption :: String -> String -> Text -> String -> OptionsM ()

-- | Define an option of type <tt>[<a>Text</a>]</tt>. This is a simple
--   wrapper around <a>option</a>. Items are comma-separated.
textsOption :: String -> String -> [Text] -> String -> OptionsM ()

-- | Define an option of type <tt><a>FilePath</a></tt>. This is a simple
--   wrapper around <a>option</a>.
pathOption :: String -> String -> FilePath -> String -> OptionsM ()

-- | Define an option of type <tt><a>Int</a></tt>. This is a simple wrapper
--   around <a>option</a>.
intOption :: String -> String -> Int -> String -> OptionsM ()

-- | Define an option of type <tt><a>Integer</a></tt>. This is a simple
--   wrapper around <a>option</a>.
integerOption :: String -> String -> Integer -> String -> OptionsM ()

-- | Define an option of type <tt><a>Float</a></tt>. This is a simple
--   wrapper around <a>option</a>.
floatOption :: String -> String -> Float -> String -> OptionsM ()

-- | Define an option of type <tt><a>Double</a></tt>. This is a simple
--   wrapper around <a>option</a>.
doubleOption :: String -> String -> Double -> String -> OptionsM ()
data ImportedOptions a
importedOptions :: Options a => ImportedOptions a

-- | Include options defined elsewhere into the current options definition.
--   
--   This is typically used by application developers to include options
--   defined in third-party libraries. For example, the author of the "foo"
--   library would define and export <tt>FooOptions</tt>:
--   
--   <pre>
--   module Foo (FooOptions, foo) where
--   
--   import Options
--   
--   <a>defineOptions</a> "FooOptions" $ do
--       <a>boolOption</a> "optFrob" "frob" True "Enable frobnication."
--   
--   foo :: FooOptions -&gt; IO ()
--   </pre>
--   
--   and the author of an application would use <tt>options</tt> to let
--   users specify <tt>--frob</tt>:
--   
--   <pre>
--   module Main where
--   
--   import Options
--   import Foo
--   
--   <a>defineOptions</a> "MainOptions" $ do
--      <a>boolOption</a> "optVerbose" "verbose" False "Be really loud."
--      <a>options</a> "optFoo" (<a>importedOptions</a> :: <a>ImportedOptions</a> FooOptions)
--   
--   main :: IO ()
--   main = runCommand $ \opts args -&gt; do
--       foo (optFoo opts)
--   </pre>
--   
--   Use of <a>options</a> may be arbitrarily nested. Library authors are
--   encouraged to aggregate their options into a single top-level type, so
--   application authors can include it easily in their own option
--   definitions.
options :: String -> ImportedOptions a -> OptionsM ()
data Option a

-- | Defines a new option in the current options type.
--   
--   All options must have a <i>field name</i> and one or more
--   <i>flags</i>. Options may also have a default value, a description, or
--   a group.
--   
--   The field name is how the option will be accessed in Haskell, and is
--   typically prefixed with "opt". This is used to define a record field,
--   and must be a valid Haskell field name (see <a>defineOptions</a> for
--   details).
--   
--   The <i>flags</i> are how the user specifies an option on the command
--   line. Flags may be <i>short</i> or <i>long</i>. See
--   <a>optionShortFlags</a> and <a>optionLongFlags</a> for details.
--   
--   <pre>
--   <a>option</a> "optPort" (\o -&gt; o
--       { <a>optionLongFlags</a> = ["port"]
--       , <a>optionDefault</a> = "80"
--       , <a>optionType</a> = <a>optionTypeWord16</a>
--       }
--   </pre>
option :: String -> (Option String -> Option a) -> OptionsM ()

-- | Short flags are a single character. When entered by a user, they are
--   preceded by a dash and possibly other short flags.
--   
--   Short flags must be a letter or a number.
--   
--   Example: An option with <tt>optionShortFlags = ['p']</tt> may be set
--   using:
--   
--   <pre>
--   $ ./app -p 443
--   $ ./app -p443
--   </pre>
optionShortFlags :: Option a -> [Char]

-- | Long flags are multiple characters. When entered by a user, they are
--   preceded by two dashes.
--   
--   Long flags may contain letters, numbers, <tt>'-'</tt>, and
--   <tt>'_'</tt>.
--   
--   Example: An option with <tt>optionLongFlags = ["port"]</tt> may be set
--   using:
--   
--   <pre>
--   $ ./app --port 443
--   $ ./app --port=443
--   </pre>
optionLongFlags :: Option a -> [String]

-- | Options may have a default value. This will be parsed as if the user
--   had entered it on the command line.
optionDefault :: Option a -> String

-- | There are many types which an application or library might want to use
--   when designing their options. By default, options are strings, but
--   <a>optionType</a> may be set to any supported type. See the "Option
--   types" section for a list of supported types.
optionType :: Option a -> OptionType a

-- | An option's description is used with the default implementation of
--   <tt>--help</tt>. It should be a short string describing what the
--   option does.
optionDescription :: Option a -> String

-- | Which group the option is in. See the "Option groups" section for
--   details.
optionGroup :: Option a -> Group

-- | An option's type determines how the option will be parsed, and which
--   Haskell type the parsed value will be stored as. There are many types
--   available, covering most basic types and a few more advanced types.
data OptionType a

-- | Store an option as a <tt><a>Bool</a></tt>. The option's value must be
--   either <tt>"true"</tt> or <tt>"false"</tt>.
--   
--   Boolean options are unary, which means that their value is optional
--   when specified on the command line. If a flag is present, the option
--   is set to True.
--   
--   <pre>
--   $ ./app -q
--   $ ./app --quiet
--   </pre>
--   
--   Boolean options may still be specified explicitly by using long flags
--   with the <tt>--flag=value</tt> format. This is the only way to set a
--   unary flag to <tt>"false"</tt>.
--   
--   <pre>
--   $ ./app --quiet=true
--   $ ./app --quiet=false
--   </pre>
optionTypeBool :: OptionType Bool

-- | Store an option value as a <tt><a>String</a></tt>. The value is
--   decoded to Unicode first, if needed. The value may contain non-Unicode
--   bytes, in which case they will be stored using GHC 7.4's encoding for
--   mixed-use strings.
optionTypeString :: OptionType String

-- | Store an option value as a <tt><a>Text</a></tt>. The value is decoded
--   to Unicode first, if needed. If the value cannot be decoded, the
--   stored value may have the Unicode substitution character
--   <tt>'\65533'</tt> in place of some of the original input.
optionTypeText :: OptionType Text

-- | Store an option value as a <tt><a>FilePath</a></tt>.
optionTypeFilePath :: OptionType FilePath

-- | Store an option as an <tt><a>Int</a></tt>. The option value must be an
--   integer <i>n</i> such that <tt><a>minBound</a> &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeInt :: OptionType Int

-- | Store an option as an <tt><a>Int8</a></tt>. The option value must be
--   an integer <i>n</i> such that <tt><a>minBound</a> &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeInt8 :: OptionType Int8

-- | Store an option as an <tt><a>Int16</a></tt>. The option value must be
--   an integer <i>n</i> such that <tt><a>minBound</a> &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeInt16 :: OptionType Int16

-- | Store an option as an <tt><a>Int32</a></tt>. The option value must be
--   an integer <i>n</i> such that <tt><a>minBound</a> &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeInt32 :: OptionType Int32

-- | Store an option as an <tt><a>Int64</a></tt>. The option value must be
--   an integer <i>n</i> such that <tt><a>minBound</a> &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeInt64 :: OptionType Int64

-- | Store an option as a <tt><a>Word</a></tt>. The option value must be a
--   positive integer <i>n</i> such that <tt>0 &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeWord :: OptionType Word

-- | Store an option as a <tt><a>Word8</a></tt>. The option value must be a
--   positive integer <i>n</i> such that <tt>0 &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeWord8 :: OptionType Word8

-- | Store an option as a <tt><a>Word16</a></tt>. The option value must be
--   a positive integer <i>n</i> such that <tt>0 &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeWord16 :: OptionType Word16

-- | Store an option as a <tt><a>Word32</a></tt>. The option value must be
--   a positive integer <i>n</i> such that <tt>0 &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeWord32 :: OptionType Word32

-- | Store an option as a <tt><a>Word64</a></tt>. The option value must be
--   a positive integer <i>n</i> such that <tt>0 &lt;= n &lt;=
--   <a>maxBound</a></tt>.
optionTypeWord64 :: OptionType Word64

-- | Store an option as an <tt><a>Integer</a></tt>. The option value must
--   be an integer. There is no minimum or maximum value.
optionTypeInteger :: OptionType Integer

-- | Store an option as a <tt><a>Float</a></tt>. The option value must be a
--   number. Due to the imprecision of floating-point math, the stored
--   value might not exactly match the user's input. If the user's input is
--   out of range for the <tt><a>Float</a></tt> type, it will be stored as
--   <tt>Infinity</tt> or <tt>-Infinity</tt>.
optionTypeFloat :: OptionType Float

-- | Store an option as a <tt><a>Double</a></tt>. The option value must be
--   a number. Due to the imprecision of floating-point math, the stored
--   value might not exactly match the user's input. If the user's input is
--   out of range for the <tt><a>Double</a></tt> type, it will be stored as
--   <tt>Infinity</tt> or <tt>-Infinity</tt>.
optionTypeDouble :: OptionType Double

-- | Store an option as a <tt><a>Maybe</a></tt> of another type. The value
--   will be <tt>Nothing</tt> if the option was not provided or is an empty
--   string.
--   
--   <pre>
--   <tt>option</tt> "optTimeout" (\o -&gt; o
--       { <a>optionLongFlags</a> = ["timeout"]
--       , <a>optionType</a> = <a>optionTypeMaybe</a> <a>optionTypeInt</a>
--       })
--   </pre>
optionTypeMaybe :: OptionType a -> OptionType (Maybe a)

-- | Store an option as a list, using another option type for the elements.
--   The separator should be a character that will not occur within the
--   values, such as a comma or semicolon.
--   
--   <pre>
--   <tt>option</tt> "optNames" (\o -&gt; o
--       { <a>optionLongFlags</a> = ["names"]
--       , <a>optionDefault</a> = "Alice;Bob;Charles"
--       , <a>optionType</a> = <a>optionTypeList</a> ';' <a>optionTypeString</a>
--       })
--   </pre>
optionTypeList :: Char -> OptionType a -> OptionType [a]

-- | Store an option as a <tt><a>Set</a></tt>, using another option type
--   for the elements. The separator should be a character that will not
--   occur within the values, such as a comma or semicolon.
--   
--   Duplicate elements in the input are permitted.
--   
--   <pre>
--   <tt>option</tt> "optNames" (\o -&gt; o
--       { <a>optionLongFlags</a> = ["names"]
--       , <a>optionDefault</a> = "Alice;Bob;Charles"
--       , <a>optionType</a> = <a>optionTypeSet</a> ';' <a>optionTypeString</a>
--       })
--   </pre>
optionTypeSet :: Ord a => Char -> OptionType a -> OptionType (Set a)

-- | Store an option as a <a>Map</a>, using other option types for the keys
--   and values.
--   
--   The item separator is used to separate key/value pairs from eachother.
--   It should be a character that will not occur within either the keys or
--   values.
--   
--   The value separator is used to separate the key from the value. It
--   should be a character that will not occur within the keys. It may
--   occur within the values.
--   
--   Duplicate keys in the input are permitted. The final value for each
--   key is stored.
--   
--   <pre>
--   <tt>option</tt> "optNames" (\o -&gt; o
--       { <a>optionLongFlags</a> = ["names"]
--       , <a>optionDefault</a> = "name=Alice;hometown=Bucharest"
--       , <a>optionType</a> = <a>optionTypeMap</a> ';' '=' <a>optionTypeString</a> <a>optionTypeString</a>
--       })
--   </pre>
optionTypeMap :: Ord k => Char -> Char -> OptionType k -> OptionType v -> OptionType (Map k v)

-- | Store an option as one of a set of enumerated values. The option type
--   must be defined in a separate file.
--   
--   <pre>
--   -- MyApp/Types.hs
--   data Mode = ModeFoo | ModeBar
--       deriving (Enum)
--   </pre>
--   
--   <pre>
--    -- Main.hs
--   import MyApp.Types
--   
--   <tt>defineOptions</tt> "MainOptions" $ do
--       <tt>option</tt> "optMode" (\o -&gt; o
--           { <a>optionLongFlags</a> = ["mode"]
--           , <a>optionDefault</a> = "foo"
--           , <a>optionType</a> = <a>optionTypeEnum</a> ''Mode
--               [ ("foo", ModeFoo)
--               , ("bar", ModeBar)
--               ]
--           })
--   </pre>
--   
--   <pre>
--   $ ./app
--   Running in mode ModeFoo
--   $ ./app --mode=bar
--   Running in mode ModeBar
--   </pre>
optionTypeEnum :: Enum a => Name -> [(String, a)] -> OptionType a
data Group

-- | Define an option group.
--   
--   Option groups are used to make long <tt>--help</tt> output more
--   readable, by hiding obscure or rarely-used options from the main
--   summary.
--   
--   If an option is in a group named <tt>"examples"</tt>, it will only be
--   shown in the help output if the user provides the flag
--   <tt>--help-examples</tt> or <tt>--help-all</tt>. The flag
--   <tt>--help-all</tt> will show all options, in all groups.
group :: String -> (Group -> Group) -> Group

-- | A short title for the group, which is used when printing
--   <tt>--help</tt> output.
groupTitle :: Group -> String

-- | A description of the group, which is used when printing
--   <tt>--help</tt> output.
groupDescription :: Group -> String

-- | See <tt><a>parseOptions</a></tt> and <tt><a>parseSubcommand</a></tt>.
class Parsed a

-- | Get the error that prevented options from being parsed from argv, or
--   <tt>Nothing</tt> if no error was detected.
parsedError :: Parsed a => a -> Maybe String

-- | Get a help message to show the user. If the arguments included a help
--   flag, this will be a message appropriate to that flag. Otherwise, it
--   is a summary (equivalent to <tt>--help</tt>).
--   
--   This is always a non-empty string, regardless of whether the parse
--   succeeded or failed. If you need to perform additional validation on
--   the options value, this message can be displayed if validation fails.
parsedHelp :: Parsed a => a -> String

-- | See <tt><a>parseOptions</a></tt>.
data ParsedOptions opts

-- | Get the options value that was parsed from argv, or <tt>Nothing</tt>
--   if the arguments could not be converted into options.
--   
--   Note: This function return <tt>Nothing</tt> if the user provided a
--   help flag. To check whether an error occured during parsing, check the
--   value of <tt><a>parsedError</a></tt>.
parsedOptions :: ParsedOptions opts -> Maybe opts

-- | Get command-line arguments remaining after parsing options. The
--   arguments are unchanged from the original argument list, and have not
--   been decoded or otherwise transformed.
parsedArguments :: ParsedOptions opts -> [String]

-- | Attempt to convert a list of command-line arguments into an options
--   value. This can be used by application developers who want finer
--   control over error handling, or who want to perform additional
--   validation on the options value.
--   
--   The argument list must be in the same encoding as the result of
--   <a>getArgs</a>.
--   
--   Use <tt><a>parsedOptions</a></tt>, <tt><a>parsedArguments</a></tt>,
--   <tt><a>parsedError</a></tt>, and <tt><a>parsedHelp</a></tt> to inspect
--   the result of <tt><a>parseOptions</a></tt>.
--   
--   Example:
--   
--   <pre>
--   getOptionsOrDie :: Options a =&gt; IO a
--   getOptionsOrDie = do
--       argv &lt;- System.Environment.getArgs
--       let parsed = <a>parseOptions</a> argv
--       case <a>parsedOptions</a> parsed of
--           Just opts -&gt; return opts
--           Nothing -&gt; case <a>parsedError</a> parsed of
--               Just err -&gt; do
--                   hPutStrLn stderr (<a>parsedHelp</a> parsed)
--                   hPutStrLn stderr err
--                   exitFailure
--               Nothing -&gt; do
--                   hPutStr stdout (<a>parsedHelp</a> parsed)
--                   exitSuccess
--   </pre>
parseOptions :: Options opts => [String] -> ParsedOptions opts

-- | See <tt><a>parseSubcommand</a></tt>.
data ParsedSubcommand action

-- | Get the subcommand action that was parsed from argv, or
--   <tt>Nothing</tt> if the arguments could not be converted into a valid
--   action.
--   
--   Note: This function return <tt>Nothing</tt> if the user provided a
--   help flag. To check whether an error occured during parsing, check the
--   value of <tt><a>parsedError</a></tt>.
parsedSubcommand :: ParsedSubcommand action -> Maybe action

-- | Attempt to convert a list of command-line arguments into a subcommand
--   action. This can be used by application developers who want finer
--   control over error handling, or who want subcommands that run in an
--   unusual monad.
--   
--   The argument list must be in the same encoding as the result of
--   <a>getArgs</a>.
--   
--   Use <tt><a>parsedSubcommand</a></tt>, <tt><a>parsedError</a></tt>, and
--   <tt><a>parsedHelp</a></tt> to inspect the result of
--   <tt><a>parseSubcommand</a></tt>.
--   
--   Example:
--   
--   <pre>
--   runSubcommand :: Options cmdOpts =&gt; [Subcommand cmdOpts (IO a)] -&gt; IO a
--   runSubcommand subcommands = do
--       argv &lt;- System.Environment.getArgs
--       let parsed = <a>parseSubcommand</a> subcommands argv
--       case <a>parsedSubcommand</a> parsed of
--           Just cmd -&gt; cmd
--           Nothing -&gt; case <a>parsedError</a> parsed of
--               Just err -&gt; do
--                   hPutStrLn stderr (<a>parsedHelp</a> parsed)
--                   hPutStrLn stderr err
--                   exitFailure
--               Nothing -&gt; do
--                   hPutStr stdout (<a>parsedHelp</a> parsed)
--                   exitSuccess
--   </pre>
parseSubcommand :: Options cmdOpts => [Subcommand cmdOpts action] -> [String] -> ParsedSubcommand action
instance Parsed (ParsedSubcommand a)
instance Parsed (ParsedOptions a)
instance Monad (ParserM optType)
instance Monad OptionsM