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