001/**
002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
003 */
004package com.typesafe.config;
005
006/**
007 * An immutable value, following the <a href="http://json.org">JSON</a> type
008 * schema.
009 * 
010 * <p>
011 * Because this object is immutable, it is safe to use from multiple threads and
012 * there's no need for "defensive copies."
013 * 
014 * <p>
015 * <em>Do not implement interface {@code ConfigValue}</em>; it should only be
016 * implemented by the config library. Arbitrary implementations will not work
017 * because the library internals assume a specific concrete implementation.
018 * Also, this interface is likely to grow new methods over time, so third-party
019 * implementations will break.
020 */
021public interface ConfigValue extends ConfigMergeable {
022    /**
023     * The origin of the value (file, line number, etc.), for debugging and
024     * error messages.
025     *
026     * @return where the value came from
027     */
028    ConfigOrigin origin();
029
030    /**
031     * The {@link ConfigValueType} of the value; matches the JSON type schema.
032     *
033     * @return value's type
034     */
035    ConfigValueType valueType();
036
037    /**
038     * Returns the value as a plain Java boxed value, that is, a {@code String},
039     * {@code Number}, {@code Boolean}, {@code Map<String,Object>},
040     * {@code List<Object>}, or {@code null}, matching the {@link #valueType()}
041     * of this {@code ConfigValue}. If the value is a {@link ConfigObject} or
042     * {@link ConfigList}, it is recursively unwrapped.
043     * @return a plain Java value corresponding to this ConfigValue
044     */
045    Object unwrapped();
046
047    /**
048     * Renders the config value as a HOCON string. This method is primarily
049     * intended for debugging, so it tries to add helpful comments and
050     * whitespace.
051     * 
052     * <p>
053     * If the config value has not been resolved (see {@link Config#resolve}),
054     * it's possible that it can't be rendered as valid HOCON. In that case the
055     * rendering should still be useful for debugging but you might not be able
056     * to parse it. If the value has been resolved, it will always be parseable.
057     * 
058     * <p>
059     * This method is equivalent to
060     * {@code render(ConfigRenderOptions.defaults())}.
061     * 
062     * @return the rendered value
063     */
064    String render();
065
066    /**
067     * Renders the config value to a string, using the provided options.
068     * 
069     * <p>
070     * If the config value has not been resolved (see {@link Config#resolve}),
071     * it's possible that it can't be rendered as valid HOCON. In that case the
072     * rendering should still be useful for debugging but you might not be able
073     * to parse it. If the value has been resolved, it will always be parseable.
074     * 
075     * <p>
076     * If the config value has been resolved and the options disable all
077     * HOCON-specific features (such as comments), the rendering will be valid
078     * JSON. If you enable HOCON-only features such as comments, the rendering
079     * will not be valid JSON.
080     * 
081     * @param options
082     *            the rendering options
083     * @return the rendered value
084     */
085    String render(ConfigRenderOptions options);
086
087    @Override
088    ConfigValue withFallback(ConfigMergeable other);
089
090    /**
091     * Places the value inside a {@link Config} at the given path. See also
092     * {@link ConfigValue#atKey(String)}.
093     * 
094     * @param path
095     *            path to store this value at.
096     * @return a {@code Config} instance containing this value at the given
097     *         path.
098     */
099    Config atPath(String path);
100
101    /**
102     * Places the value inside a {@link Config} at the given key. See also
103     * {@link ConfigValue#atPath(String)}.
104     * 
105     * @param key
106     *            key to store this value at.
107     * @return a {@code Config} instance containing this value at the given key.
108     */
109    Config atKey(String key);
110    
111    /**
112     * Returns a {@code ConfigValue} based on this one, but with the given
113     * origin. This is useful when you are parsing a new format of file or setting
114     * comments for a single ConfigValue.
115     * 
116     * @param origin the origin set on the returned value
117     * @return the new ConfigValue with the given origin
118     */
119    ConfigValue withOrigin(ConfigOrigin origin);
120}