View Javadoc

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