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}