001/**
002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
003 */
004package com.typesafe.config;
005
006
007/**
008 * Context provided to a {@link ConfigIncluder}; this interface is only useful
009 * inside a {@code ConfigIncluder} implementation, and is not intended for apps
010 * to implement.
011 *
012 * <p>
013 * <em>Do not implement this interface</em>; it should only be implemented by
014 * the config library. Arbitrary implementations will not work because the
015 * library internals assume a specific concrete implementation. Also, this
016 * interface is likely to grow new methods over time, so third-party
017 * implementations will break.
018 */
019public interface ConfigIncludeContext {
020    /**
021     * Tries to find a name relative to whatever is doing the including, for
022     * example in the same directory as the file doing the including. Returns
023     * null if it can't meaningfully create a relative name. The returned
024     * parseable may not exist; this function is not required to do any IO, just
025     * compute what the name would be.
026     *
027     * The passed-in filename has to be a complete name (with extension), not
028     * just a basename. (Include statements in config files are allowed to give
029     * just a basename.)
030     *
031     * @param filename
032     *            the name to make relative to the resource doing the including
033     * @return parseable item relative to the resource doing the including, or
034     *         null
035     */
036    ConfigParseable relativeTo(String filename);
037
038    /**
039     * Parse options to use (if you use another method to get a
040     * {@link ConfigParseable} then use {@link ConfigParseable#options()}
041     * instead though).
042     *
043     * @return the parse options
044     */
045    ConfigParseOptions parseOptions();
046
047
048    /**
049     * Copy this {@link ConfigIncludeContext} giving it a new value for its parseOptions.
050     *
051     * @param options new parse options to use
052     *
053     * @return the updated copy of this context
054     */
055    ConfigIncludeContext setParseOptions(ConfigParseOptions options);
056}