OptEnvConf

settings are the building blocks of Parsers.

setting lets you put together different builders to define what to parse.

Here are some common examples:

• Argument

  setting
     [ help "Document your argument"
     , reader str -- The argument is a string
     , argument
     ] :: Parser String
  

• Switch

  setting
     [ help "Document your switch"
     , switch True -- The value of the switch when activated
     , long foo -- "--foo"
     , short f -- "-f"
     , value False -- The default value of the switch
     ] :: Parser Bool
  

• Option

  setting
     [ help "Document your option"
     , reader str -- The argument is a string
     , long foo -- "--foo"
     , short f -- "-f"
     , option
     ] :: Parser String
  

• Environment Variable

  setting
     [ help "Document your environment variable"
     , reader str -- The argument is a string
     , env FOO_BAR
     ] :: Parser String
  

• Configuration Value

  setting
     [ help "Document your configuration value"
     , conf "foo-bar"
     ] :: Parser String
  

• Some combination

  setting
     [ help "Document your configuration value"
     , conf "foo-bar"
     ] :: Parser String
  

  Note that parsing is always tried in this order when using a combined setting:

  1. Argument

  2. Switch

  3. Option

  4. Environment variable

  5. Configuration value

  (Hence the name of the package.)

A setting for Path Abs File.

This takes care of setting the reader to str, setting the metavar to FILE_PATH, autocompletion, and parsing the FilePath into a Path Abs File.

A setting for Path Abs dir.

This takes care of setting the reader to str, setting the metavar to DIRECTORY_PATH, autocompletion, and parsing the FilePath into a Path Abs Dir.

Document a setting

Multiple helps concatenate help on new lines.

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

Try to parse an argument.

You'll also need to add a reader.

Multiple arguments are redundant.

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.

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.

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.

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.

Try to parse an environment variable.

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

Multiple envs will be tried in order.

Like env but ignores any subEnv, subEnv_, or subAll.

Try to parse a configuration value at the given key.

Multiple confs will be tried in order.

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

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

Like conf but ignores any subConf, subConf_, or subAll.

Like confWith but ignores any subConf, subConf_, or subAll.

Like confWith' but ignores any subConf, subConf_, or subAll.

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

Multiple names will be tried in order.

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.

Don't show this setting in documentation

Multiple hiddens are redundant.

Document an option or env var.

Multiple metavars override eachother.

Set the setting to tab-complete with the given completer

Multiple completers are redundant.

Declare multiple commands

Use command to define a Command.

Declare a single command with a name, documentation and parser

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 *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> NothingNothing

>>> show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17Left 17

>>> show <$> Right 17Right "17"

Double each element of a list:

>>> (*2) <$> [1,2,3][2,4,6]

Apply even to the second element of a pair:

>>> even <$> (2,2)(2,True)

Sequential application.

A few functors support an implementation of <*> that is more efficient than the default one.

Example

Used in combination with (Data.Functor.<$>), (<*>) can be used to build a record.

>>> data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}

>>> produceFoo :: Applicative f => f Foo>>> produceBar :: Applicative f => f Bar>>> produceBaz :: Applicative f => f Baz

>>> mkState :: Applicative f => f MyState>>> mkState = MyState <$> produceFoo <*> produceBar <*> produceBaz

An associative binary operation

Zero or more.

Examples

>>> many (putStr "la")lalalalalalalalala... * goes on forever *

>>> many NothingJust []

>>> take 5 <$> many (Just 1)* hangs forever *

Note that this function can be used with Parsers based on Applicatives. In that case many parser will attempt to parse parser zero or more times until it fails.

One or more.

Examples

>>> some (putStr "la")lalalalalalalalala... * goes on forever *

>>> some Nothingnothing

>>> take 5 <$> some (Just 1)* hangs forever *

Note that this function can be used with Parsers based on Applicatives. In that case some parser will attempt to parse parser one or more times until it fails.

Prefix all longs and shorts with a given String.

Helper function for calling subArgs with toArgCase and a - appended.

subArgs_ s = subArgs (toArgCase s <> "-")

Prefix all envs with a given String.

Helper function for calling subEnv with toEnvCase and a _ appended.

subEnv_ s = subEnv (toEnvCase s <> "_")

Prefix all confs with a given String.

Helper function for calling subConfig with toConfigCase.

subConfig_ s = subConfig (toConfigCase s)

Helper function for calling subArgs_, subEnv_ and subConfig_ with the same prefix.

