001/**
002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
003 */
004package com.typesafe.config;
005
006/**
007 * A set of options related to resolving substitutions. Substitutions use the
008 * <code>${foo.bar}</code> syntax and are documented in the <a
009 * href="https://github.com/typesafehub/config/blob/master/HOCON.md">HOCON</a>
010 * spec.
011 * <p>
012 * Typically this class would be used with the method
013 * {@link Config#resolve(ConfigResolveOptions)}.
014 * <p>
015 * This object is immutable, so the "setters" return a new object.
016 * <p>
017 * Here is an example of creating a custom {@code ConfigResolveOptions}:
018 * 
019 * <pre>
020 *     ConfigResolveOptions options = ConfigResolveOptions.defaults()
021 *         .setUseSystemEnvironment(false)
022 * </pre>
023 * <p>
024 * In addition to {@link ConfigResolveOptions#defaults}, there's a prebuilt
025 * {@link ConfigResolveOptions#noSystem} which avoids looking at any system
026 * environment variables or other external system information. (Right now,
027 * environment variables are the only example.)
028 */
029public final class ConfigResolveOptions {
030    private final boolean useSystemEnvironment;
031    private final boolean allowUnresolved;
032
033    private ConfigResolveOptions(boolean useSystemEnvironment, boolean allowUnresolved) {
034        this.useSystemEnvironment = useSystemEnvironment;
035        this.allowUnresolved = allowUnresolved;
036    }
037
038    /**
039     * Returns the default resolve options. By default the system environment
040     * will be used and unresolved substitutions are not allowed.
041     * 
042     * @return the default resolve options
043     */
044    public static ConfigResolveOptions defaults() {
045        return new ConfigResolveOptions(true, false);
046    }
047
048    /**
049     * Returns resolve options that disable any reference to "system" data
050     * (currently, this means environment variables).
051     *
052     * @return the resolve options with env variables disabled
053     */
054    public static ConfigResolveOptions noSystem() {
055        return defaults().setUseSystemEnvironment(false);
056    }
057
058    /**
059     * Returns options with use of environment variables set to the given value.
060     *
061     * @param value
062     *            true to resolve substitutions falling back to environment
063     *            variables.
064     * @return options with requested setting for use of environment variables
065     */
066    public ConfigResolveOptions setUseSystemEnvironment(boolean value) {
067        return new ConfigResolveOptions(value, allowUnresolved);
068    }
069
070    /**
071     * Returns whether the options enable use of system environment variables.
072     * This method is mostly used by the config lib internally, not by
073     * applications.
074     *
075     * @return true if environment variables should be used
076     */
077    public boolean getUseSystemEnvironment() {
078        return useSystemEnvironment;
079    }
080
081    /**
082     * Returns options with "allow unresolved" set to the given value. By
083     * default, unresolved substitutions are an error. If unresolved
084     * substitutions are allowed, then a future attempt to use the unresolved
085     * value may fail, but {@link Config#resolve(ConfigResolveOptions)} itself
086     * will not throw.
087     * 
088     * @param value
089     *            true to silently ignore unresolved substitutions.
090     * @return options with requested setting for whether to allow substitutions
091     * @since 1.2.0
092     */
093    public ConfigResolveOptions setAllowUnresolved(boolean value) {
094        return new ConfigResolveOptions(useSystemEnvironment, value);
095    }
096
097    /**
098     * Returns whether the options allow unresolved substitutions. This method
099     * is mostly used by the config lib internally, not by applications.
100     * 
101     * @return true if unresolved substitutions are allowed
102     * @since 1.2.0
103     */
104    public boolean getAllowUnresolved() {
105        return allowUnresolved;
106    }
107}