Strings, integers, floats, timestamps. These are the types of data that our data structures are fundamentally constructed from. YAML supports many of the basic types which are included in Ruby's standard library.
The Null, Boolean, Integer, Float, Time, and Date types each fit on a single line and map directly to their Ruby counterparts. Here is a sequence containing each of these types, respectively:
- ~ - true - 10 - 10.2 - 2002-08-15T17:18:23.18-06:00 - 2002-08-15
In the above example, the tilde '~' character represents a NilClass object in Ruby. Here's a basic mapping showing some valid YAML elements and their corresponding Ruby classes:
~: NilClass +: TrueClass true: TrueClass True: TrueClass -: FalseClass false: FalseClass False: FalseClass 0: Integer 1: Integer 100: Integer 1,000: Integer 0.0: Float 1.0: Float 100.001: Float 1,000.001: Float 1.00009e+3: Float 2002-08-15T17:18:23.18-06:00: Time 2002-08-15 17:18:23.18 -06:00: Time 1976-07-31: Date
Basic types have their own to_yaml method (like any other object in Ruby), which can be used to generate YAML:
puts( nil.to_yaml ) # prints: # --- ~ puts( true.to_yaml ) # prints: # --- true puts( false.to_yaml ) # prints: # --- (false) puts( 10.to_yaml ) # prints: # --- 10 puts( 20.45.to_yaml ) # prints: # --- 20.45 puts( Time.now.to_yaml ) # prints: # --- 2002-08-15T17:29:01.79-06:00 puts( Date.new( 1976, 07, 31 ).to_yaml ) # prints: # --- 1976-07-31
The triple dash '---' in the above outputs is the YAML separator. Documents which contain a single collection (such as the Collections examples on the last page) don't require a separator. The above examples are not collections, so they require a separator.
Basic types which begin with an alphanumeric character are Strings if they don't fall into one of the above categories.
Strings which span several lines can be represented in YAML as blocks. Blocks begin with either a literal '|' character or a folded '>' character. The block is then dumped into a new level of indentation:
- literal: |
A literal block keeps all
new lines when it is brought
into Ruby.
- folded: >
A folded block will get rid
of its newlines, trading them
for spaces when it is brought
into Ruby.
The String class has a to_yaml method which will determine how to best flow your text in the YAML document. By default, it will attempt to fold your text. If your text has indented portions, it will leave the text as-is and present it as a literal block:
txt = "Just got my (dead-tree, printed-on-paper, I don't know if there's a web " +
"version) copy of Linux Magazine for September, 2002. There's an article by " +
"Dave Thomas about building networked applications in Ruby.\n\nProps to Dave!"
puts txt.to_yaml
# prints:
# --- >-
# Just got my (dead-tree, printed-on-paper, I don't know if there's a web version)
# copy of Linux Magazine for September, 2002. There's an article by Dave Thomas
# about building networked applications in Ruby.
#
#
# Props to Dave!
txt =<<EOF ZenWeb 2.11.0 has been released! I don't think I've remembered to announce any releases in a while, so this one is a tad different. Among the newest changes are: + relative url renderer + massively improved demo/docs :) EOF puts txt.to_yaml # prints: # --- | # # ZenWeb 2.11.0 has been released! # # I don't think I've remembered to announce any releases in a while, so # this one is a tad different. Among the newest changes are: # # + relative url renderer # + massively improved demo/docs # # :) #
Blocks are great because you can use all of the indicator characters freely without needing to escape them. This is actually an incredible advantage to YAML, as YAML documents can contain other YAML documents without needing to encode them! Think of what trouble you have to go through to include XML inside of XML!
Please see the YAML Cookbook for more information on the various string and block types.