subAll = subArgs_ prefix . subEnv_ prefix . subConfig_ prefix

Use the settingsParser of a given type, but prefixed with a subAll and allOrNothing.

subSettings prefix = allOrNothing $ subAll prefix settingsParser

Parse either all or none of the parser below.

If you don't use this function, and only some of the settings below are defined, this parser will fail and the next alternative will be tried. If you do use this function, this parser will error unforgivably if at least one, but not all, of the settings below are defined.

If each setting has a corresponding forgivable error, consider this forgivable. Consider all other forgivable errors unforgivable

For example, the following will parser will fail intsead of succeed when given the arguments below:

( choice
    [ allOrNothing $
        (,)
          <$> setting [option, long "foo", reader auto, help "This one will exist", metavar "CHAR"]
          <*> setting [option, long "bar", reader auto, help "This one will not exist", metavar "CHAR"],
      pure ('a', 'b')
    ]
)

["--foo", "'a'"]

Turn a string into arg case for option names

Example: this-is-arg-case

Turn a string into env case for environment variable names

Example: THIS_IS_ENV_CASE

Turn a string into config case for configuration value names

Example: this-is-config-case

Like some but with a more accurate type

Like checkMapEither but without changing the type

Like checkMapMaybe but without changing the type

Check a Parser after the fact, purely.

Check a Parser after the fact, allowing IO.

Like checkMapEither but without a helpful error message.

Prefer checkMapEither.

Like checkMapEither, but allow trying the other side of any alternative if the result is Nothing.

Like checkMapIO, but allow trying the other side of any alternative if the result is Nothing. TODO add a SRCLoc here

Like checkMapMaybe, but allow trying the other side of any alternative if the result is Nothing.

Like checkMapEither but without a helpful error message.

Prefer checkMapEither.

Apply a computation to the result of a parser

This is intended for use-cases like resolving a file to an absolute path. It is morally ok for read-only IO actions but you will have a bad time if the action is not read-only.

Try a list of parsers in order

Give a parser a default value.

This is morally equal to (| pure a) but will give you better documentation of the default value in many cases.

This does nothing if the parser already has a default value.

Like withDefault but lets you specfiy how to show the default value yourself.

Load a configuration value and use it for the given parser

Load a YAML config file and use it for the given parser

Load the Yaml config in the first of the filepaths that points to something that exists.

Combine all Yaml config files that exist into a single combined config object.

Load config.yaml from the given XDG configuration subdirectory

Load a config file that is reconfigurable with an option and environment variable but config.yaml in the local working directory by default.

Use the given Parser for deciding which configuration file to load, but only if configuredConfigFile fails to define it first.

Don't load any configuration, but still shut up lint errors about conf being used without defining any way to load configuration.

This may be useful if you use a library's Parser that uses conf but do not want to parse any configuration.

Define a setting for a Bool with a given default value.

If you pass in long values, it will have --enable-foobar and --disable-foobar switches. If you pass in env values, it will read those environment variables too. If you pass in conf values, it will read those configuration values too. If you pass in a value value, it will use that as the default value.

Define a setting for a Bool with a given default value.

If you pass in long values, it will have --foobar and --no-foobar switches. If you pass in env values, it will read those environment variables too. If you pass in conf values, it will read those configuration values too. If you pass in a value value, it will use that as the default value.

Read a text file but strip whitespace so it can be edited with an editor that messes with line endings.

Load a secret from a text file, with readSecretTextFile

Load a secret from a text file, with readSecretTextFile, or specify it directly

A setting with option, a reader set to str, and the metavar set to STR.

Note that you can override the metavar with another metavar in the given list of builders.

This function may help with easier migration from optparse-applicative.

A setting with argument, a reader set to str, and the metavar set to STR.

Note that you can override the metavar with another metavar in the given list of builders.

This function may help with easier migration from optparse-applicative.

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.

Read via the Read instance

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

Always return True

exists = Reader $ const $ pure True

Turn a Maybe parsing function into a Reader

Turn an Either parsing function into a Reader

API note: This is a forward-compatible alias for Reader.

Like commaSeparated but uses a list type.

Note that this will never parse the empty list, so prefer commaSeparated if you want a more accurately typed function.

Turn a reader into one that parses comma separated values with that reader.

Like commaSeparated but uses a set type.

Note that this will never parse the empty list, so prefer commaSeparated if you want a more accurately typed function.

Note also that this function throws away any ordering information and ignores any duplicate values.