Safe Haskell | Safe-Inferred |
---|---|
Language | GHC2021 |
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
- getLexemes :: MonadIO m => m Lexemes
- getLexemesWith :: MonadIO m => (Registry _ _ -> Registry _ _) -> m Lexemes
- setOptionNames :: [Text] -> Registry _ _ -> Registry _ _
- setConfigFilePath :: Text -> Registry _ _ -> Registry _ _
- setEnvironmentNames :: EnvironmentNames -> Registry _ _ -> Registry _ _
- setYamlNames :: YamlNames -> Registry _ _ -> Registry _ _
- setArguments :: [Text] -> Registry _ _ -> Registry _ _
- setPriorities :: [Source] -> Registry _ _ -> Registry _ _
- sources :: Registry _ _
- newtype OptionNames = OptionNames {
- _optionNames :: [Text]
- selectValues :: Priorities -> Tag "environment" Lexemes -> Tag "yaml" Lexemes -> Tag "commandline" Lexemes -> Lexemes
- getValuesFromCommandLine :: Arguments -> Tag "commandline" Lexemes
- getCommandlineArguments :: IO Arguments
- newtype Arguments = Arguments {
- _arguments :: [Text]
- getValuesFromEnvironment :: OptionNames -> EnvironmentNames -> IO (Tag "environment" Lexemes)
- data EnvironmentNames = EnvironmentNames {
- fromEnvironmentName :: Text -> Text
- toEnvironmentName :: Text -> Text
- defaultEnvironmentNames :: EnvironmentNames
- getValuesFromYaml :: YamlNames -> OptionNames -> Maybe YamlByteString -> IO (Tag "yaml" Lexemes)
- newtype YamlPath = YamlPath {}
- newtype YamlByteString = YamlByteString {}
- defaultYamlPath :: Maybe YamlPath
- readYamlFile :: Maybe YamlPath -> IO (Maybe YamlByteString)
- collectYamlOptions :: Node Pos -> [(YamlName, [Text])]
- newtype YamlName = YamlName {}
- data YamlNames = YamlNames {
- fromYamlName :: YamlName -> Text
- toYamlName :: Text -> YamlName
- defaultYamlNames :: YamlNames
- newtype Priorities = Priorities [Source]
- defaultPriorities :: Priorities
- sortBySource :: Priorities -> [(Source, a)] -> [a]
- newtype Source = Source Text
- environmentSource :: Source
- commandLineSource :: Source
- yamlSource :: Source
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
OptionNames | |
|
Instances
Monoid OptionNames Source # | |
Defined in Data.Registry.Options.Sources mempty :: OptionNames # mappend :: OptionNames -> OptionNames -> OptionNames # mconcat :: [OptionNames] -> OptionNames # | |
Semigroup OptionNames Source # | |
Defined in Data.Registry.Options.Sources (<>) :: OptionNames -> OptionNames -> OptionNames # sconcat :: NonEmpty OptionNames -> OptionNames # stimes :: Integral b => b -> OptionNames -> OptionNames # | |
Show OptionNames Source # | |
Defined in Data.Registry.Options.Sources showsPrec :: Int -> OptionNames -> ShowS # show :: OptionNames -> String # showList :: [OptionNames] -> ShowS # | |
Eq OptionNames Source # | |
Defined in Data.Registry.Options.Sources (==) :: OptionNames -> OptionNames -> Bool # (/=) :: OptionNames -> OptionNames -> Bool # |
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
List of strings retrieved from the command line
Arguments | |
|
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
EnvironmentNames | |
|
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
Path for a YAML document
newtype YamlByteString Source #
ByteString representing a YAML document
Instances
Monoid YamlByteString Source # | |
Defined in Data.Registry.Options.Sources mappend :: YamlByteString -> YamlByteString -> YamlByteString # mconcat :: [YamlByteString] -> YamlByteString # | |
Semigroup YamlByteString Source # | |
Defined in Data.Registry.Options.Sources (<>) :: YamlByteString -> YamlByteString -> YamlByteString # sconcat :: NonEmpty YamlByteString -> YamlByteString # stimes :: Integral b => b -> YamlByteString -> YamlByteString # | |
Show YamlByteString Source # | |
Defined in Data.Registry.Options.Sources showsPrec :: Int -> YamlByteString -> ShowS # show :: YamlByteString -> String # showList :: [YamlByteString] -> ShowS # | |
Eq YamlByteString Source # | |
Defined in Data.Registry.Options.Sources (==) :: YamlByteString -> YamlByteString -> Bool # (/=) :: YamlByteString -> YamlByteString -> Bool # |
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
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
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
Instances
Show Priorities Source # | |
Defined in Data.Registry.Options.Sources showsPrec :: Int -> Priorities -> ShowS # show :: Priorities -> String # showList :: [Priorities] -> ShowS # | |
Eq Priorities Source # | |
Defined in Data.Registry.Options.Sources (==) :: Priorities -> Priorities -> Bool # (/=) :: Priorities -> Priorities -> Bool # |
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
Source of an option value This is modelled as a simple newtype on Text in order to enable the creation of new sources
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 |
toException :: Text -> SomeException # fromException :: SomeException -> Maybe Text # displayException :: Text -> String # |