Add better support for environment variables

Author: Exlll

README.md

@@ -30,6 +30,7 @@ wiki!
 * Option to customize null handling
 * Option to customize serialization by providing your own serializers
 * Option to add headers and footers to configuration files
+* Option to overwrite configuration values with environment variables
 * ...and a few more!
 
 ## Usage example
@@ -502,7 +503,7 @@ serializing and deserializing a configuration:
   are treated as missing and are, therefore, handled as described in the section
   above.
 * By setting `inputNulls` to true, null values read from the configuration file
-  override the corresponding default values of a configuration class with null
+  overwrite the corresponding default values of a configuration class with null
   or set the component value of a record type to null. If the configuration
   element type is primitive, an exception is thrown.
 
@@ -943,6 +944,123 @@ ConfigurationProperties.newBuilder()
         .build();
 ```
 
+### Overwriting configuration values with environment variables
+
+You can allow users of your configuration to overwrite values that come from
+configuration files with values that are provided by environment variables.
+When a configuration is loaded, boolean values, numbers, and strings that appear
+in that configuration files can be overwritten with values that come from
+environment variables.
+
+To enable support for overwriting config values with environment variables
+first create a `ConfigurationProperties.EnvVarResolutionConfiguration` object
+and then configure your `ConfigurationProperties` instance with it:
+
+```java
+final var envVarConf = ConfigurationProperties.EnvVarResolutionConfiguration
+        .resolveEnvVarsWithPrefix(prefix, caseSensitiveResolution);
+final var properties = ConfigurationProperties.newBuilder()
+        .setEnvVarResolutionConfiguration(envVarConf)
+        // ... build
+```
+
+The `resolveEnvVarsWithPrefix` method returns a configuration object that
+resolves environment variables that start with the given prefix.
+
+If you specify a non-empty prefix, then only variables that start with that
+prefix will be resolved when loading your configuration. For example, if you
+choose `MY_PREFIX_` as your prefix, only environment variables that start
+with `MY_PREFIX_` will be able to overwrite configuration values. Specifying a
+non-empty prefix that is specific to your project is highly recommended.
+
+#### Environment variable names
+
+To be able to overwrite configuration values, you need to name your environment
+variables in a specific way (see example below):
+
+- To overwrite a boolean, number, or string value of a field, use an environment
+variable whose name matches the name of the field. The environment variable must
+be uppercase if case-sensitive resolution is disabled.
+- You can target nested elements by joining all field names that lead to that
+element with an underscore `_`.
+- You can target list elements by using the index of an element as the field name.
+
+For example, in the following configuration file
+
+```yaml
+a: 0
+b:
+  c: 1
+d:
+- 2
+- 3
+e:
+- f: 4
+  g: 5
+```
+
+`a` is a simple value, `b` is a map, `d` is a list, and `e` is a list of
+maps. Then, under the assumption that you aren't using a prefix and that
+case-sensitive resolution is disabled, you can overwrite the values from 0 to 5
+using the following environment variables, respectively:
+`A`, `B_C`, `D_0`, `D_1`, `E_0_F`, and `E_0_G`.
+
+#### Case-sensitivity
+
+**NOTE:** Environment variables are case-sensitive on UNIX systems and
+case-insensitive on Windows.
+
+If you want to (or have to, because you are on Windows) target the values of
+your configuration using uppercase environment variables (irrespective of the
+actual casing of the name of the fields), then you have to disable
+case-sensitive resolution. For example, if you have a configuration file with
+the following content
+```yaml
+alPHA:
+  be_ta: 1
+ga_mma:
+  dELTa: 2
+```
+then, with `caseSensitiveResolution` set to `false`, you can overwrite the values
+`1` and `2` using the environment variables `ALPHA_BE_TA` and `GA_MMA_DELTA`,
+respectively.
+
+If your configuration contains paths that differ only in their case but are
+otherwise the same, and if you want to target these paths individually, then
+you have to enable case-sensitive resolution. For example, if you have a
+configuration file with the following content
+```yaml
+alpha:
+  beta: 1
+ALPHA:
+  BETA: 2
+```
+and you want to target the values of `beta` and `BETA` individually, then you
+have to set `caseSensitiveResolution` to `true`. After doing so you can
+overwrite the values `1` and `2` by using the environment variables `alpha_beta`
+and `ALPHA_BETA`, respectively.
+
+#### Restrictions
+
+The values provided by environment variables come as strings and need to be
+converted to the correct target type. Because the resolution of environment
+variables happens very early in the process (before the type information of the
+configuration type is available) there are a few restrictions on how
+environment variables are resolved and which values can be overwritten:
+
+- Environment variables can only be used to overwrite simple values.
+  Trying to overwrite a collection or map will cause an exception.
+- Environment variables cannot be used to insert new values into collections
+  or maps.
+- Overwriting `null` values is not possible because `null`s don't carry any type
+  information.
+- To overwrite a boolean value, an environment variable must be assigned the
+  string `true` or `false` (using any casing).
+- Numbers that, when a configuration file is read, are interpreted as integers
+  (because they don't contain a decimal point), (currently) cannot be overwritten
+  by floating point numbers. This applies even if the configuration type actually
+  expects a floating point number.
+
 ### Changing the type of configuration elements
 
 Changing the type of configuration elements is not supported. If you change the

configlib-core/src/main/java/de/exlll/configlib/ConfigurationProperties.java

@@ -1,10 +1,7 @@
 package de.exlll.configlib;
 
 import java.lang.reflect.Type;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.LinkedHashMap;
-import java.util.Map;
+import java.util.*;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.UnaryOperator;
@@ -28,6 +25,7 @@ public class ConfigurationProperties {
     private final boolean outputNulls;
     private final boolean inputNulls;
     private final boolean serializeSetsAsLists;
+    private final EnvVarResolutionConfiguration envVarResolutionConfiguration;
 
     /**
      * Constructs a new instance of this class with values taken from the given builder.
@@ -49,6 +47,10 @@ protected ConfigurationProperties(Builder<?> builder) {
         this.outputNulls = builder.outputNulls;
         this.inputNulls = builder.inputNulls;
         this.serializeSetsAsLists = builder.serializeSetsAsLists;
+        this.envVarResolutionConfiguration = requireNonNull(
+                builder.envVarResolutionConfiguration,
+                "environment variable resolution configuration"
+        );
     }
 
     /**
@@ -100,9 +102,18 @@ public static abstract class Builder<B extends Builder<B>> {
         private boolean outputNulls = false;
         private boolean inputNulls = false;
         private boolean serializeSetsAsLists = true;
+        private EnvVarResolutionConfiguration envVarResolutionConfiguration
+                = EnvVarResolutionConfiguration.disabled();
 
+        /** Default constructor */
         protected Builder() {}
 
+        /**
+         * A constructor that initializes the values of this builder with the values
+         * of the given {@code ConfigurationProperties} object.
+         *
+         * @param properties the properties used to initialize the values of this builder
+         */
         protected Builder(ConfigurationProperties properties) {
             this.serializersByType.putAll(properties.serializersByType);
             this.serializerFactoriesByType.putAll(properties.serializerFactoriesByType);
@@ -113,6 +124,7 @@ protected Builder(ConfigurationProperties properties) {
             this.outputNulls = properties.outputNulls;
             this.inputNulls = properties.inputNulls;
             this.serializeSetsAsLists = properties.serializeSetsAsLists;
+            this.envVarResolutionConfiguration = properties.envVarResolutionConfiguration;
         }
 
         /**
@@ -289,6 +301,26 @@ final B serializeSetsAsLists(boolean serializeSetsAsLists) {
             return getThis();
         }
 
+        /**
+         * Configures whether and how environment variables should be resolved.
+         * <p>
+         * The default is {@link EnvVarResolutionConfiguration#disabled()} which
+         * is a configuration that disables the resolution of environment variables.
+         *
+         * @param configuration the {@code EnvVarResolutionConfiguration}
+         * @return this builder
+         * @throws NullPointerException if {@code configuration} is null
+         */
+        public final B setEnvVarResolutionConfiguration(
+                EnvVarResolutionConfiguration configuration
+        ) {
+            this.envVarResolutionConfiguration = requireNonNull(
+                    configuration,
+                    "environment variable resolution configuration"
+            );
+            return getThis();
+        }
+
         /**
          * Builds a {@code ConfigurationProperties} instance.
          *
@@ -304,6 +336,139 @@ final B serializeSetsAsLists(boolean serializeSetsAsLists) {
         protected abstract B getThis();
     }
 
+    /**
+     * A collection of values used to configure the resolution of environment variables.
+     */
+    public static final class EnvVarResolutionConfiguration {
+        private static final EnvVarResolutionConfiguration DISABLED =
+                new EnvVarResolutionConfiguration();
+        private final boolean resolveEnvVars;
+        private final String prefix;
+        private final boolean caseSensitive;
+
+        /**
+         * Returns a configuration object that disables the resolution of
+         * environment variables.
+         *
+         * @return configuration object that disables the resolution of
+         * environment variables.
+         */
+        public static EnvVarResolutionConfiguration disabled() {
+            return DISABLED;
+        }
+
+        /**
+         * Returns a configuration object that resolves environment variables
+         * that start with the given prefix. Specifying a non-empty prefix that
+         * is specific to your project is highly recommended.
+         * <p>
+         * On UNIX systems environment variables are case-sensitive.
+         * On Windows they are case-insensitive.
+         * <ul>
+         * <li>
+         * If you want to (or have to, because you are on Windows) target the
+         * values of your configuration using uppercase environment variables,
+         * then you have to disable case-sensitive resolution.
+         * <p>
+         * For example, if you have a YAML configuration with the following content
+         * <pre>
+         * alPHA:
+         *   be_ta: 1
+         * ga_mma:
+         *   dELTa: 2
+         * </pre>
+         * then, with {@code caseSensitive} set to {@code false}, you can overwrite
+         * the values 1 and 2 using the environment variables
+         * {@code ALPHA_BE_TA} and {@code GA_MMA_DELTA}, respectively.
+         * </li>
+         * <li>
+         * If your configuration contains paths that differ only in their case,
+         * but are otherwise the same, and if you want to target these paths
+         * individually, then you have to enable case-sensitive resolution.
+         * <p>
+         * For example, if you have a YAML configuration with the following content
+         * <pre>
+         * alpha:
+         *   beta: 1
+         * ALPHA:
+         *   BETA: 2
+         * </pre>
+         * and you want to target the values of {@code beta} and {@code BETA}
+         * individually, then you have to set {@code caseSensitive} to {@code true}.
+         * After doing so you can overwrite the values 1 and 2 by using the environment
+         * variables {@code alpha_beta} and {@code ALPHA_BETA}, respectively.
+         * </li>
+         * <li>
+         * If you specify a non-empty prefix, then all variables that you want to
+         * be resolved have to start with that prefix. For example, if you choose
+         * {@code MY_PREFIX_} as your prefix, then the four variables listed
+         * above have to be named {@code MY_PREFIX_ALPHA_BE_TA},
+         * {@code MY_PREFIX_GA_MMA_DELTA}, {@code MY_PREFIX_alpha_beta}, and
+         * {@code MY_PREFIX_ALPHA_BETA}, respectively.
+         * </li>
+         * </ul>
+         *
+         * @param prefix        string the environment variables have to be prefixed with
+         * @param caseSensitive specifies whether the resolution should be case-sensitive
+         * @return configuration object that resolves environment variables
+         * that start with the given prefix
+         * @throws NullPointerException if {@code prefix} is null
+         */
+        public static EnvVarResolutionConfiguration resolveEnvVarsWithPrefix(
+                String prefix,
+                boolean caseSensitive
+        ) {
+            return new EnvVarResolutionConfiguration(true, prefix, caseSensitive);
+        }
+
+        private EnvVarResolutionConfiguration() {
+            this(false, "", false);
+        }
+
+        // create 'Builder' class if more configuration options are added
+        private EnvVarResolutionConfiguration(
+                boolean resolveEnvVars,
+                String prefix,
+                boolean caseSensitive
+        ) {
+            this.resolveEnvVars = resolveEnvVars;
+            this.prefix = requireNonNull(prefix, "prefix");
+            this.caseSensitive = caseSensitive;
+        }
+
+        /**
+         * Returns whether environment variables should be resolved.
+         *
+         * @return whether environment variables should be resolved
+         */
+        public boolean resolveEnvVars() {
+            return resolveEnvVars;
+        }
+
+        /**
+         * Returns the string with which the environment variables must begin
+         * in order to be resolved.
+         *
+         * @return the string environment variables have to begin with to be resolved
+         * @see EnvVarResolutionConfiguration#resolveEnvVarsWithPrefix(String, boolean)
+         */
+        public String prefix() {
+            return prefix;
+        }
+
+        /**
+         * Returns whether the resolution of environment variables should be
+         * case-sensitive.
+         *
+         * @return whether the resolution of environment variables should be
+         * case-sensitive
+         * @see EnvVarResolutionConfiguration#resolveEnvVarsWithPrefix(String, boolean)
+         */
+        public boolean caseSensitive() {
+            return caseSensitive;
+        }
+    }
+
     /**
      * Returns the field filter used to filter the fields of a configuration class.
      *
@@ -388,4 +553,14 @@ public final boolean inputNulls() {
     final boolean serializeSetsAsLists() {
         return serializeSetsAsLists;
     }
+
+    /**
+     * Returns the configuration that determines whether and how environment
+     * variables should be resolved.
+     *
+     * @return the configuration
+     */
+    public final EnvVarResolutionConfiguration getEnvVarResolutionConfiguration() {
+        return envVarResolutionConfiguration;
+    }
 }