001package com.typesafe.config;
002
003/**
004 * Implement this interface and provide an instance to
005 * {@link ConfigResolveOptions#appendResolver ConfigResolveOptions.appendResolver()}
006 * to provide custom behavior when unresolved substitutions are encountered
007 * during resolution.
008 * @since 1.3.2
009 */
010public interface ConfigResolver {
011
012    /**
013     * Returns the value to substitute for the given unresolved path. To get the
014     * components of the path use {@link ConfigUtil#splitPath(String)}. If a
015     * non-null value is returned that value will be substituted, otherwise
016     * resolution will continue to consider the substitution as still
017     * unresolved.
018     *
019     * @param path the unresolved path
020     * @return the value to use as a substitution or null
021     */
022    public ConfigValue lookup(String path);
023
024    /**
025     * Returns a new resolver that falls back to the given resolver if this
026     * one doesn't provide a substitution itself.
027     *
028     * It's important to handle the case where you already have the fallback
029     * with a "return this", i.e. this method should not create a new object if
030     * the fallback is the same one you already have. The same fallback may be
031     * added repeatedly.
032     *
033     * @param fallback the previous includer for chaining
034     * @return a new resolver
035     */
036    public ConfigResolver withFallback(ConfigResolver fallback);
037
038}