Safe Haskell	None
Language	Haskell2010

OptEnvConf.Setting

Contents

Builders
Internal

Synopsis

data Setting a = Setting {
- settingDasheds :: ![Dashed]
- settingReaders :: ![Reader a]
- settingTryArgument :: !Bool
- settingSwitchValue :: !(Maybe a)
- settingTryOption :: !Bool
- settingEnvVars :: !(Maybe (NonEmpty String))
- settingConfigVals :: !(Maybe (NonEmpty (ConfigValSetting a)))
- settingDefaultValue :: !(Maybe (a, String))
- settingExamples :: ![String]
- settingHidden :: !Bool
- settingMetavar :: !(Maybe Metavar)
- settingHelp :: !(Maybe String)
}
data ConfigValSetting a = ConfigValSetting {
- configValSettingPath :: !(NonEmpty String)
- configValSettingCodec :: !(ValueCodec void (Maybe a))
}
help :: String -> Builder a
metavar :: String -> Builder a
argument :: Builder a
option :: Builder a
switch :: a -> Builder a
reader :: Reader a -> Builder a
str :: IsString s => Reader s
auto :: Read a => Reader a
long :: String -> Builder a
short :: Char -> Builder a
env :: String -> Builder a
conf :: HasCodec a => String -> Builder a
confWith :: String -> ValueCodec void a -> Builder a
confWith' :: String -> ValueCodec void (Maybe a) -> Builder a
name :: HasCodec a => String -> Builder a
value :: Show a => a -> Builder a
valueWithShown :: (a -> String) -> a -> Builder a
example :: String -> Builder a
shownExample :: Show a => a -> Builder a
hidden :: Builder a
newtype Builder a = Builder {
- unBuilder :: [BuildInstruction a]
}
data BuildInstruction a
- = BuildAddHelp !String
- | BuildSetMetavar !String
- | BuildTryArgument
- | BuildTryOption
- | BuildSetSwitchValue !a
- | BuildAddReader !(Reader a)
- | BuildAddLong !(NonEmpty Char)
- | BuildAddShort !Char
- | BuildAddEnv !String
- | BuildAddConf !(ConfigValSetting a)
- | BuildSetDefault !a !String
- | BuildAddExample !String
- | BuildSetHidden
showSettingABit :: Setting a -> ShowS
newtype SettingHash = SettingHash Int
hashSetting :: Setting a -> SettingHash
completeBuilder :: Builder a -> Setting a
mapMaybeBuilder :: (BuildInstruction a -> Maybe (BuildInstruction b)) -> Builder a -> Builder b
emptySetting :: Setting a
type Metavar = String
type Help = String
prefixConfigValSetting :: String -> ConfigValSetting a -> ConfigValSetting a
suffixConfigValSettingKey :: String -> ConfigValSetting a -> ConfigValSetting a

Documentation

data Setting a Source #

A setting for parsing and documenting a single value.

Constructors

Setting

Fields

settingDasheds :: ![Dashed]
Which dashed values are required for parsing
No dashed values means this is an argument.
settingReaders :: ![Reader a]
Which readers should be tried to parse a value from a string
settingTryArgument :: !Bool
Whether the readers should be used to parsed arguments
settingSwitchValue :: !(Maybe a)
What value to parse when the switch exists.
Nothing means this is not a switch.
settingTryOption :: !Bool
Whether the dasheds should be tried together with the readers as options.
settingEnvVars :: !(Maybe (NonEmpty String))
Which env vars can be read.
settingConfigVals :: !(Maybe (NonEmpty (ConfigValSetting a)))
Which and how to parse config values
settingDefaultValue :: !(Maybe (a, String))
Default value, if none of the above find the setting.
settingExamples :: ![String]
Example values
settingHidden :: !Bool
Whether to hide docs
settingMetavar :: !(Maybe Metavar)
Which metavar should be show in documentation
settingHelp :: !(Maybe String)

data ConfigValSetting a Source #

Constructors

ConfigValSetting
Fields configValSettingPath :: !(NonEmpty String) configValSettingCodec :: !(ValueCodec void (Maybe a))

Builders

help :: String -> Builder a Source #

Document a setting

Multiple helps concatenate help on new lines.

metavar :: String -> Builder a Source #

Document an option or env var.

Multiple metavars override eachother.

argument :: Builder a Source #

Try to parse an argument.

You'll also need to add a reader.

Multiple arguments are redundant.

option :: Builder a Source #

Try to parse an argument.

You'll also need to add a reader, at least one long or short, and a metavar.

Multiple options are redundant.

switch :: a -> Builder a Source #

Try to parse a switch, activate the given value when succesful

You'll also need to add at least one long or short.

Multiple switchs override eachother.

reader :: Reader a -> Builder a Source #

Declare how to parse an argument, option, or environment variable.

str :: IsString s => Reader s Source #

