Basic Types in YAML

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.

Single-line types

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
Ex. 9: Basic types in YAML

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
Ex. 10: Basic types and their Ruby classes

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
Ex. 11: Using to_yaml with basic types

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.

Multi-line types

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.
Ex. 12: Literal and folded blocks

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!
Ex. 13: Case where to_yaml generates a folded block
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
#   
#   :)
#
Ex. 14: Case where to_yaml generates a literal block

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.