libghc-options-doc 1.2.1.1-6build1 / usr / share / doc / libghc-options-doc / html / options.txt

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


-- | A powerful and easy-to-use command-line option parser.
--   
--   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>
--   import Control.Applicative
--   import Options
--   
--   data MainOptions = MainOptions
--       { optMessage :: String
--       , optQuiet :: Bool
--       }
--   
--   instance <a>Options</a> MainOptions where
--       defineOptions = pure MainOptions
--           &lt;*&gt; simpleOption "message" "Hello world!"
--               "A message to show the user."
--           &lt;*&gt; simpleOption "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 :: text
--       A message to show the user.
--       default: "Hello world!"
--     --quiet :: bool
--       Whether to be quiet.
--       default: false
--   </pre>
@package options
@version 1.2.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>
--   import Control.Applicative
--   import Options
--   
--   data MainOptions = MainOptions
--       { optMessage :: String
--       , optQuiet :: Bool
--       }
--   
--   instance <a>Options</a> MainOptions where
--       <a>defineOptions</a> = pure MainOptions
--           &lt;*&gt; <a>simpleOption</a> "message" "Hello world!"
--               "A message to show the user."
--           &lt;*&gt; <a>simpleOption</a> "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 :: text
--       A message to show the user.
--       default: "Hello world!"
--     --quiet :: bool
--       Whether to be quiet.
--       default: false
--   </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>.
class Options opts

-- | Defines the structure and metadata of the options in this type,
--   including their types, flag names, and documentation.
--   
--   Options with a basic type and a single flag name may be defined with
--   <a>simpleOption</a>. Options with more complex requirements may be
--   defined with <a>defineOption</a>.
--   
--   Non-option fields in the type may be set using applicative functions
--   such as <a>pure</a>.
--   
--   Options may be included from another type by using a nested call to
--   <a>defineOptions</a>.
--   
--   Library authors are encouraged to aggregate their options into a few
--   top-level types, so application authors can include it easily in their
--   own option definitions.
defineOptions :: Options opts => DefineOptions opts

-- | 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 opts => opts

-- | Defines a new option in the current options type.
simpleOption :: SimpleOptionType a => String -> a -> String -> DefineOptions a
data DefineOptions a
class SimpleOptionType a
simpleOptionType :: SimpleOptionType a => OptionType a
data Subcommand cmdOpts action
subcommand :: (Options cmdOpts, Options subcmdOpts) => String -> (cmdOpts -> subcmdOpts -> [String] -> action) -> Subcommand cmdOpts action

-- | 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

-- | 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>
--   import Control.Applicative
--   import Control.Monad (unless)
--   import Options
--   
--   data MainOptions = MainOptions { optQuiet :: Bool }
--   instance <a>Options</a> MainOptions where
--       <a>defineOptions</a> = pure MainOptions
--           &lt;*&gt; <a>simpleOption</a> "quiet" False "Whether to be quiet."
--   
--   data HelloOpts = HelloOpts { optHello :: String }
--   instance <a>Options</a> HelloOpts where
--       <a>defineOptions</a> = pure HelloOpts
--           &lt;*&gt; <a>simpleOption</a> "hello" "Hello!" "How to say hello."
--   
--   data ByeOpts = ByeOpts { optName :: String }
--   instance <a>Options</a> ByeOpts where
--       <a>defineOptions</a> = pure ByeOpts
--           &lt;*&gt; <a>simpleOption</a> "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='Alice'
--   Good bye Alice
--   </pre>
runSubcommand :: (Options opts, MonadIO m) => [Subcommand opts (m a)] -> m a

-- | 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

-- | 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 val

-- | Defines a new option in the current options type.
--   
--   All options must have one or more <i>flags</i>. Options may also have
--   a default value, a description, and a group.
--   
--   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>defineOption</a> <a>optionType_word16</a> (\o -&gt; o
--       { <a>optionLongFlags</a> = ["port"]
--       , <a>optionDefault</a> = 80
--       })
--    
--   </pre>
defineOption :: OptionType a -> (Option a -> Option a) -> DefineOptions a
data Option a

-- | 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 -> 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 -> Maybe Group
data Group

-- | Define an option group with the given name and title. Use
--   <a>groupDescription</a> to add additional descriptive text, if needed.
group :: String -> String -> String -> Group
groupName :: Group -> String

-- | 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

-- | 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>
optionType_bool :: 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.
optionType_string :: OptionType String