Read a string as-is.

This is the reader you will want to use for reading a String.

This is different from auto for strings because Read wants to parse quotes when parsing Strings.

auto :: Read a => Reader a Source #

Read via the Read instance

You cannot use this for bare strings, because Read for strings parses quotes.

long :: String -> Builder a Source #

Try to parse this long option or switch.

long "foo" corresponds to --foo

Notes: * Parsing options with an empty name in the long is not supported. * Parsing options with an '=' sign in the long is not supported.

Multiple longs will be tried in order. Empty longs will be ignored.

short :: Char -> Builder a Source #

Try to parse this short option or switch.

short f corresponds to -f

Notes: * Parsing options with short - is not supported.

Multiple shorts will be tried in order.

env :: String -> Builder a Source #

Try to parse an environment variable.

You'll also need to add a reader and a metavar.

Multiple envs will be tried in order.

conf :: HasCodec a => String -> Builder a Source #

Try to parse a configuration value at the given key.

Multiple confs will be tried in order.

confWith :: String -> ValueCodec void a -> Builder a Source #

Like conf but with a custom Codec for parsing the value.

confWith' :: String -> ValueCodec void (Maybe a) -> Builder a Source #

Like confWith but allows interpreting Null as a value other than "Not found".

name :: HasCodec a => String -> Builder a Source #

Short-hand function for option, long, env, and conf at the same time.

Multiple names will be tried in order.

value :: Show a => a -> Builder a Source #

Set the default value

Multiple values override eachother.

API Note: default is not a valid identifier in Haskell. I'd also have preferred default instead.

valueWithShown :: (a -> String) -> a -> Builder a Source #

Set the default value, along with version of it shown by a custom function.

example :: String -> Builder a Source #

Provide an example value for documentation.

The example is provided as a literal string.

If you use reader auto, you'll want to use shownExample instead.

shownExample :: Show a => a -> Builder a Source #

Use Show to show an example.

This only makes sense if you use reader auto.

hidden :: Builder a Source #

Don't show this setting in documentation

Multiple hiddens are redundant.

newtype Builder a Source #

Builder for a Setting

Constructors

Builder
Fields unBuilder :: [BuildInstruction a]

Instances

Instances details

Monoid (Builder f) Source #
Instance details Defined in OptEnvConf.Setting Methods mempty :: Builder f # mappend :: Builder f -> Builder f -> Builder f # mconcat :: [Builder f] -> Builder f #
Semigroup (Builder f) Source #
Instance details Defined in OptEnvConf.Setting Methods (<>) :: Builder f -> Builder f -> Builder f # sconcat :: NonEmpty (Builder f) -> Builder f # stimes :: Integral b => b -> Builder f -> Builder f #

data BuildInstruction a Source #

Internal

showSettingABit :: Setting a -> ShowS Source #

Show a Setting as much as possible, for debugging

newtype SettingHash Source #

Constructors

SettingHash Int

Instances

Instances details

Show SettingHash Source #
Instance details Defined in OptEnvConf.Setting Methods showsPrec :: Int -> SettingHash -> ShowS # show :: SettingHash -> String # showList :: [SettingHash] -> ShowS #
Eq SettingHash Source #
Instance details Defined in OptEnvConf.Setting Methods (==) :: SettingHash -> SettingHash -> Bool # (/=) :: SettingHash -> SettingHash -> Bool #
Ord SettingHash Source #
Instance details Defined in OptEnvConf.Setting Methods compare :: SettingHash -> SettingHash -> Ordering # (<) :: SettingHash -> SettingHash -> Bool # (<=) :: SettingHash -> SettingHash -> Bool # (>) :: SettingHash -> SettingHash -> Bool # (>=) :: SettingHash -> SettingHash -> Bool # max :: SettingHash -> SettingHash -> SettingHash # min :: SettingHash -> SettingHash -> SettingHash #

hashSetting :: Setting a -> SettingHash Source #

completeBuilder :: Builder a -> Setting a Source #

Complete a Builder into a Setting

mapMaybeBuilder :: (BuildInstruction a -> Maybe (BuildInstruction b)) -> Builder a -> Builder b Source #

emptySetting :: Setting a Source #

A mempty Setting to build up a setting from.

type Metavar = String Source #

type Help = String Source #

prefixConfigValSetting :: String -> ConfigValSetting a -> ConfigValSetting a Source #

suffixConfigValSettingKey :: String -> ConfigValSetting a -> ConfigValSetting a Source #

BuildAddHelp !String
BuildSetMetavar !String
BuildTryArgument
BuildTryOption
BuildSetSwitchValue !a
BuildAddReader !(Reader a)
BuildAddLong !(NonEmpty Char)
BuildAddShort !Char
BuildAddEnv !String
BuildAddConf !(ConfigValSetting a)
BuildSetDefault !a !String
BuildAddExample !String
BuildSetHidden