    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006import java.io.File;
    007import java.io.Reader;
    008import java.net.MalformedURLException;
    009import java.net.URL;
    010import java.util.Map;
    011import java.util.Properties;
    012import java.util.concurrent.Callable;
    013
    014import com.typesafe.config.impl.ConfigImpl;
    015import com.typesafe.config.impl.Parseable;
    016
    017/**
    018 * Contains static methods for creating {@link Config} instances.
    019 *
    020 * <p>
    021 * See also {@link ConfigValueFactory} which contains static methods for
    022 * converting Java values into a {@link ConfigObject}. You can then convert a
    023 * {@code ConfigObject} into a {@code Config} with {@link ConfigObject#toConfig}.
    024 *
    025 * <p>
    026 * The static methods with "load" in the name do some sort of higher-level
    027 * operation potentially parsing multiple resources and resolving substitutions,
    028 * while the ones with "parse" in the name just create a {@link ConfigValue}
    029 * from a resource and nothing else.
    030 *
    031 * <p> You can find an example app and library <a
    032 * href="https://github.com/typesafehub/config/tree/master/examples">on
    033 * GitHub</a>.  Also be sure to read the <a
    034 * href="package-summary.html#package_description">package
    035 * overview</a> which describes the big picture as shown in those
    036 * examples.
    037 */
    038public final class ConfigFactory {
    039    private ConfigFactory() {
    040    }
    041
    042    /**
    043     * Loads an application's configuration from the given classpath resource or
    044     * classpath resource basename, sandwiches it between default reference
    045     * config and default overrides, and then resolves it. The classpath
    046     * resource is "raw" (it should have no "/" prefix, and is not made relative
    047     * to any package, so it's like {@link ClassLoader#getResource} not
    048     * {@link Class#getResource}).
    049     *
    050     * <p>
    051     * Resources are loaded from the current thread's
    052     * {@link Thread#getContextClassLoader()}. In general, a library needs its
    053     * configuration to come from the class loader used to load that library, so
    054     * the proper "reference.conf" are present.
    055     *
    056     * <p>
    057     * The loaded object will already be resolved (substitutions have already
    058     * been processed). As a result, if you add more fallbacks then they won't
    059     * be seen by substitutions. Substitutions are the "${foo.bar}" syntax. If
    060     * you want to parse additional files or something then you need to use
    061     * {@link #load(Config)}.
    062     *
    063     * <p>
    064     * To load a standalone resource (without the default reference and default
    065     * overrides), use {@link #parseResourcesAnySyntax(String)} rather than this
    066     * method. To load only the reference config use {@link #defaultReference()}
    067     * and to load only the overrides use {@link #defaultOverrides()}.
    068     *
    069     * @param resourceBasename
    070     *            name (optionally without extension) of a resource on classpath
    071     * @return configuration for an application relative to context class loader
    072     */
    073    public static Config load(String resourceBasename) {
    074        return load(resourceBasename, ConfigParseOptions.defaults(),
    075                ConfigResolveOptions.defaults());
    076    }
    077
    078    /**
    079     * Like {@link #load(String)} but uses the supplied class loader instead of
    080     * the current thread's context class loader.
    081     *
    082     * <p>
    083     * To load a standalone resource (without the default reference and default
    084     * overrides), use {@link #parseResourcesAnySyntax(ClassLoader, String)}
    085     * rather than this method. To load only the reference config use
    086     * {@link #defaultReference(ClassLoader)} and to load only the overrides use
    087     * {@link #defaultOverrides(ClassLoader)}.
    088     *
    089     * @param loader class loader to look for resources in
    090     * @param resourceBasename basename (no .conf/.json/.properties suffix)
    091     * @return configuration for an application relative to given class loader
    092     */
    093    public static Config load(ClassLoader loader, String resourceBasename) {
    094        return load(resourceBasename, ConfigParseOptions.defaults().setClassLoader(loader),
    095                ConfigResolveOptions.defaults());
    096    }
    097
    098    /**
    099     * Like {@link #load(String)} but allows you to specify parse and resolve
    100     * options.
    101     *
    102     * @param resourceBasename
    103     *            the classpath resource name with optional extension
    104     * @param parseOptions
    105     *            options to use when parsing the resource
    106     * @param resolveOptions
    107     *            options to use when resolving the stack
    108     * @return configuration for an application
    109     */
    110    public static Config load(String resourceBasename, ConfigParseOptions parseOptions,
    111            ConfigResolveOptions resolveOptions) {
    112        ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load");
    113        Config appConfig = ConfigFactory.parseResourcesAnySyntax(resourceBasename, withLoader);
    114        return load(withLoader.getClassLoader(), appConfig, resolveOptions);
    115    }
    116
    117    /**
    118     * Like {@link #load(String,ConfigParseOptions,ConfigResolveOptions)} but
    119     * has a class loader parameter that overrides any from the
    120     * {@code ConfigParseOptions}.
    121     *
    122     * @param loader
    123     *            class loader in which to find resources (overrides loader in
    124     *            parse options)
    125     * @param resourceBasename
    126     *            the classpath resource name with optional extension
    127     * @param parseOptions
    128     *            options to use when parsing the resource (class loader
    129     *            overridden)
    130     * @param resolveOptions
    131     *            options to use when resolving the stack
    132     * @return configuration for an application
    133     */
    134    public static Config load(ClassLoader loader, String resourceBasename,
    135            ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions) {
    136        return load(resourceBasename, parseOptions.setClassLoader(loader), resolveOptions);
    137    }
    138
    139    private static ClassLoader checkedContextClassLoader(String methodName) {
    140        ClassLoader loader = Thread.currentThread().getContextClassLoader();
    141        if (loader == null)
    142            throw new ConfigException.BugOrBroken("Context class loader is not set for the current thread; "
    143                    + "if Thread.currentThread().getContextClassLoader() returns null, you must pass a ClassLoader "
    144                    + "explicitly to ConfigFactory." + methodName);
    145        else
    146            return loader;
    147    }
    148
    149    private static ConfigParseOptions ensureClassLoader(ConfigParseOptions options, String methodName) {
    150        if (options.getClassLoader() == null)
    151            return options.setClassLoader(checkedContextClassLoader(methodName));
    152        else
    153            return options;
    154    }
    155
    156    /**
    157     * Assembles a standard configuration using a custom <code>Config</code>
    158     * object rather than loading "application.conf". The <code>Config</code>
    159     * object will be sandwiched between the default reference config and
    160     * default overrides and then resolved.
    161     *
    162     * @param config
    163     *            the application's portion of the configuration
    164     * @return resolved configuration with overrides and fallbacks added
    165     */
    166    public static Config load(Config config) {
    167        return load(checkedContextClassLoader("load"), config);
    168    }
    169
    170    /**
    171     * Like {@link #load(Config)} but allows you to specify
    172     * the class loader for looking up resources.
    173     *
    174     * @param loader
    175     *            the class loader to use to find resources
    176     * @param config
    177     *            the application's portion of the configuration
    178     * @return resolved configuration with overrides and fallbacks added
    179     */
    180    public static Config load(ClassLoader loader, Config config) {
    181        return load(loader, config, ConfigResolveOptions.defaults());
    182    }
    183
    184    /**
    185     * Like {@link #load(Config)} but allows you to specify
    186     * {@link ConfigResolveOptions}.
    187     *
    188     * @param config
    189     *            the application's portion of the configuration
    190     * @param resolveOptions
    191     *            options for resolving the assembled config stack
    192     * @return resolved configuration with overrides and fallbacks added
    193     */
    194    public static Config load(Config config, ConfigResolveOptions resolveOptions) {
    195        return load(checkedContextClassLoader("load"), config, resolveOptions);
    196    }
    197
    198    /**
    199     * Like {@link #load(Config,ConfigResolveOptions)} but allows you to specify
    200     * a class loader other than the context class loader.
    201     *
    202     * @param loader
    203     *            class loader to use when looking up override and reference
    204     *            configs
    205     * @param config
    206     *            the application's portion of the configuration
    207     * @param resolveOptions
    208     *            options for resolving the assembled config stack
    209     * @return resolved configuration with overrides and fallbacks added
    210     */
    211    public static Config load(ClassLoader loader, Config config, ConfigResolveOptions resolveOptions) {
    212        return defaultOverrides(loader).withFallback(config).withFallback(defaultReference(loader))
    213                .resolve(resolveOptions);
    214    }
    215
    216    private static Config parseApplicationConfig(ConfigParseOptions parseOptions) {
    217        ClassLoader loader = parseOptions.getClassLoader();
    218        if (loader == null)
    219            throw new ConfigException.BugOrBroken(
    220                    "ClassLoader should have been set here; bug in ConfigFactory. "
    221                            + "(You can probably work around this bug by passing in a class loader or calling currentThread().setContextClassLoader() though.)");
    222
    223        int specified = 0;
    224
    225        // override application.conf with config.file, config.resource,
    226        // config.url if requested.
    227        String resource = System.getProperty("config.resource");
    228        if (resource != null)
    229            specified += 1;
    230        String file = System.getProperty("config.file");
    231        if (file != null)
    232            specified += 1;
    233        String url = System.getProperty("config.url");
    234        if (url != null)
    235            specified += 1;
    236
    237        if (specified == 0) {
    238            return ConfigFactory.parseResourcesAnySyntax("application", parseOptions);
    239        } else if (specified > 1) {
    240            throw new ConfigException.Generic("You set more than one of config.file='" + file
    241                    + "', config.url='" + url + "', config.resource='" + resource
    242                    + "'; don't know which one to use!");
    243        } else {
    244            // the override file/url/resource MUST be present or it's an error
    245            ConfigParseOptions overrideOptions = parseOptions.setAllowMissing(false);
    246            if (resource != null) {
    247                if (resource.startsWith("/"))
    248                    resource = resource.substring(1);
    249                // this deliberately does not parseResourcesAnySyntax; if
    250                // people want that they can use an include statement.
    251                return parseResources(loader, resource, overrideOptions);
    252            } else if (file != null) {
    253                return parseFile(new File(file), overrideOptions);
    254            } else {
    255                try {
    256                    return parseURL(new URL(url), overrideOptions);
    257                } catch (MalformedURLException e) {
    258                    throw new ConfigException.Generic("Bad URL in config.url system property: '"
    259                            + url + "': " + e.getMessage(), e);
    260                }
    261            }
    262        }
    263    }
    264
    265    /**
    266     * Loads a default configuration, equivalent to {@link #load(Config)
    267     * load(defaultApplication())} in most cases. This configuration should be used by
    268     * libraries and frameworks unless an application provides a different one.
    269     * <p>
    270     * This method may return a cached singleton so will not see changes to
    271     * system properties or config files. (Use {@link #invalidateCaches()} to
    272     * force it to reload.)
    273     *
    274     * @return configuration for an application
    275     */
    276    public static Config load() {
    277        ClassLoader loader = checkedContextClassLoader("load");
    278        return load(loader);
    279    }
    280
    281    /**
    282     * Like {@link #load()} but allows specifying parse options.
    283     *
    284     * @param parseOptions
    285     *            Options for parsing resources
    286     * @return configuration for an application
    287     */
    288    public static Config load(ConfigParseOptions parseOptions) {
    289        return load(parseOptions, ConfigResolveOptions.defaults());
    290    }
    291
    292    /**
    293     * Like {@link #load()} but allows specifying a class loader other than the
    294     * thread's current context class loader.
    295     *
    296     * @param loader
    297     *            class loader for finding resources
    298     * @return configuration for an application
    299     */
    300    public static Config load(final ClassLoader loader) {
    301        final ConfigParseOptions withLoader = ConfigParseOptions.defaults().setClassLoader(loader);
    302        return ConfigImpl.computeCachedConfig(loader, "load", new Callable<Config>() {
    303            @Override
    304            public Config call() {
    305                return load(loader, defaultApplication(withLoader));
    306            }
    307        });
    308    }
    309
    310    /**
    311     * Like {@link #load()} but allows specifying a class loader other than the
    312     * thread's current context class loader and also specify parse options.
    313     *
    314     * @param loader
    315     *            class loader for finding resources (overrides any loader in parseOptions)
    316     * @param parseOptions
    317     *            Options for parsing resources
    318     * @return configuration for an application
    319     */
    320    public static Config load(ClassLoader loader, ConfigParseOptions parseOptions) {
    321        return load(parseOptions.setClassLoader(loader));
    322    }
    323
    324    /**
    325     * Like {@link #load()} but allows specifying a class loader other than the
    326     * thread's current context class loader and also specify resolve options.
    327     *
    328     * @param loader
    329     *            class loader for finding resources
    330     * @param resolveOptions
    331     *            options for resolving the assembled config stack
    332     * @return configuration for an application
    333     */
    334    public static Config load(ClassLoader loader, ConfigResolveOptions resolveOptions) {
    335        return load(loader, ConfigParseOptions.defaults(), resolveOptions);
    336    }
    337
    338
    339    /**
    340     * Like {@link #load()} but allows specifying a class loader other than the
    341     * thread's current context class loader, parse options, and resolve options.
    342     *
    343     * @param loader
    344     *            class loader for finding resources (overrides any loader in parseOptions)
    345     * @param parseOptions
    346     *            Options for parsing resources
    347     * @param resolveOptions
    348     *            options for resolving the assembled config stack
    349     * @return configuration for an application
    350     */
    351    public static Config load(ClassLoader loader, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions) {
    352        final ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load");
    353        return load(loader, defaultApplication(withLoader), resolveOptions);
    354    }
    355
    356    /**
    357     * Like {@link #load()} but allows specifying parse options and resolve
    358     * options.
    359     *
    360     * @param parseOptions
    361     *            Options for parsing resources
    362     * @param resolveOptions
    363     *            options for resolving the assembled config stack
    364     * @return configuration for an application
    365     *
    366     * @since 1.3.0
    367     */
    368    public static Config load(ConfigParseOptions parseOptions, final ConfigResolveOptions resolveOptions) {
    369        final ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load");
    370        return load(defaultApplication(withLoader), resolveOptions);
    371    }
    372
    373    /**
    374     * Obtains the default reference configuration, which is currently created
    375     * by merging all resources "reference.conf" found on the classpath and
    376     * overriding the result with system properties. The returned reference
    377     * configuration will already have substitutions resolved.
    378     *
    379     * <p>
    380     * Libraries and frameworks should ship with a "reference.conf" in their
    381     * jar.
    382     *
    383     * <p>
    384     * The reference config must be looked up in the class loader that contains
    385     * the libraries that you want to use with this config, so the
    386     * "reference.conf" for each library can be found. Use
    387     * {@link #defaultReference(ClassLoader)} if the context class loader is not
    388     * suitable.
    389     *
    390     * <p>
    391     * The {@link #load()} methods merge this configuration for you
    392     * automatically.
    393     *
    394     * <p>
    395     * Future versions may look for reference configuration in more places. It
    396     * is not guaranteed that this method <em>only</em> looks at
    397     * "reference.conf".
    398     *
    399     * @return the default reference config for context class loader
    400     */
    401    public static Config defaultReference() {
    402        return defaultReference(checkedContextClassLoader("defaultReference"));
    403    }
    404
    405    /**
    406     * Like {@link #defaultReference()} but allows you to specify a class loader
    407     * to use rather than the current context class loader.
    408     *
    409     * @param loader class loader to look for resources in
    410     * @return the default reference config for this class loader
    411     */
    412    public static Config defaultReference(ClassLoader loader) {
    413        return ConfigImpl.defaultReference(loader);
    414    }
    415
    416    /**
    417     * Obtains the default override configuration, which currently consists of
    418     * system properties. The returned override configuration will already have
    419     * substitutions resolved.
    420     *
    421     * <p>
    422     * The {@link #load()} methods merge this configuration for you
    423     * automatically.
    424     *
    425     * <p>
    426     * Future versions may get overrides in more places. It is not guaranteed
    427     * that this method <em>only</em> uses system properties.
    428     *
    429     * @return the default override configuration
    430     */
    431    public static Config defaultOverrides() {
    432        return systemProperties();
    433    }
    434
    435    /**
    436     * Like {@link #defaultOverrides()} but allows you to specify a class loader
    437     * to use rather than the current context class loader.
    438     *
    439     * @param loader class loader to look for resources in
    440     * @return the default override configuration
    441     */
    442    public static Config defaultOverrides(ClassLoader loader) {
    443        return systemProperties();
    444    }
    445
    446    /**
    447     * Obtains the default application-specific configuration,
    448     * which defaults to parsing <code>application.conf</code>,
    449     * <code>application.json</code>, and
    450     * <code>application.properties</code> on the classpath, but
    451     * can also be rerouted using the <code>config.file</code>,
    452     * <code>config.resource</code>, and <code>config.url</code>
    453     * system properties.
    454     *
    455     * <p> The no-arguments {@link #load()} method automatically
    456     * stacks the {@link #defaultReference()}, {@link
    457     * #defaultApplication()}, and {@link #defaultOverrides()}
    458     * configs. You would use <code>defaultApplication()</code>
    459     * directly only if you're somehow customizing behavior by
    460     * reimplementing <code>load()</code>.
    461     *
    462     * <p>The configuration returned by
    463     * <code>defaultApplication()</code> will not be resolved
    464     * already, in contrast to <code>defaultReference()</code> and
    465     * <code>defaultOverrides()</code>. This is because
    466     * application.conf would normally be resolved <em>after</em>
    467     * merging with the reference and override configs.
    468     *
    469     * <p>
    470     * If the system properties <code>config.resource</code>,
    471     * <code>config.file</code>, or <code>config.url</code> are set, then the
    472     * classpath resource, file, or URL specified in those properties will be
    473     * used rather than the default
    474     * <code>application.{conf,json,properties}</code> classpath resources.
    475     * These system properties should not be set in code (after all, you can
    476     * just parse whatever you want manually and then use {@link #load(Config)}
    477     * if you don't want to use <code>application.conf</code>). The properties
    478     * are intended for use by the person or script launching the application.
    479     * For example someone might have a <code>production.conf</code> that
    480     * include <code>application.conf</code> but then change a couple of values.
    481     * When launching the app they could specify
    482     * <code>-Dconfig.resource=production.conf</code> to get production mode.
    483     *
    484     * <p>
    485     * If no system properties are set to change the location of the default
    486     * configuration, <code>defaultApplication()</code> is equivalent to
    487     * <code>ConfigFactory.parseResources("application")</code>.
    488     *
    489     * @since 1.3.0
    490     *
    491     * @return the default application.conf or system-property-configured configuration
    492     */
    493    public static Config defaultApplication() {
    494        return defaultApplication(ConfigParseOptions.defaults());
    495    }
    496
    497    /**
    498     * Like {@link #defaultApplication()} but allows you to specify a class loader
    499     * to use rather than the current context class loader.
    500     *
    501     * @since 1.3.0
    502     *
    503     * @param loader class loader to look for resources in
    504     * @return the default application configuration
    505     */
    506    public static Config defaultApplication(ClassLoader loader) {
    507        return defaultApplication(ConfigParseOptions.defaults().setClassLoader(loader));
    508    }
    509
    510    /**
    511     * Like {@link #defaultApplication()} but allows you to specify parse options.
    512     *
    513     * @since 1.3.0
    514     *
    515     * @param options the options
    516     * @return the default application configuration
    517     */
    518    public static Config defaultApplication(ConfigParseOptions options) {
    519        return parseApplicationConfig(ensureClassLoader(options, "defaultApplication"));
    520    }
    521
    522    /**
    523     * Reloads any cached configs, picking up changes to system properties for
    524     * example. Because a {@link Config} is immutable, anyone with a reference
    525     * to the old configs will still have the same outdated objects. However,
    526     * new calls to {@link #load()} or {@link #defaultOverrides()} or
    527     * {@link #defaultReference} may return a new object.
    528     * <p>
    529     * This method is primarily intended for use in unit tests, for example,
    530     * that may want to update a system property then confirm that it's used
    531     * correctly. In many cases, use of this method may indicate there's a
    532     * better way to set up your code.
    533     * <p>
    534     * Caches may be reloaded immediately or lazily; once you call this method,
    535     * the reload can occur at any time, even during the invalidation process.
    536     * So FIRST make the changes you'd like the caches to notice, then SECOND
    537     * call this method to invalidate caches. Don't expect that invalidating,
    538     * making changes, then calling {@link #load()}, will work. Make changes
    539     * before you invalidate.
    540     */
    541    public static void invalidateCaches() {
    542        // We rely on this having the side effect that it drops
    543        // all caches
    544        ConfigImpl.reloadSystemPropertiesConfig();
    545    }
    546
    547    /**
    548     * Gets an empty configuration. See also {@link #empty(String)} to create an
    549     * empty configuration with a description, which may improve user-visible
    550     * error messages.
    551     *
    552     * @return an empty configuration
    553     */
    554    public static Config empty() {
    555        return empty(null);
    556    }
    557
    558    /**
    559     * Gets an empty configuration with a description to be used to create a
    560     * {@link ConfigOrigin} for this <code>Config</code>. The description should
    561     * be very short and say what the configuration is, like "default settings"
    562     * or "foo settings" or something. (Presumably you will merge some actual
    563     * settings into this empty config using {@link Config#withFallback}, making
    564     * the description more useful.)
    565     *
    566     * @param originDescription
    567     *            description of the config
    568     * @return an empty configuration
    569     */
    570    public static Config empty(String originDescription) {
    571        return ConfigImpl.emptyConfig(originDescription);
    572    }
    573
    574    /**
    575     * Gets a <code>Config</code> containing the system properties from
    576     * {@link java.lang.System#getProperties()}, parsed and converted as with
    577     * {@link #parseProperties}.
    578     * <p>
    579     * This method can return a global immutable singleton, so it's preferred
    580     * over parsing system properties yourself.
    581     * <p>
    582     * {@link #load} will include the system properties as overrides already, as
    583     * will {@link #defaultReference} and {@link #defaultOverrides}.
    584     *
    585     * <p>
    586     * Because this returns a singleton, it will not notice changes to system
    587     * properties made after the first time this method is called. Use
    588     * {@link #invalidateCaches()} to force the singleton to reload if you
    589     * modify system properties.
    590     *
    591     * @return system properties parsed into a <code>Config</code>
    592     */
    593    public static Config systemProperties() {
    594        return ConfigImpl.systemPropertiesAsConfig();
    595    }
    596
    597    /**
    598     * Gets a <code>Config</code> containing the system's environment variables.
    599     * This method can return a global immutable singleton.
    600     *
    601     * <p>
    602     * Environment variables are used as fallbacks when resolving substitutions
    603     * whether or not this object is included in the config being resolved, so
    604     * you probably don't need to use this method for most purposes. It can be a
    605     * nicer API for accessing environment variables than raw
    606     * {@link java.lang.System#getenv(String)} though, since you can use methods
    607     * such as {@link Config#getInt}.
    608     *
    609     * @return system environment variables parsed into a <code>Config</code>
    610     */
    611    public static Config systemEnvironment() {
    612        return ConfigImpl.envVariablesAsConfig();
    613    }
    614
    615    /**
    616     * Converts a Java {@link java.util.Properties} object to a
    617     * {@link ConfigObject} using the rules documented in the <a
    618     * href="https://github.com/typesafehub/config/blob/master/HOCON.md">HOCON
    619     * spec</a>. The keys in the <code>Properties</code> object are split on the
    620     * period character '.' and treated as paths. The values will all end up as
    621     * string values. If you have both "a=foo" and "a.b=bar" in your properties
    622     * file, so "a" is both the object containing "b" and the string "foo", then
    623     * the string value is dropped.
    624     *
    625     * <p>
    626     * If you want to have <code>System.getProperties()</code> as a
    627     * ConfigObject, it's better to use the {@link #systemProperties()} method
    628     * which returns a cached global singleton.
    629     *
    630     * @param properties
    631     *            a Java Properties object
    632     * @param options
    633     *            the parse options
    634     * @return the parsed configuration
    635     */
    636    public static Config parseProperties(Properties properties,
    637            ConfigParseOptions options) {
    638        return Parseable.newProperties(properties, options).parse().toConfig();
    639    }
    640
    641    /**
    642     * Like {@link parseProperties(Properties, ConfigParseOptions)} but uses default
    643     * parse options.
    644     * @param properties
    645     *            a Java Properties object
    646     * @return the parsed configuration
    647     */
    648    public static Config parseProperties(Properties properties) {
    649        return parseProperties(properties, ConfigParseOptions.defaults());
    650    }
    651
    652    /**
    653     * Parses a Reader into a Config instance. Does not call
    654     * {@link Config#resolve} or merge the parsed stream with any
    655     * other configuration; this method parses a single stream and
    656     * does nothing else. It does process "include" statements in
    657     * the parsed stream, and may end up doing other IO due to those
    658     * statements.
    659     *
    660     * @param reader
    661     *       the reader to parse
    662     * @param options
    663     *       parse options to control how the reader is interpreted
    664     * @return the parsed configuration
    665     * @throws ConfigException on IO or parse errors
    666     */
    667    public static Config parseReader(Reader reader, ConfigParseOptions options) {
    668        return Parseable.newReader(reader, options).parse().toConfig();
    669    }
    670
    671    /**
    672     * Parses a reader into a Config instance as with
    673     * {@link #parseReader(Reader,ConfigParseOptions)} but always uses the
    674     * default parse options.
    675     *
    676     * @param reader
    677     *       the reader to parse
    678     * @return the parsed configuration
    679     * @throws ConfigException on IO or parse errors
    680     */
    681    public static Config parseReader(Reader reader) {
    682        return parseReader(reader, ConfigParseOptions.defaults());
    683    }
    684
    685    /**
    686     * Parses a URL into a Config instance. Does not call
    687     * {@link Config#resolve} or merge the parsed stream with any
    688     * other configuration; this method parses a single stream and
    689     * does nothing else. It does process "include" statements in
    690     * the parsed stream, and may end up doing other IO due to those
    691     * statements.
    692     *
    693     * @param url
    694     *       the url to parse
    695     * @param options
    696     *       parse options to control how the url is interpreted
    697     * @return the parsed configuration
    698     * @throws ConfigException on IO or parse errors
    699     */
    700    public static Config parseURL(URL url, ConfigParseOptions options) {
    701        return Parseable.newURL(url, options).parse().toConfig();
    702    }
    703
    704    /**
    705     * Parses a url into a Config instance as with
    706     * {@link #parseURL(URL,ConfigParseOptions)} but always uses the
    707     * default parse options.
    708     *
    709     * @param url
    710     *       the url to parse
    711     * @return the parsed configuration
    712     * @throws ConfigException on IO or parse errors
    713     */
    714    public static Config parseURL(URL url) {
    715        return parseURL(url, ConfigParseOptions.defaults());
    716    }
    717
    718    /**
    719     * Parses a file into a Config instance. Does not call
    720     * {@link Config#resolve} or merge the file with any other
    721     * configuration; this method parses a single file and does
    722     * nothing else. It does process "include" statements in the
    723     * parsed file, and may end up doing other IO due to those
    724     * statements.
    725     *
    726     * @param file
    727     *       the file to parse
    728     * @param options
    729     *       parse options to control how the file is interpreted
    730     * @return the parsed configuration
    731     * @throws ConfigException on IO or parse errors
    732     */
    733    public static Config parseFile(File file, ConfigParseOptions options) {
    734        return Parseable.newFile(file, options).parse().toConfig();
    735    }
    736
    737    /**
    738     * Parses a file into a Config instance as with
    739     * {@link #parseFile(File,ConfigParseOptions)} but always uses the
    740     * default parse options.
    741     *
    742     * @param file
    743     *       the file to parse
    744     * @return the parsed configuration
    745     * @throws ConfigException on IO or parse errors
    746     */
    747    public static Config parseFile(File file) {
    748        return parseFile(file, ConfigParseOptions.defaults());
    749    }
    750
    751    /**
    752     * Parses a file with a flexible extension. If the <code>fileBasename</code>
    753     * already ends in a known extension, this method parses it according to
    754     * that extension (the file's syntax must match its extension). If the
    755     * <code>fileBasename</code> does not end in an extension, it parses files
    756     * with all known extensions and merges whatever is found.
    757     *
    758     * <p>
    759     * In the current implementation, the extension ".conf" forces
    760     * {@link ConfigSyntax#CONF}, ".json" forces {@link ConfigSyntax#JSON}, and
    761     * ".properties" forces {@link ConfigSyntax#PROPERTIES}. When merging files,
    762     * ".conf" falls back to ".json" falls back to ".properties".
    763     *
    764     * <p>
    765     * Future versions of the implementation may add additional syntaxes or
    766     * additional extensions. However, the ordering (fallback priority) of the
    767     * three current extensions will remain the same.
    768     *
    769     * <p>
    770     * If <code>options</code> forces a specific syntax, this method only parses
    771     * files with an extension matching that syntax.
    772     *
    773     * <p>
    774     * If {@link ConfigParseOptions#getAllowMissing options.getAllowMissing()}
    775     * is true, then no files have to exist; if false, then at least one file
    776     * has to exist.
    777     *
    778     * @param fileBasename
    779     *            a filename with or without extension
    780     * @param options
    781     *            parse options
    782     * @return the parsed configuration
    783     */
    784    public static Config parseFileAnySyntax(File fileBasename,
    785            ConfigParseOptions options) {
    786        return ConfigImpl.parseFileAnySyntax(fileBasename, options).toConfig();
    787    }
    788
    789    /**
    790     * Like {@link #parseFileAnySyntax(File,ConfigParseOptions)} but always uses
    791     * default parse options.
    792     *
    793     * @param fileBasename
    794     *            a filename with or without extension
    795     * @return the parsed configuration
    796     */
    797    public static Config parseFileAnySyntax(File fileBasename) {
    798        return parseFileAnySyntax(fileBasename, ConfigParseOptions.defaults());
    799    }
    800
    801    /**
    802     * Parses all resources on the classpath with the given name and merges them
    803     * into a single <code>Config</code>.
    804     *
    805     * <p>
    806     * If the resource name does not begin with a "/", it will have the supplied
    807     * class's package added to it, in the same way as
    808     * {@link java.lang.Class#getResource}.
    809     *
    810     * <p>
    811     * Duplicate resources with the same name are merged such that ones returned
    812     * earlier from {@link ClassLoader#getResources} fall back to (have higher
    813     * priority than) the ones returned later. This implies that resources
    814     * earlier in the classpath override those later in the classpath when they
    815     * configure the same setting. However, in practice real applications may
    816     * not be consistent about classpath ordering, so be careful. It may be best
    817     * to avoid assuming too much.
    818     *
    819     * @param klass
    820     *            <code>klass.getClassLoader()</code> will be used to load
    821     *            resources, and non-absolute resource names will have this
    822     *            class's package added
    823     * @param resource
    824     *            resource to look up, relative to <code>klass</code>'s package
    825     *            or absolute starting with a "/"
    826     * @param options
    827     *            parse options
    828     * @return the parsed configuration
    829     */
    830    public static Config parseResources(Class<?> klass, String resource,
    831            ConfigParseOptions options) {
    832        return Parseable.newResources(klass, resource, options).parse()
    833                .toConfig();
    834    }
    835
    836    /**
    837     * Like {@link #parseResources(Class,String,ConfigParseOptions)} but always uses
    838     * default parse options.
    839     *
    840     * @param klass
    841     *            <code>klass.getClassLoader()</code> will be used to load
    842     *            resources, and non-absolute resource names will have this
    843     *            class's package added
    844     * @param resource
    845     *            resource to look up, relative to <code>klass</code>'s package
    846     *            or absolute starting with a "/"
    847     * @return the parsed configuration
    848     */
    849    public static Config parseResources(Class<?> klass, String resource) {
    850        return parseResources(klass, resource, ConfigParseOptions.defaults());
    851    }
    852
    853    /**
    854     * Parses classpath resources with a flexible extension. In general, this
    855     * method has the same behavior as
    856     * {@link #parseFileAnySyntax(File,ConfigParseOptions)} but for classpath
    857     * resources instead, as in {@link #parseResources}.
    858     *
    859     * <p>
    860     * There is a thorny problem with this method, which is that
    861     * {@link java.lang.ClassLoader#getResources} must be called separately for
    862     * each possible extension. The implementation ends up with separate lists
    863     * of resources called "basename.conf" and "basename.json" for example. As a
    864     * result, the ideal ordering between two files with different extensions is
    865     * unknown; there is no way to figure out how to merge the two lists in
    866     * classpath order. To keep it simple, the lists are simply concatenated,
    867     * with the same syntax priorities as
    868     * {@link #parseFileAnySyntax(File,ConfigParseOptions) parseFileAnySyntax()}
    869     * - all ".conf" resources are ahead of all ".json" resources which are
    870     * ahead of all ".properties" resources.
    871     *
    872     * @param klass
    873     *            class which determines the <code>ClassLoader</code> and the
    874     *            package for relative resource names
    875     * @param resourceBasename
    876     *            a resource name as in {@link java.lang.Class#getResource},
    877     *            with or without extension
    878     * @param options
    879     *            parse options (class loader is ignored in favor of the one
    880     *            from klass)
    881     * @return the parsed configuration
    882     */
    883    public static Config parseResourcesAnySyntax(Class<?> klass, String resourceBasename,
    884            ConfigParseOptions options) {
    885        return ConfigImpl.parseResourcesAnySyntax(klass, resourceBasename,
    886                options).toConfig();
    887    }
    888
    889    /**
    890     * Like {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)}
    891     * but always uses default parse options.
    892     *
    893     * @param klass
    894     *            <code>klass.getClassLoader()</code> will be used to load
    895     *            resources, and non-absolute resource names will have this
    896     *            class's package added
    897     * @param resourceBasename
    898     *            a resource name as in {@link java.lang.Class#getResource},
    899     *            with or without extension
    900     * @return the parsed configuration
    901     */
    902    public static Config parseResourcesAnySyntax(Class<?> klass, String resourceBasename) {
    903        return parseResourcesAnySyntax(klass, resourceBasename, ConfigParseOptions.defaults());
    904    }
    905
    906    /**
    907     * Parses all resources on the classpath with the given name and merges them
    908     * into a single <code>Config</code>.
    909     *
    910     * <p>
    911     * This works like {@link java.lang.ClassLoader#getResource}, not like
    912     * {@link java.lang.Class#getResource}, so the name never begins with a
    913     * slash.
    914     *
    915     * <p>
    916     * See {@link #parseResources(Class,String,ConfigParseOptions)} for full
    917     * details.
    918     *
    919     * @param loader
    920     *            will be used to load resources by setting this loader on the
    921     *            provided options
    922     * @param resource
    923     *            resource to look up
    924     * @param options
    925     *            parse options (class loader is ignored)
    926     * @return the parsed configuration
    927     */
    928    public static Config parseResources(ClassLoader loader, String resource,
    929            ConfigParseOptions options) {
    930        return parseResources(resource, options.setClassLoader(loader));
    931    }
    932
    933    /**
    934     * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but always uses
    935     * default parse options.
    936     *
    937     * @param loader
    938     *            will be used to load resources
    939     * @param resource
    940     *            resource to look up in the loader
    941     * @return the parsed configuration
    942     */
    943    public static Config parseResources(ClassLoader loader, String resource) {
    944        return parseResources(loader, resource, ConfigParseOptions.defaults());
    945    }
    946
    947    /**
    948     * Parses classpath resources with a flexible extension. In general, this
    949     * method has the same behavior as
    950     * {@link #parseFileAnySyntax(File,ConfigParseOptions)} but for classpath
    951     * resources instead, as in
    952     * {@link #parseResources(ClassLoader,String,ConfigParseOptions)}.
    953     *
    954     * <p>
    955     * {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} differs
    956     * in the syntax for the resource name, but otherwise see
    957     * {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} for
    958     * some details and caveats on this method.
    959     *
    960     * @param loader
    961     *            class loader to look up resources in, will be set on options
    962     * @param resourceBasename
    963     *            a resource name as in
    964     *            {@link java.lang.ClassLoader#getResource}, with or without
    965     *            extension
    966     * @param options
    967     *            parse options (class loader ignored)
    968     * @return the parsed configuration
    969     */
    970    public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename,
    971            ConfigParseOptions options) {
    972        return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options.setClassLoader(loader))
    973                .toConfig();
    974    }
    975
    976    /**
    977     * Like {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)} but always uses
    978     * default parse options.
    979     *
    980     * @param loader
    981     *            will be used to load resources
    982     * @param resourceBasename
    983     *            a resource name as in
    984     *            {@link java.lang.ClassLoader#getResource}, with or without
    985     *            extension
    986     * @return the parsed configuration
    987     */
    988    public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename) {
    989        return parseResourcesAnySyntax(loader, resourceBasename, ConfigParseOptions.defaults());
    990    }
    991
    992    /**
    993     * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but
    994     * uses thread's current context class loader if none is set in the
    995     * ConfigParseOptions.
    996     * @param resource the resource name
    997     * @param options parse options
    998     * @return the parsed configuration
    999     */
    1000    public static Config parseResources(String resource, ConfigParseOptions options) {
    1001        ConfigParseOptions withLoader = ensureClassLoader(options, "parseResources");
    1002        return Parseable.newResources(resource, withLoader).parse().toConfig();
    1003    }
    1004
    1005    /**
    1006     * Like {@link #parseResources(ClassLoader,String)} but uses thread's
    1007     * current context class loader.
    1008     * @param resource the resource name
    1009     * @return the parsed configuration
    1010     */
    1011    public static Config parseResources(String resource) {
    1012        return parseResources(resource, ConfigParseOptions.defaults());
    1013    }
    1014
    1015    /**
    1016     * Like
    1017     * {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)}
    1018     * but uses thread's current context class loader.
    1019     * @param resourceBasename the resource basename (no file type suffix)
    1020     * @param options parse options
    1021     * @return the parsed configuration
    1022     */
    1023    public static Config parseResourcesAnySyntax(String resourceBasename, ConfigParseOptions options) {
    1024        return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options).toConfig();
    1025    }
    1026
    1027    /**
    1028     * Like {@link #parseResourcesAnySyntax(ClassLoader,String)} but uses
    1029     * thread's current context class loader.
    1030     * @param resourceBasename the resource basename (no file type suffix)
    1031     * @return the parsed configuration
    1032     */
    1033    public static Config parseResourcesAnySyntax(String resourceBasename) {
    1034        return parseResourcesAnySyntax(resourceBasename, ConfigParseOptions.defaults());
    1035    }
    1036
    1037    /**
    1038     * Parses a string (which should be valid HOCON or JSON by default, or
    1039     * the syntax specified in the options otherwise).
    1040     *
    1041     * @param s string to parse
    1042     * @param options parse options
    1043     * @return the parsed configuration
    1044     */
    1045    public static Config parseString(String s, ConfigParseOptions options) {
    1046        return Parseable.newString(s, options).parse().toConfig();
    1047    }
    1048
    1049    /**
    1050     * Parses a string (which should be valid HOCON or JSON).
    1051     *
    1052     * @param s string to parse
    1053     * @return the parsed configuration
    1054     */
    1055    public static Config parseString(String s) {
    1056        return parseString(s, ConfigParseOptions.defaults());
    1057    }
    1058
    1059    /**
    1060     * Creates a {@code Config} based on a {@link java.util.Map} from paths to
    1061     * plain Java values. Similar to
    1062     * {@link ConfigValueFactory#fromMap(Map,String)}, except the keys in the
    1063     * map are path expressions, rather than keys; and correspondingly it
    1064     * returns a {@code Config} instead of a {@code ConfigObject}. This is more
    1065     * convenient if you are writing literal maps in code, and less convenient
    1066     * if you are getting your maps from some data source such as a parser.
    1067     *
    1068     * <p>
    1069     * An exception will be thrown (and it is a bug in the caller of the method)
    1070     * if a path is both an object and a value, for example if you had both
    1071     * "a=foo" and "a.b=bar", then "a" is both the string "foo" and the parent
    1072     * object of "b". The caller of this method should ensure that doesn't
    1073     * happen.
    1074     *
    1075     * @param values map from paths to plain Java objects
    1076     * @param originDescription
    1077     *            description of what this map represents, like a filename, or
    1078     *            "default settings" (origin description is used in error
    1079     *            messages)
    1080     * @return the map converted to a {@code Config}
    1081     */
    1082    public static Config parseMap(Map<String, ? extends Object> values,
    1083            String originDescription) {
    1084        return ConfigImpl.fromPathMap(values, originDescription).toConfig();
    1085    }
    1086
    1087    /**
    1088     * See the other overload of {@link #parseMap(Map, String)} for details,
    1089     * this one just uses a default origin description.
    1090     *
    1091     * @param values map from paths to plain Java values
    1092     * @return the map converted to a {@code Config}
    1093     */
    1094    public static Config parseMap(Map<String, ? extends Object> values) {
    1095        return parseMap(values, null);
    1096    }
    1097}