    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}