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 human- friendly 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. YAML is easily readable by humans 2. YAML data is portable between programming languages 3. YAML matches the native data structures of agile languages. 4. YAML has a consistent model to support generic tools. 5. YAML supports one-pass processing. 6. YAML is expressive and extensible. 7. 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 :

Basic YAML Syntax Rules  Example: --- Student-Id: First-Name: John Last-Name: Smith Phone-numbers: 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 = # 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

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? = yml_graph puts " ---> Graph has been loaded!" else puts " ---> Error: #{name}.yml failed to load due to unknown object: puts #{yml_graph.class}." exit end

Extended Example  Please refer to the below files to see the full example. graphn.rb graph.rb create_graph.gn load_graph.gn