001/**
002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
003 */
004package com.typesafe.config;
005
006/**
007 * Implement this interface and provide an instance to
008 * {@link ConfigParseOptions#setIncluder ConfigParseOptions.setIncluder()} to
009 * customize handling of {@code include} statements in config files. You may
010 * also want to implement {@link ConfigIncluderClasspath},
011 * {@link ConfigIncluderFile}, and {@link ConfigIncluderURL}, or not.
012 */
013public interface ConfigIncluder {
014    /**
015     * Returns a new includer that falls back to the given includer. This is how
016     * you can obtain the default includer; it will be provided as a fallback.
017     * It's up to your includer to chain to it if you want to. You might want to
018     * merge any files found by the fallback includer with any objects you load
019     * yourself.
020     *
021     * It's important to handle the case where you already have the fallback
022     * with a "return this", i.e. this method should not create a new object if
023     * the fallback is the same one you already have. The same fallback may be
024     * added repeatedly.
025     *
026     * @param fallback the previous includer for chaining
027     * @return a new includer
028     */
029    ConfigIncluder withFallback(ConfigIncluder fallback);
030
031    /**
032     * Parses another item to be included. The returned object typically would
033     * not have substitutions resolved. You can throw a ConfigException here to
034     * abort parsing, or return an empty object, but may not return null.
035     * 
036     * This method is used for a "heuristic" include statement that does not
037     * specify file, URL, or classpath resource. If the include statement does
038     * specify, then the same class implementing {@link ConfigIncluder} must
039     * also implement {@link ConfigIncluderClasspath},
040     * {@link ConfigIncluderFile}, or {@link ConfigIncluderURL} as needed, or a
041     * default includer will be used.
042     * 
043     * @param context
044     *            some info about the include context
045     * @param what
046     *            the include statement's argument
047     * @return a non-null ConfigObject
048     */
049    ConfigObject include(ConfigIncludeContext context, String what);
050}