View Javadoc

1   /**
2    * Copyright (c) 2008-2012, http://www.snakeyaml.org
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.yaml.snakeyaml;
17  
18  import java.util.Map;
19  import java.util.TimeZone;
20  
21  import org.yaml.snakeyaml.emitter.Emitter;
22  import org.yaml.snakeyaml.emitter.ScalarAnalysis;
23  import org.yaml.snakeyaml.error.YAMLException;
24  import org.yaml.snakeyaml.nodes.Tag;
25  
26  public class DumperOptions {
27      /**
28       * YAML provides a rich set of scalar styles. Block scalar styles include
29       * the literal style and the folded style; flow scalar styles include the
30       * plain style and two quoted styles, the single-quoted style and the
31       * double-quoted style. These styles offer a range of trade-offs between
32       * expressive power and readability.
33       * 
34       * @see <a href="http://yaml.org/spec/1.1/#id903915">Chapter 9. Scalar
35       *      Styles</a>
36       * @see <a href="http://yaml.org/spec/1.1/#id858081">2.3. Scalars</a>
37       */
38      public enum ScalarStyle {
39          DOUBLE_QUOTED(Character.valueOf('"')), SINGLE_QUOTED(Character.valueOf('\'')), LITERAL(
40                  Character.valueOf('|')), FOLDED(Character.valueOf('>')), PLAIN(null);
41          private Character styleChar;
42  
43          private ScalarStyle(Character style) {
44              this.styleChar = style;
45          }
46  
47          public Character getChar() {
48              return styleChar;
49          }
50  
51          @Override
52          public String toString() {
53              return "Scalar style: '" + styleChar + "'";
54          }
55  
56          public static ScalarStyle createStyle(Character style) {
57              if (style == null) {
58                  return PLAIN;
59              } else {
60                  switch (style) {
61                  case '"':
62                      return DOUBLE_QUOTED;
63                  case '\'':
64                      return SINGLE_QUOTED;
65                  case '|':
66                      return LITERAL;
67                  case '>':
68                      return FOLDED;
69                  default:
70                      throw new YAMLException("Unknown scalar style character: " + style);
71                  }
72              }
73          }
74      }
75  
76      /**
77       * Block styles use indentation to denote nesting and scope within the
78       * document. In contrast, flow styles rely on explicit indicators to denote
79       * nesting and scope.
80       * 
81       * @see <a href="http://www.yaml.org/spec/current.html#id2509255">3.2.3.1.
82       *      Node Styles (http://yaml.org/spec/1.1)</a>
83       */
84      public enum FlowStyle {
85          FLOW(Boolean.TRUE), BLOCK(Boolean.FALSE), AUTO(null);
86  
87          private Boolean styleBoolean;
88  
89          private FlowStyle(Boolean flowStyle) {
90              styleBoolean = flowStyle;
91          }
92  
93          public Boolean getStyleBoolean() {
94              return styleBoolean;
95          }
96  
97          @Override
98          public String toString() {
99              return "Flow style: '" + styleBoolean + "'";
100         }
101     }
102 
103     /**
104      * Platform dependent line break.
105      */
106     public enum LineBreak {
107         WIN("\r\n"), MAC("\r"), UNIX("\n");
108 
109         private String lineBreak;
110 
111         private LineBreak(String lineBreak) {
112             this.lineBreak = lineBreak;
113         }
114 
115         public String getString() {
116             return lineBreak;
117         }
118 
119         @Override
120         public String toString() {
121             return "Line break: " + name();
122         }
123 
124         public static LineBreak getPlatformLineBreak() {
125             String platformLineBreak = System.getProperty("line.separator");
126             for (LineBreak lb : values()) {
127                 if (lb.lineBreak.equals(platformLineBreak)) {
128                     return lb;
129                 }
130             }
131             return LineBreak.UNIX;
132         }
133     }
134 
135     /**
136      * Specification version. Currently supported 1.0 and 1.1
137      */
138     public enum Version {
139         V1_0(new Integer[] { 1, 0 }), V1_1(new Integer[] { 1, 1 });
140 
141         private Integer[] version;
142 
143         private Version(Integer[] version) {
144             this.version = version;
145         }
146 
147         public Integer[] getArray() {
148             return version;
149         }
150 
151         public String getRepresentation() {
152             return version[0] + "." + version[1];
153         }
154 
155         @Override
156         public String toString() {
157             return "Version: " + getRepresentation();
158         }
159     }
160 
161     private ScalarStyle defaultStyle = ScalarStyle.PLAIN;
162     private FlowStyle defaultFlowStyle = FlowStyle.AUTO;
163     private boolean canonical = false;
164     private boolean allowUnicode = true;
165     private boolean allowReadOnlyProperties = false;
166     private int indent = 2;
167     private int bestWidth = 80;
168     private LineBreak lineBreak = LineBreak.UNIX;
169     private boolean explicitStart = false;
170     private boolean explicitEnd = false;
171     private TimeZone timeZone = null;
172 
173     /**
174      * @deprecated do not use explicit root Tag
175      */
176     private Tag explicitRoot = null;
177     private Version version = null;
178     private Map<String, String> tags = null;
179     private Boolean prettyFlow = false;
180 
181     public boolean isAllowUnicode() {
182         return allowUnicode;
183     }
184 
185     /**
186      * Specify whether to emit non-ASCII printable Unicode characters (to
187      * support ASCII terminals). The default value is true.
188      * 
189      * @param allowUnicode
190      *            if allowUnicode is false then all non-ASCII characters are
191      *            escaped
192      */
193     public void setAllowUnicode(boolean allowUnicode) {
194         this.allowUnicode = allowUnicode;
195     }
196 
197     public ScalarStyle getDefaultScalarStyle() {
198         return defaultStyle;
199     }
200 
201     /**
202      * Set default style for scalars. See YAML 1.1 specification, 2.3 Scalars
203      * (http://yaml.org/spec/1.1/#id858081)
204      * 
205      * @param defaultStyle
206      *            set the style for all scalars
207      */
208     public void setDefaultScalarStyle(ScalarStyle defaultStyle) {
209         if (defaultStyle == null) {
210             throw new NullPointerException("Use ScalarStyle enum.");
211         }
212         this.defaultStyle = defaultStyle;
213     }
214 
215     public void setIndent(int indent) {
216         if (indent < Emitter.MIN_INDENT) {
217             throw new YAMLException("Indent must be at least " + Emitter.MIN_INDENT);
218         }
219         if (indent > Emitter.MAX_INDENT) {
220             throw new YAMLException("Indent must be at most " + Emitter.MAX_INDENT);
221         }
222         this.indent = indent;
223     }
224 
225     public int getIndent() {
226         return this.indent;
227     }
228 
229     public void setVersion(Version version) {
230         this.version = version;
231     }
232 
233     public Version getVersion() {
234         return this.version;
235     }
236 
237     /**
238      * Force the emitter to produce a canonical YAML document.
239      * 
240      * @param canonical
241      *            true produce canonical YAML document
242      */
243     public void setCanonical(boolean canonical) {
244         this.canonical = canonical;
245     }
246 
247     public boolean isCanonical() {
248         return this.canonical;
249     }
250 
251     /**
252      * Force the emitter to produce a pretty YAML document when using the flow
253      * style.
254      * 
255      * @param prettyFlow
256      *            true produce pretty flow YAML document
257      */
258     public void setPrettyFlow(boolean prettyFlow) {
259         this.prettyFlow = prettyFlow;
260     }
261 
262     public boolean isPrettyFlow() {
263         return this.prettyFlow;
264     }
265 
266     /**
267      * Specify the preferred width to emit scalars. When the scalar
268      * representation takes more then the preferred with the scalar will be
269      * split into a few lines. The default is 80.
270      * 
271      * @param bestWidth
272      *            the preferred with for scalars.
273      */
274     public void setWidth(int bestWidth) {
275         this.bestWidth = bestWidth;
276     }
277 
278     public int getWidth() {
279         return this.bestWidth;
280     }
281 
282     public LineBreak getLineBreak() {
283         return lineBreak;
284     }
285 
286     public void setDefaultFlowStyle(FlowStyle defaultFlowStyle) {
287         if (defaultFlowStyle == null) {
288             throw new NullPointerException("Use FlowStyle enum.");
289         }
290         this.defaultFlowStyle = defaultFlowStyle;
291     }
292 
293     public FlowStyle getDefaultFlowStyle() {
294         return defaultFlowStyle;
295     }
296 
297     /**
298      * @deprecated do not use explicit root Tag
299      */
300     public Tag getExplicitRoot() {
301         return explicitRoot;
302     }
303 
304     /**
305      * @param expRoot
306      *            tag to be used for the root node. (JavaBeans may use
307      *            Tag.MAP="tag:yaml.org,2002:map")
308      * @deprecated use Tag instead of String
309      */
310     public void setExplicitRoot(String expRoot) {
311         setExplicitRoot(new Tag(expRoot));
312     }
313 
314     /**
315      * @param expRoot
316      *            tag to be used for the root node. (JavaBeans may use
317      *            Tag.MAP="tag:yaml.org,2002:map")
318      * @deprecated do not use explicit root Tag
319      */
320     public void setExplicitRoot(Tag expRoot) {
321         if (expRoot == null) {
322             throw new NullPointerException("Root tag must be specified.");
323         }
324         this.explicitRoot = expRoot;
325     }
326 
327     /**
328      * Specify the line break to separate the lines. It is platform specific:
329      * Windows - "\r\n", old MacOS - "\r", Unix - "\n". The default value is the
330      * one for Unix.
331      */
332     public void setLineBreak(LineBreak lineBreak) {
333         if (lineBreak == null) {
334             throw new NullPointerException("Specify line break.");
335         }
336         this.lineBreak = lineBreak;
337     }
338 
339     public boolean isExplicitStart() {
340         return explicitStart;
341     }
342 
343     public void setExplicitStart(boolean explicitStart) {
344         this.explicitStart = explicitStart;
345     }
346 
347     public boolean isExplicitEnd() {
348         return explicitEnd;
349     }
350 
351     public void setExplicitEnd(boolean explicitEnd) {
352         this.explicitEnd = explicitEnd;
353     }
354 
355     public Map<String, String> getTags() {
356         return tags;
357     }
358 
359     // TODO should use Tag ???
360     public void setTags(Map<String, String> tags) {
361         this.tags = tags;
362     }
363 
364     /**
365      * Define the ScalarStyle to be used for emitting scalars
366      * 
367      * @param analysis
368      *            - Scalar meta data
369      * @param style
370      *            - automatically detected style
371      * @return ScalarStyle to be used for scalar
372      * @deprecated it was implemented as a quick fix for issue 29
373      */
374     public ScalarStyle calculateScalarStyle(ScalarAnalysis analysis, ScalarStyle style) {
375         return style;
376     }
377 
378     /**
379      * Report whether read-only JavaBean properties (the ones without setters)
380      * should be included in the YAML document
381      * 
382      * @return false when read-only JavaBean properties are not emitted
383      */
384     public boolean isAllowReadOnlyProperties() {
385         return allowReadOnlyProperties;
386     }
387 
388     /**
389      * Set to true to include read-only JavaBean properties (the ones without
390      * setters) in the YAML document. By default these properties are not
391      * included to be able to parse later the same JavaBean.
392      * 
393      * @param allowReadOnlyProperties
394      *            - true to dump read-only JavaBean properties
395      */
396     public void setAllowReadOnlyProperties(boolean allowReadOnlyProperties) {
397         this.allowReadOnlyProperties = allowReadOnlyProperties;
398     }
399 
400     public TimeZone getTimeZone() {
401         return timeZone;
402     }
403 
404     /**
405      * Set the timezone to be used for Date. If set to <code>null</code> UTC is
406      * used.
407      */
408     public void setTimeZone(TimeZone timeZone) {
409         this.timeZone = timeZone;
410     }
411 }