option package:configuration-tools

Builder for an option using the given reader. This is a regular option, and should always have either a long or short name specified in the modifiers (or both).

nameParser = option str ( long "name" <> short 'n' )

One or none. It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int

>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> final
Left "it failed"

>>> runExcept $ optional canFail *> final
Right 42

Options parser for configuration

Lens for simultaneous query and update of piOptionParser and piDefaultConfiguration. This supports to change the type of ProgramInfoValidate' with over and set.

An option that always fails. When this option is encountered, the option parser immediately aborts with the given parse error. If you simply want to output a message, use infoOption instead.

The boolOption is an alternative to switch. Using switch with command line parsers that overwrite settings from a configuration file is problematic: the absence of the switch is interpreted as setting the respective configuration value to False. So there is no way to specify on the command line that the value from the configuration file shall be used. Some command line UIs use two different options for those values, for instance --enable-feature and --disable-feature. This option instead expects a Boolean value. Beside that it behaves like any other option.

An alternative syntax for boolOption for options with long names. Instead of taking a boolean argument the presence of the option acts as a switch to set the respective configuration setting to True. If the option is not present the setting is left unchanged. In addition for long option names a respective unset flag is provided. For instance for a flag --verbose there will also be a flag --no-verbose. This can still be used with short option names only, but no unset flag would be provided.

An option that expects a file name.

Intersperse matched options and arguments normally, but allow unmatched options to be treated as positional arguments. This is sometimes useful if one is wrapping a third party cli tool and needs to pass options through, while also providing a handful of their own options. Not recommended in general as typos by the user may not yield a parse error and cause confusion.

An option that always fails and displays a message.

An option that expects a JSON value as argument.

Builder for an option taking a String argument.

Command line parser for record Maybe values

Example:

data Setting = Setting
{ _setA ∷ !Int
, _setB ∷ !String
}
deriving (Show, Read, Eq, Ord, Typeable)

$(makeLenses ''Setting)

defaultSetting ∷ Setting
defaultSetting = Setting
{ _setA = 0
, _setB = 1
}

instance ToJSON Setting where
toJSON setting = object
[ "a" .= _setA setting
, "b" .= _setB setting
]

instance FromJSON (Setting → Setting) where
parseJSON = withObject "Setting" $ \o → id
<$< setA ..: "a" % o
<*< setB ..: "b" % o

instance FromJSON Setting where
parseJSON v = parseJSON v <*> pure defaultSetting

pSetting ∷ MParser Setting
pSetting = id
<$< setA .:: option auto
% short 'a'
<> metavar "INT"
<> help "set a"
<*< setB .:: option auto
% short 'b'
<> metavar "INT"
<> help "set b"

-- | Use 'Setting' as 'Maybe' in a configuration:
--
data Config = Config
{ _maybeSetting ∷ !(Maybe Setting)
}
deriving (Show, Read, Eq, Ord, Typeable)

$(makeLenses ''Config)

defaultConfig ∷ Config
defaultConfig = Config
{ _maybeSetting = defaultSetting
}

instance ToJSON Config where
toJSON config = object
[ "setting" .= maybeSetting
]

instance FromJSON (Config → Config) where
parseJSON = withObject "Config" $ \o → id
<$< maybeSetting %.: "setting" % o

pConfig ∷ MParser Config
pConfig = id
<$< maybeSetting %:: (maybeOption defaultSetting
<$> pEnableSetting
<*> pSetting)
where
pEnableSetting = boolOption
% long "setting-enable"
<> value False
<> help "Enable configuration flags for setting"