    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006/**
    007 * <p>
    008 * A set of options related to rendering a {@link ConfigValue}. Passed to
    009 * {@link ConfigValue#render(ConfigRenderOptions)}.
    010 *
    011 * <p>
    012 * Here is an example of creating a {@code ConfigRenderOptions}:
    013 *
    014 * <pre>
    015 *     ConfigRenderOptions options =
    016 *         ConfigRenderOptions.defaults().setComments(false)
    017 * </pre>
    018 */
    019public final class ConfigRenderOptions {
    020    private final boolean originComments;
    021    private final boolean comments;
    022    private final boolean formatted;
    023    private final boolean json;
    024    private final boolean showEnvVariableValues;
    025
    026    private ConfigRenderOptions(boolean originComments, boolean comments, boolean formatted,
    027            boolean json, boolean showEnvVariableValues) {
    028        this.originComments = originComments;
    029        this.comments = comments;
    030        this.formatted = formatted;
    031        this.json = json;
    032        this.showEnvVariableValues = showEnvVariableValues;
    033    }
    034
    035    /**
    036     * Returns the default render options which are verbose (commented and
    037     * formatted). See {@link ConfigRenderOptions#concise} for stripped-down
    038     * options. This rendering will not be valid JSON since it has comments.
    039     *
    040     * @return the default render options
    041     */
    042    public static ConfigRenderOptions defaults() {
    043        return new ConfigRenderOptions(true, true, true, true, true);
    044    }
    045
    046    /**
    047     * Returns concise render options (no whitespace or comments). For a
    048     * resolved {@link Config}, the concise rendering will be valid JSON.
    049     *
    050     * @return the concise render options
    051     */
    052    public static ConfigRenderOptions concise() {
    053        return new ConfigRenderOptions(false, false, false, true, true);
    054    }
    055
    056    /**
    057     * Returns options with comments toggled. This controls human-written
    058     * comments but not the autogenerated "origin of this setting" comments,
    059     * which are controlled by {@link ConfigRenderOptions#setOriginComments}.
    060     *
    061     * @param value
    062     *            true to include comments in the render
    063     * @return options with requested setting for comments
    064     */
    065    public ConfigRenderOptions setComments(boolean value) {
    066        if (value == comments)
    067            return this;
    068        else
    069            return new ConfigRenderOptions(originComments, value, formatted, json, showEnvVariableValues);
    070    }
    071
    072    /**
    073     * Returns whether the options enable comments. This method is mostly used
    074     * by the config lib internally, not by applications.
    075     *
    076     * @return true if comments should be rendered
    077     */
    078    public boolean getComments() {
    079        return comments;
    080    }
    081
    082    /**
    083     * Returns options with origin comments toggled. If this is enabled, the
    084     * library generates comments for each setting based on the
    085     * {@link ConfigValue#origin} of that setting's value. For example these
    086     * comments might tell you which file a setting comes from.
    087     *
    088     * <p>
    089     * {@code setOriginComments()} controls only these autogenerated
    090     * "origin of this setting" comments, to toggle regular comments use
    091     * {@link ConfigRenderOptions#setComments}.
    092     *
    093     * @param value
    094     *            true to include autogenerated setting-origin comments in the
    095     *            render
    096     * @return options with origin comments toggled
    097     */
    098    public ConfigRenderOptions setOriginComments(boolean value) {
    099        if (value == originComments)
    100            return this;
    101        else
    102            return new ConfigRenderOptions(value, comments, formatted, json, showEnvVariableValues);
    103    }
    104
    105    /**
    106     * Returns whether the options enable automated origin comments. This method
    107     * is mostly used by the config lib internally, not by applications.
    108     *
    109     * @return true if origin comments should be rendered
    110     */
    111    public boolean getOriginComments() {
    112        return originComments;
    113    }
    114
    115    /**
    116     * Returns options with formatting toggled. Formatting means indentation and
    117     * whitespace, enabling formatting makes things prettier but larger.
    118     *
    119     * @param value
    120     *            true to enable formatting
    121     * @return options with requested setting for formatting
    122     */
    123    public ConfigRenderOptions setFormatted(boolean value) {
    124        if (value == formatted)
    125            return this;
    126        else
    127            return new ConfigRenderOptions(originComments, comments, value, json, showEnvVariableValues);
    128    }
    129
    130    /**
    131     * Returns whether the options enable formatting. This method is mostly used
    132     * by the config lib internally, not by applications.
    133     *
    134     * @return true if the options enable formatting
    135     */
    136    public boolean getFormatted() {
    137        return formatted;
    138    }
    139
    140    /**
    141     * Returns options with JSON toggled. JSON means that HOCON extensions
    142     * (omitting commas, quotes for example) won't be used. However, whether to
    143     * use comments is controlled by the separate {@link #setComments(boolean)}
    144     * and {@link #setOriginComments(boolean)} options. So if you enable
    145     * comments you will get invalid JSON despite setting this to true.
    146     *
    147     * @param value
    148     *            true to include non-JSON extensions in the render
    149     * @return options with requested setting for JSON
    150     */
    151    public ConfigRenderOptions setJson(boolean value) {
    152        if (value == json)
    153            return this;
    154        else
    155            return new ConfigRenderOptions(originComments, comments, formatted, value, showEnvVariableValues);
    156    }
    157
    158    /**
    159     * Returns options with showEnvVariableValues toggled. This controls if values set from
    160     * environment variables are included in the rendered string.
    161     *
    162     * @param value
    163     *            true to include environment variable values in the render
    164     * @return options with requested setting for environment variables
    165     */
    166    public ConfigRenderOptions setShowEnvVariableValues(boolean value) {
    167        if (value == showEnvVariableValues)
    168            return this;
    169        else
    170            return new ConfigRenderOptions(originComments, comments, formatted, json, value);
    171    }
    172
    173    /**
    174     * Returns whether the options enable rendering of environment variable values. This method is mostly used
    175     * by the config lib internally, not by applications.
    176     *
    177     * @return true if environment variable values should be rendered
    178     */
    179    public boolean getShowEnvVariableValues() {
    180        return showEnvVariableValues;
    181    }
    182
    183    /**
    184     * Returns whether the options enable JSON. This method is mostly used by
    185     * the config lib internally, not by applications.
    186     *
    187     * @return true if only JSON should be rendered
    188     */
    189    public boolean getJson() {
    190        return json;
    191    }
    192
    193    @Override
    194    public String toString() {
    195        StringBuilder sb = new StringBuilder("ConfigRenderOptions(");
    196        if (originComments)
    197            sb.append("originComments,");
    198        if (comments)
    199            sb.append("comments,");
    200        if (formatted)
    201            sb.append("formatted,");
    202        if (json)
    203            sb.append("json,");
    204        if (showEnvVariableValues)
    205            sb.append("showEnvVariableValues,");
    206        if (sb.charAt(sb.length() - 1) == ',')
    207            sb.setLength(sb.length() - 1);
    208        sb.append(")");
    209        return sb.toString();
    210    }
    211}