registry-options-0.2.0.0: application options parsing
Safe HaskellSafe-Inferred
LanguageGHC2021

Data.Registry.Options.Sources

Description

This module provides way to get option values from different sources:

  • the command line
  • the system environment variables
  • a YAML configuration file

A registry is used to bring some extensibility:

  • change the configuration file name
  • change the mapping between option names and environment variable names
  • change the mapping between options names and yaml names

Here is an example:

getLexemesWith ( -- restrict the env / config file search to the options of a given parser setOptionNames (getOptionNames parser) . -- change the config file path setConfigFilePath "~/.config" . -- change the config for retrieving environment variables based on option names setEnvironmentNames env1 . -- change the config for retrieving yaml values based on option names setYamlNames yaml1 . -- set command line arguments instead of taking them from getArgs setArguments args . -- set the priorities for the option values setPriorities [commandLineSource, yamlSource])

Synopsis

Documentation

getLexemes :: MonadIO m => m Lexemes Source #

Get lexemes

getLexemesWith :: MonadIO m => (Registry _ _ -> Registry _ _) -> m Lexemes Source #

Get lexemes with a modified registry

setOptionNames :: [Text] -> Registry _ _ -> Registry _ _ Source #

Set option names on the registry

setConfigFilePath :: Text -> Registry _ _ -> Registry _ _ Source #

Set the config file path

setEnvironmentNames :: EnvironmentNames -> Registry _ _ -> Registry _ _ Source #

Set the configuration for environment names

setYamlNames :: YamlNames -> Registry _ _ -> Registry _ _ Source #

Set the configuration for yaml names

setArguments :: [Text] -> Registry _ _ -> Registry _ _ Source #

Set arguments as if they were read from the command line

setPriorities :: [Source] -> Registry _ _ -> Registry _ _ Source #

Set source priorities

sources :: Registry _ _ Source #

Registry allowing the retrieval of Lexemes from various sources: command line, environment variable, configuration file

newtype OptionNames Source #

List of option names defined in a parser It is used to restrict the names parsed in environment variables or in a configuration file

Constructors

OptionNames 

Fields

selectValues :: Priorities -> Tag "environment" Lexemes -> Tag "yaml" Lexemes -> Tag "commandline" Lexemes -> Lexemes Source #

Select lexed option names / values according to user defined priorities

Command line

getValuesFromCommandLine :: Arguments -> Tag "commandline" Lexemes Source #

Lex the arguments coming from the command line

getCommandlineArguments :: IO Arguments Source #

By default arguments are retrieved from the base getArgs function

newtype Arguments Source #

List of strings retrieved from the command line

Constructors

Arguments 

Fields

Environment

getValuesFromEnvironment :: OptionNames -> EnvironmentNames -> IO (Tag "environment" Lexemes) Source #

Get values from the environment

data EnvironmentNames Source #

Configuration for transforming an environment name into an option name and for transforming an option name into an environment name

defaultEnvironmentNames :: EnvironmentNames Source #

Default conversion functions for environment variables names to option names fromEnvironmentName OPTION_NAME == "optionName" toEnvironmentName "optionName" == OPTION_NAME

Yaml

getValuesFromYaml :: YamlNames -> OptionNames -> Maybe YamlByteString -> IO (Tag "yaml" Lexemes) Source #

Values can be retrieved from a Yaml file

newtype YamlPath Source #

Path for a YAML document

Constructors

YamlPath 

Fields

Instances

Instances details
Monoid YamlPath Source # 
Instance details

Defined in Data.Registry.Options.Sources

Semigroup YamlPath Source # 
Instance details

Defined in Data.Registry.Options.Sources

Show YamlPath Source # 
Instance details

Defined in Data.Registry.Options.Sources

Eq YamlPath Source # 
Instance details

Defined in Data.Registry.Options.Sources

defaultYamlPath :: Maybe YamlPath Source #

Default path for a configuration file By default we don't read from a configuration file

readYamlFile :: Maybe YamlPath -> IO (Maybe YamlByteString) Source #

Read yaml as a ByteString from a configuration file

collectYamlOptions :: Node Pos -> [(YamlName, [Text])] Source #

Collect what looks like options in a YAML document i.e. any list of strings leading to a scalar

newtype YamlName Source #

A YAML name is represented by a list of keys

Constructors

YamlName 

Fields

Instances

Instances details
Show YamlName Source # 
Instance details

Defined in Data.Registry.Options.Sources

Eq YamlName Source # 
Instance details

Defined in Data.Registry.Options.Sources

data YamlNames Source #

Configuration for transforming a YAML name into an option name and for transforming an option name into a YAML name We consider that a YAML name is a sequence of string keys in a nested YAML document

Constructors

YamlNames 

defaultYamlNames :: YamlNames Source #

Default conversion functions for YAML variables names to option names We only keep in names on the leaves of the YAML tree

fromYamlName ["section", "option_name"] == "option-name" toYamlName "option-name" == ["option_name"]

Sources and priorities

newtype Priorities Source #

List of sources sorted by the highest priority to the lowest

Constructors

Priorities [Source] 

Instances

Instances details
Show Priorities Source # 
Instance details

Defined in Data.Registry.Options.Sources

Eq Priorities Source # 
Instance details

Defined in Data.Registry.Options.Sources

defaultPriorities :: Priorities Source #

By default we take environment values, then command line values, then values coming from a configuration file

sortBySource :: Priorities -> [(Source, a)] -> [a] Source #

Sort a list of values associated with a source, using Priorities to determine the order

newtype Source Source #

Source of an option value This is modelled as a simple newtype on Text in order to enable the creation of new sources

Constructors

Source Text 

Instances

Instances details
Show Source Source # 
Instance details

Defined in Data.Registry.Options.Sources

Eq Source Source # 
Instance details

Defined in Data.Registry.Options.Sources

Methods

(==) :: Source -> Source -> Bool #

(/=) :: Source -> Source -> Bool #

environmentSource :: Source Source #

Source of options values coming from the environment

commandLineSource :: Source Source #

Source of options values coming from the command line

yamlSource :: Source Source #

Source of options values coming from a YAML configuration file

Orphan instances

Exception Text Source #

Text needs to have an Exception instance in order to use throwIO

Instance details