-- | 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>.
optionType_int :: 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>.
optionType_int8 :: 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>.
optionType_int16 :: 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>.
optionType_int32 :: 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>.
optionType_int64 :: 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>.
optionType_word :: 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>.
optionType_word8 :: 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>.
optionType_word16 :: 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>.
optionType_word32 :: 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>.
optionType_word64 :: 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.
optionType_integer :: 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>.
optionType_float :: 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>.
optionType_double :: 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 is set to an empty string.
optionType_maybe :: 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.
optionType_list :: 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.
optionType_set :: 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.
optionType_map :: Ord k => Char -> Char -> OptionType k -> OptionType v -> OptionType (Map k v)

-- | Store an option as one of a set of possible values. The type must be a
--   bounded enumeration, and the type's <a>Show</a> instance will be used
--   to implement the parser.
--   
--   This is a simplistic implementation, useful for quick scripts. Users
--   with more complex requirements for enum parsing are encouraged to
--   define their own option types using <a>optionType</a>.
--   
--   <pre>
--   data Action = Hello | Goodbye
--       deriving (Bounded, Enum, Show)
--   
--   data MainOptions = MainOptions { optAction :: Action }
--   
--   instance <a>Options</a> MainOptions where
--       <a>defineOptions</a> = pure MainOptions
--           &lt;*&gt; <a>defineOption</a> (optionType_enum "action") (\o -&gt; o
--               { <a>optionLongFlags</a> = ["action"]
--               , <a>optionDefault</a> = Hello
--               })
--   
--   main = <a>runCommand</a> $ \opts args -&gt; do
--       putStrLn ("Running action " ++ show (optAction opts))
--    
--   </pre>
--   
--   <pre>
--   $ ./app
--   Running action Hello
--   $ ./app --action=Goodbye
--   Running action Goodbye
--   </pre>
optionType_enum :: (Bounded a, Enum a, Show a) => String -> OptionType a

-- | Define a new option type with the given name, default, and behavior.
optionType :: String -> val -> (String -> Either String val) -> (val -> String) -> OptionType val

-- | The name of this option type; used in <tt>--help</tt> output.
optionTypeName :: OptionType val -> String

-- | The default value for options of this type. This will be used if
--   <a>optionDefault</a> is not set when defining the option.
optionTypeDefault :: OptionType val -> val

-- | Try to parse the given string to an option value. If parsing fails, an
--   error message will be returned.
optionTypeParse :: OptionType val -> String -> Either String val

-- | Format the value for display; used in <tt>--help</tt> output.
optionTypeShow :: OptionType val -> val -> String

-- | If not Nothing, then options of this type may be set by a unary flag.
--   The option will be parsed as if the given value were set.
optionTypeUnary :: OptionType val -> Maybe val

-- | If not Nothing, then options of this type may be set with repeated
--   flags. Each flag will be parsed with <a>optionTypeParse</a>, and the
--   resulting parsed values will be passed to this function for merger
--   into the final value.
optionTypeMerge :: OptionType val -> Maybe ([val] -> val)
instance GHC.Show.Show Options.DeDupFlag
instance GHC.Classes.Ord Options.DeDupFlag
instance GHC.Classes.Eq Options.DeDupFlag
instance GHC.Base.Functor Options.DefineOptions
instance GHC.Base.Applicative Options.DefineOptions
instance Options.SimpleOptionType GHC.Types.Bool
instance Options.SimpleOptionType GHC.Base.String
instance Options.SimpleOptionType GHC.Integer.Type.Integer
instance Options.SimpleOptionType GHC.Types.Int
instance Options.SimpleOptionType GHC.Int.Int8
instance Options.SimpleOptionType GHC.Int.Int16
instance Options.SimpleOptionType GHC.Int.Int32
instance Options.SimpleOptionType GHC.Int.Int64
instance Options.SimpleOptionType GHC.Types.Word
instance Options.SimpleOptionType GHC.Word.Word8
instance Options.SimpleOptionType GHC.Word.Word16
instance Options.SimpleOptionType GHC.Word.Word32
instance Options.SimpleOptionType GHC.Word.Word64
instance Options.SimpleOptionType GHC.Types.Float
instance Options.SimpleOptionType GHC.Types.Double
instance Options.SimpleOptionType a => Options.SimpleOptionType (GHC.Base.Maybe a)
instance Options.Parsed (Options.ParsedOptions a)
instance Options.Parsed (Options.ParsedSubcommand a)