    001package com.typesafe.config.parser;
    002
    003import com.typesafe.config.ConfigValue;
    004
    005/**
    006 * Represents an individual HOCON or JSON file, preserving all
    007 * formatting and syntax details.  This can be used to replace
    008 * individual values and exactly render the original text of the
    009 * input.
    010 *
    011 * <p>
    012 * Because this object is immutable, it is safe to use from multiple threads and
    013 * there's no need for "defensive copies."
    014 *
    015 * <p>
    016 * <em>Do not implement interface {@code ConfigDocument}</em>; it should only be
    017 * implemented by the config library. Arbitrary implementations will not work
    018 * because the library internals assume a specific concrete implementation.
    019 * Also, this interface is likely to grow new methods over time, so third-party
    020 * implementations will break.
    021 */
    022public interface ConfigDocument {
    023    /**
    024     * Returns a new ConfigDocument that is a copy of the current ConfigDocument,
    025     * but with the desired value set at the desired path. If the path exists, it will
    026     * remove all duplicates before the final occurrence of the path, and replace the value
    027     * at the final occurrence of the path. If the path does not exist, it will be added. If
    028     * the document has an array as the root value, an exception will be thrown.
    029     *
    030     * @param path the path at which to set the desired value
    031     * @param newValue the value to set at the desired path, represented as a string. This
    032     *                 string will be parsed into a ConfigNode using the same options used to
    033     *                 parse the entire document, and the text will be inserted
    034     *                 as-is into the document. Leading and trailing comments, whitespace, or
    035     *                 newlines are not allowed, and if present an exception will be thrown.
    036     *                 If a concatenation is passed in for newValue but the document was parsed
    037     *                 with JSON, the first value in the concatenation will be parsed and inserted
    038     *                 into the ConfigDocument.
    039     * @return a copy of the ConfigDocument with the desired value at the desired path
    040     */
    041    ConfigDocument setValue(String path, String newValue);
    042
    043    /**
    044     * Returns a new ConfigDocument that is a copy of the current ConfigDocument,
    045     * but with the desired value set at the desired path as with {@link #setValue(String, String)},
    046     * but takes a ConfigValue instead of a string.
    047     *
    048     * @param path the path at which to set the desired value
    049     * @param newValue the value to set at the desired path, represented as a ConfigValue.
    050     *                 The rendered text of the ConfigValue will be inserted into the
    051     *                 ConfigDocument.
    052     * @return a copy of the ConfigDocument with the desired value at the desired path
    053     */
    054    ConfigDocument setValue(String path, ConfigValue newValue);
    055
    056    /**
    057     * Returns a new ConfigDocument that is a copy of the current ConfigDocument, but with
    058     * the value at the desired path removed. If the desired path does not exist in the document,
    059     * a copy of the current document will be returned. If there is an array at the root, an exception
    060     * will be thrown.
    061     *
    062     * @param path the path to remove from the document
    063     * @return a copy of the ConfigDocument with the desired value removed from the document.
    064     */
    065    ConfigDocument removeValue(String path);
    066
    067    /**
    068     * Returns a boolean indicating whether or not a ConfigDocument has a value at the desired path.
    069     * @param path the path to check
    070     * @return true if the path exists in the document, otherwise false
    071     */
    072    boolean hasValue(String path);
    073
    074    /**
    075     * The original text of the input, modified if necessary with
    076     * any replaced or added values.
    077     * @return the modified original text
    078     */
    079    String render();
    080}