@@ -9,16 +9,19 @@
99--
1010-- On a historical note, this code was taken directly from the yesod web framework's configuration module.
1111module Data.Yaml.Config
12− ( applyCurrentEnv
13− , getCurrentEnv
14− , applyEnvValue
15− , loadYamlSettings
12+ ( -- * High-level
13+ loadYamlSettings
14+ -- ** EnvUsage
1615 , EnvUsage
1716 , ignoreEnv
1817 , useEnv
1918 , requireEnv
2019 , useCustomEnv
2120 , requireCustomEnv
21+ -- * Lower level
22+ , applyCurrentEnv
23+ , getCurrentEnv
24+ , applyEnvValue
2225 ) where
2326
2427
@@ -50,6 +53,14 @@ mergeValues :: Value -> Value -> Value
5053mergeValues (Object x) (Object y) = Object $ H.unionWith mergeValues x y
5154mergeValues x _ = x
5255
56+-- | Override environment variable placeholders in the given @Value@ with
57+-- values from the environment.
58+--
59+-- If the first argument is @True@, then all placeholders _must_ be provided by
60+-- the actual environment. Otherwise, default values from the @Value@ will be
61+-- used.
62+--
63+-- @since 0.8.16
5364applyEnvValue :: Bool -- ^ require an environment variable to be present?
5465 -> H.HashMap Text Text -> Value -> Value
5566applyEnvValue requireEnv' env =
@@ -82,26 +93,62 @@ applyEnvValue requireEnv' env =
8293
8394 parseValue val = fromMaybe (String val) $ Y.decode $ encodeUtf8 val
8495
96+-- | Get the actual environment as a @HashMap@ from @Text@ to @Text@.
97+--
98+-- @since 0.8.16
8599getCurrentEnv :: IO (H.HashMap Text Text)
86100getCurrentEnv = fmap (H.fromList . map (pack *** pack)) getEnvironment
87101
102+-- | A convenience wrapper around 'applyEnvValue' and 'getCurrentEnv'
103+--
104+-- @since 0.8.16
88105applyCurrentEnv :: Bool -- ^ require an environment variable to be present?
89106 -> Value -> IO Value
90107applyCurrentEnv requireEnv' orig = flip (applyEnvValue requireEnv') orig <$> getCurrentEnv
91108
109+-- | Defines how we want to use the environment variables when loading a config
110+-- file. Use the smart constructors provided by this module.
111+--
112+-- @since 0.8.16
92113data EnvUsage = IgnoreEnv
93114 | UseEnv
94115 | RequireEnv
95116 | UseCustomEnv (H.HashMap Text Text)
96117 | RequireCustomEnv (H.HashMap Text Text)
97118
98−ignoreEnv, useEnv, requireEnv :: EnvUsage
119+-- | Do not use any environment variables, instead relying on defaults values
120+-- in the config file.
121+--
122+-- @since 0.8.16
123+ignoreEnv :: EnvUsage
99124ignoreEnv = IgnoreEnv
125+
126+-- | Use environment variables when available, otherwise use defaults.
127+--
128+-- @since 0.8.16
129+useEnv :: EnvUsage
100130useEnv = UseEnv
131+
132+-- | Do not use default values from the config file, but instead take all
133+-- overrides from the environment. If a value is missing, loading the file will
134+-- throw an exception.
135+--
136+-- @since 0.8.16
137+requireEnv :: EnvUsage
101138requireEnv = RequireEnv
102139
103−useCustomEnv, requireCustomEnv :: H.HashMap Text Text -> EnvUsage
140+-- | Same as 'useEnv', but instead of the actual environment, use the provided
141+-- @HashMap@ as the environment.
142+--
143+-- @since 0.8.16
144+useCustomEnv :: H.HashMap Text Text -> EnvUsage
104145useCustomEnv = UseCustomEnv
146+
147+-- | Same as 'requireEnv', but instead of the actual environment, use the
148+-- provided @HashMap@ as the environment.
149+--
150+-- @since 0.8.16
151+requireCustomEnv :: H.HashMap Text Text -> EnvUsage
105152requireCustomEnv = RequireCustomEnv
106153
107154-- | Load the settings from the following three sources:
@@ -111,6 +158,13 @@ requireCustomEnv = RequireCustomEnv
111158-- * Run time environment variables
112159--
113160-- * The default compile time config file
161+--
162+-- For example, to load up settings from @config/foo.yaml@ and allow overriding
163+-- from the actual environment, you can use:
164+--
165+-- > loadYamlSettings ["config/foo.yaml"] [] useEnv
166+--
167+-- @since 0.8.16
114168loadYamlSettings
115169 :: FromJSON settings
116170 => [FilePath] -- ^ run time config files to use, earlier files have precedence