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}