An Introductory Tutorial
Background and Purpose
What is YAML?
Human friendly, cross language,
Unicode based data serialization
language.
 Pronounced in such a way as to rhyme
with “camel”
 Acronym for

YAML
Ain’t
Markup
Language
What is a data serialization
language?
A language used to convert or represent
structured data or objects as a series of
characters that can be stored on a disk.
 Examples:

 CSV – Comma separated values
 XML – Extensible markup language
 JSON – JavaScript object notation
 YAML – YAML ain’t markup language
Why YAML if XML?
Unlike XML which is not easily readable by
humans, YAML was created to be humanfriendly and integrate easily with modern
programming languages.
 Unlike with XML, YAML was intended to
simplify the viewing and understanding of
config files, log files, object persistence,
and messaging, to allow the programmer to
spend more time programming and less
time formatting data.

YAML Design Goals

As stated in the YAML official specification, the
design goals for YAML in decreasing priority
are:
1.
2.
3.
4.
5.
6.
7.
YAML is easily readable by humans
YAML data is portable between programming
languages
YAML matches the native data structures of agile
languages.
YAML has a consistent model to support generic
tools.
YAML supports one-pass processing.
YAML is expressive and extensible.
YAML is easy to implement and use.
Syntax and Language Elements
Basic YAML Syntax Rules
Documents begin with --- and end with
…
 Indentation of lines denotes the
structure within the document.
 Comments begin with #
 Members of lists begin with –
 Key value pairs use the following syntax

 <key>: <value>
Basic YAML Syntax Rules

Example:
--Student-Id: 11223344
First-Name: John
Last-Name: Smith
Phone-numbers:
- 281.555.7689
- 713.555.8967
- 832.555.9980
Addresses:
- street: 123 Main St.
city: Houston
state: TX
...
Advanced YAML Syntax

There is more advanced syntaxes that
exist that allow YAML to represent
 Relational trees
○ *, <<, and & are used for node reference,
array merges, and anchoring respectively
 User defined data types

These are beyond the scope of this
introductory tutorial.
Integration and Usage
How to Integrate YAML and Ruby?
Thankfully, YAML support comes built in
to Ruby with the use of the yaml library.
 Simply add the below Ruby code to the
top of any Ruby file to get YAML
support.

 require ‘yaml’
How to Integrate YAML and Ruby
After the yaml library has been included in
a file, you then have access to the to_yaml
method that can be used on any Ruby
Object.
 to_yaml returns a String in YAML syntax
that represents the Object being converted.
 Remember, everything in Ruby is an
Object, therefore everything can easily be
converted to YAML notation and written to
disk.

How to Integrate YAML and Ruby

Example:
require 'yaml'
class Graph
attr_reader :graph_name
# Serializes a graph to YAML format and saves it to
# a file with the same name as the graph
# and returns the path to the file.
def serialize
# build the filename for the serialized data
file_name = "#{@graph_name}.yml"
# create and write the YAML data to the file
File.open(file_name, 'w+') do |f|
f.write(self.to_yaml)
end
# return the file path
File.path(file_name)
end
end
How to Integrate YAML and Ruby

Example:
# Restores a previously saved graph from its corresponding YAML file
# with the passed in name.
def loadGraph(name)
# the DSL expects the name argument to be a String.
validate_stringness_of name, :method => :loadGraph
# load the YAML file from the disk
print "Loading #{name}.yml"
yml_graph = YAML.load_file "#{name}.yml"
# ensure the data loaded is actually a Graph and set it to the Graph instance variable.
# otherwise let the user know that there was no Graph data in the YAML file.
if yml_graph.kind_of? Graph
@graph = yml_graph
puts " ---> Graph #{@graph.graph_name} has been loaded!"
else
puts " ---> Error: #{name}.yml failed to load due to unknown object:
puts #{yml_graph.class}."
exit
end
end
Extended Example

Please refer to the below files to see the
full example.
 graphn.rb
 graph.rb
 create_graph.gn
 load_graph.gn