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 }