-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Parsing command-line options
--
-- The options package lets library and application developers
-- easily work with command-line options.
--
-- The following example is a full program that can accept two options,
-- --message and --quiet:
--
--
-- {-# 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 -> do
-- if optQuiet opts
-- then return ()
-- else putStrLn (optMessage opts)
--
--
--
-- $ ./hello
-- Hello world!
-- $ ./hello --message='ciao mondo'
-- ciao mondo
-- $ ./hello --quiet
-- $
--
--
-- In addition, this library will automatically create documentation
-- options such as --help and --help-all:
--
--
-- $ ./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.
--
@package options
@version 0.1
-- | The options package lets library and application developers
-- easily work with command-line options.
--
-- The following example is a full program that can accept two options,
-- --message and --quiet:
--
--
-- {-# 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 -> do
-- if optQuiet opts
-- then return ()
-- else putStrLn (optMessage opts)
--
--
--
-- $ ./hello
-- Hello world!
-- $ ./hello --message='ciao mondo'
-- ciao mondo
-- $ ./hello --quiet
-- $
--
--
-- In addition, this library will automatically create documentation
-- options such as --help and --help-all:
--
--
-- $ ./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.
--
module Options
-- | Options are defined together in a single data type, which will be an
-- instance of Options.
--
-- See defineOptions for details on defining instances of
-- Options.
--
-- See options for details on including imported Options
-- 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 getArgs, and attempt to parse it into a valid value of
-- an Options 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
-- exitFailure.
--
-- If parsing succeeds, and the user has passed a --help flag,
-- and the developer is using the default help flag definitions, then
-- this computation will print documentation and call exitSuccess.
--
-- See runSubcommand 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 subcommand 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 exitFailure. In handling of invalid flags or
-- --help, runSubcommand acts like runCommand.
--
--
-- {-# LANGUAGE TemplateHaskell #-}
--
-- import Control.Monad (unless)
-- import Options
--
-- defineOptions "MainOptions" $ do
-- boolOption "optQuiet" "quiet" False "Whether to be quiet."
--
-- defineOptions "HelloOpts" $ do
-- stringOption "optHello" "hello" "Hello!" "How to say hello."
--
-- defineOptions "ByeOpts" $ do
-- stringOption "optName" "name" "" "The user's name."
--
-- hello :: MainOptions -> HelloOpts -> [String] -> IO ()
-- hello mainOpts opts args = unless (optQuiet mainOpts) $ do
-- putStrLn (optHello opts)
--
-- bye :: MainOptions -> ByeOpts -> [String] -> IO ()
-- bye mainOpts opts args = unless (optQuiet mainOpts) $ do
-- putStrLn ("Good bye " ++ optName opts)
--
-- main :: IO ()
-- main = runSubcommand
-- [ subcommand "hello" hello
-- , subcommand "bye" bye
-- ]
--
--
--
-- $ ./app hello
-- Hello!
-- $ ./app hello --hello='Allo!'
-- Allo!
-- $ ./app bye
-- Good bye
-- $ ./app bye --name='John'
-- Good bye John
--
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 Options.
--
-- Example: this use of defineOptions:
--
--
-- defineOptions "MainOptions" $ do
-- stringOption "optMessage" "message" "Hello world!" ""
-- boolOption "optQuiet" "quiet" False ""
--
--
-- expands to the following definition:
--
--
-- data MainOptions = MainOptions
-- { optMessage :: String
-- , optQuiet :: Bool
-- }
--
-- instance Options MainOptions
--
defineOptions :: String -> OptionsM () -> Q [Dec]
-- | Define an option of type Bool. This is a simple
-- wrapper around option.
boolOption :: String -> String -> Bool -> String -> OptionsM ()
-- | Define an option of type String. This is a simple
-- wrapper around option.
stringOption :: String -> String -> String -> String -> OptionsM ()
-- | Define an option of type [String]. This is a simple
-- wrapper around option. Items are comma-separated.
stringsOption :: String -> String -> [String] -> String -> OptionsM ()
-- | Define an option of type Text. This is a simple
-- wrapper around option.
textOption :: String -> String -> Text -> String -> OptionsM ()
-- | Define an option of type [Text]. This is a simple
-- wrapper around option. Items are comma-separated.
textsOption :: String -> String -> [Text] -> String -> OptionsM ()
-- | Define an option of type FilePath. This is a simple
-- wrapper around option.
pathOption :: String -> String -> FilePath -> String -> OptionsM ()
-- | Define an option of type Int. This is a simple wrapper
-- around option.
intOption :: String -> String -> Int -> String -> OptionsM ()
-- | Define an option of type Integer. This is a simple
-- wrapper around option.
integerOption :: String -> String -> Integer -> String -> OptionsM ()
-- | Define an option of type Float. This is a simple
-- wrapper around option.
floatOption :: String -> String -> Float -> String -> OptionsM ()
-- | Define an option of type Double. This is a simple
-- wrapper around option.
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 FooOptions:
--
--
-- module Foo (FooOptions, foo) where
--
-- import Options
--
-- defineOptions "FooOptions" $ do
-- boolOption "optFrob" "frob" True "Enable frobnication."
--
-- foo :: FooOptions -> IO ()
--
--
-- and the author of an application would use options to let
-- users specify --frob:
--
--
-- module Main where
--
-- import Options
-- import Foo
--
-- defineOptions "MainOptions" $ do
-- boolOption "optVerbose" "verbose" False "Be really loud."
-- options "optFoo" (importedOptions :: ImportedOptions FooOptions)
--
-- main :: IO ()
-- main = runCommand $ \opts args -> do
-- foo (optFoo opts)
--
--
-- Use of options 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 field name and one or more
-- flags. 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 defineOptions for
-- details).
--
-- The flags are how the user specifies an option on the command
-- line. Flags may be short or long. See
-- optionShortFlags and optionLongFlags for details.
--
--
-- option "optPort" (\o -> o
-- { optionLongFlags = ["port"]
-- , optionDefault = "80"
-- , optionType = optionTypeWord16
-- }
--
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 optionShortFlags = ['p'] may be set
-- using:
--
--
-- $ ./app -p 443
-- $ ./app -p443
--
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, '-', and
-- '_'.
--
-- Example: An option with optionLongFlags = ["port"] may be set
-- using:
--
--
-- $ ./app --port 443
-- $ ./app --port=443
--
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
-- optionType 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
-- --help. 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 Bool. The option's value must be
-- either "true" or "false".
--
-- 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.
--
--
-- $ ./app -q
-- $ ./app --quiet
--
--
-- Boolean options may still be specified explicitly by using long flags
-- with the --flag=value format. This is the only way to set a
-- unary flag to "false".
--
--
-- $ ./app --quiet=true
-- $ ./app --quiet=false
--
optionTypeBool :: OptionType Bool
-- | Store an option value as a String. 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 Text. The value is decoded
-- to Unicode first, if needed. If the value cannot be decoded, the
-- stored value may have the Unicode substitution character
-- '\65533' in place of some of the original input.
optionTypeText :: OptionType Text
-- | Store an option value as a FilePath.
optionTypeFilePath :: OptionType FilePath
-- | Store an option as an Int. The option value must be an
-- integer n such that minBound <= n <=
-- maxBound.
optionTypeInt :: OptionType Int
-- | Store an option as an Int8. The option value must be
-- an integer n such that minBound <= n <=
-- maxBound.
optionTypeInt8 :: OptionType Int8
-- | Store an option as an Int16. The option value must be
-- an integer n such that minBound <= n <=
-- maxBound.
optionTypeInt16 :: OptionType Int16
-- | Store an option as an Int32. The option value must be
-- an integer n such that minBound <= n <=
-- maxBound.
optionTypeInt32 :: OptionType Int32
-- | Store an option as an Int64. The option value must be
-- an integer n such that minBound <= n <=
-- maxBound.
optionTypeInt64 :: OptionType Int64
-- | Store an option as a Word. The option value must be a
-- positive integer n such that 0 <= n <=
-- maxBound.
optionTypeWord :: OptionType Word
-- | Store an option as a Word8. The option value must be a
-- positive integer n such that 0 <= n <=
-- maxBound.
optionTypeWord8 :: OptionType Word8
-- | Store an option as a Word16. The option value must be
-- a positive integer n such that 0 <= n <=
-- maxBound.
optionTypeWord16 :: OptionType Word16
-- | Store an option as a Word32. The option value must be
-- a positive integer n such that 0 <= n <=
-- maxBound.
optionTypeWord32 :: OptionType Word32
-- | Store an option as a Word64. The option value must be
-- a positive integer n such that 0 <= n <=
-- maxBound.
optionTypeWord64 :: OptionType Word64
-- | Store an option as an Integer. The option value must
-- be an integer. There is no minimum or maximum value.
optionTypeInteger :: OptionType Integer
-- | Store an option as a Float. 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 Float type, it will be stored as
-- Infinity or -Infinity.
optionTypeFloat :: OptionType Float
-- | Store an option as a Double. 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 Double type, it will be stored as
-- Infinity or -Infinity.
optionTypeDouble :: OptionType Double
-- | Store an option as a Maybe of another type. The value
-- will be Nothing if the option was not provided or is an empty
-- string.
--
--
-- option "optTimeout" (\o -> o
-- { optionLongFlags = ["timeout"]
-- , optionType = optionTypeMaybe optionTypeInt
-- })
--
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.
--
--
-- option "optNames" (\o -> o
-- { optionLongFlags = ["names"]
-- , optionDefault = "Alice;Bob;Charles"
-- , optionType = optionTypeList ';' optionTypeString
-- })
--
optionTypeList :: Char -> OptionType a -> OptionType [a]
-- | Store an option as a Set, 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.
--
--
-- option "optNames" (\o -> o
-- { optionLongFlags = ["names"]
-- , optionDefault = "Alice;Bob;Charles"
-- , optionType = optionTypeSet ';' optionTypeString
-- })
--
optionTypeSet :: Ord a => Char -> OptionType a -> OptionType (Set a)
-- | Store an option as a Map, 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.
--
--
-- option "optNames" (\o -> o
-- { optionLongFlags = ["names"]
-- , optionDefault = "name=Alice;hometown=Bucharest"
-- , optionType = optionTypeMap ';' '=' optionTypeString optionTypeString
-- })
--
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.
--
--
-- -- MyApp/Types.hs
-- data Mode = ModeFoo | ModeBar
-- deriving (Enum)
--
--
--
-- -- Main.hs
-- import MyApp.Types
--
-- defineOptions "MainOptions" $ do
-- option "optMode" (\o -> o
-- { optionLongFlags = ["mode"]
-- , optionDefault = "foo"
-- , optionType = optionTypeEnum ''Mode
-- [ ("foo", ModeFoo)
-- , ("bar", ModeBar)
-- ]
-- })
--
--
--
-- $ ./app
-- Running in mode ModeFoo
-- $ ./app --mode=bar
-- Running in mode ModeBar
--
optionTypeEnum :: Enum a => Name -> [(String, a)] -> OptionType a
data Group
-- | Define an option group.
--
-- Option groups are used to make long --help output more
-- readable, by hiding obscure or rarely-used options from the main
-- summary.
--
-- If an option is in a group named "examples", it will only be
-- shown in the help output if the user provides the flag
-- --help-examples or --help-all. The flag
-- --help-all will show all options, in all groups.
group :: String -> (Group -> Group) -> Group
-- | A short title for the group, which is used when printing
-- --help output.
groupTitle :: Group -> String
-- | A description of the group, which is used when printing
-- --help output.
groupDescription :: Group -> String
-- | See parseOptions and parseSubcommand.
class Parsed a
-- | Get the error that prevented options from being parsed from argv, or
-- Nothing 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 --help).
--
-- 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 parseOptions.
data ParsedOptions opts
-- | Get the options value that was parsed from argv, or Nothing
-- if the arguments could not be converted into options.
--
-- Note: This function return Nothing if the user provided a
-- help flag. To check whether an error occured during parsing, check the
-- value of parsedError.
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
-- getArgs.
--
-- Use parsedOptions, parsedArguments,
-- parsedError, and parsedHelp to inspect
-- the result of parseOptions.
--
-- Example:
--
--
-- getOptionsOrDie :: Options a => IO a
-- getOptionsOrDie = do
-- argv <- System.Environment.getArgs
-- let parsed = parseOptions argv
-- case parsedOptions parsed of
-- Just opts -> return opts
-- Nothing -> case parsedError parsed of
-- Just err -> do
-- hPutStrLn stderr (parsedHelp parsed)
-- hPutStrLn stderr err
-- exitFailure
-- Nothing -> do
-- hPutStr stdout (parsedHelp parsed)
-- exitSuccess
--
parseOptions :: Options opts => [String] -> ParsedOptions opts
-- | See parseSubcommand.
data ParsedSubcommand action
-- | Get the subcommand action that was parsed from argv, or
-- Nothing if the arguments could not be converted into a valid
-- action.
--
-- Note: This function return Nothing if the user provided a
-- help flag. To check whether an error occured during parsing, check the
-- value of parsedError.
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
-- getArgs.
--
-- Use parsedSubcommand, parsedError, and
-- parsedHelp to inspect the result of
-- parseSubcommand.
--
-- Example:
--
--
-- runSubcommand :: Options cmdOpts => [Subcommand cmdOpts (IO a)] -> IO a
-- runSubcommand subcommands = do
-- argv <- System.Environment.getArgs
-- let parsed = parseSubcommand subcommands argv
-- case parsedSubcommand parsed of
-- Just cmd -> cmd
-- Nothing -> case parsedError parsed of
-- Just err -> do
-- hPutStrLn stderr (parsedHelp parsed)
-- hPutStrLn stderr err
-- exitFailure
-- Nothing -> do
-- hPutStr stdout (parsedHelp parsed)
-- exitSuccess
--
parseSubcommand :: Options cmdOpts => [Subcommand cmdOpts action] -> [String] -> ParsedSubcommand action
instance Parsed (ParsedSubcommand a)
instance Parsed (ParsedOptions a)
instance Monad (ParserM optType)
instance Monad OptionsM