Module YAML
In: lib/yaml.rb

YAML

YAML(tm) (rhymes with ‘camel’) is a straightforward machine parsable data serialization format designed for human readability and interaction with scripting languages such as Perl and Python. YAML is optimized for data serialization, formatted dumping, configuration files, log files, Internet messaging and filtering. This specification describes the YAML information model and serialization format. Together with the Unicode standard for characters, it provides all the information necessary to understand YAML Version 1.0 and construct computer programs to process it.

See yaml.org/ for more information. For a quick tutorial, please visit YAML In Five Minutes (yaml.kwiki.org/?YamlInFiveMinutes).

About This Library

The YAML 1.0 specification outlines four stages of YAML loading and dumping. This library honors all four of those stages, although data is really only available to you in three stages.

The four stages are: native, representation, serialization, and presentation.

The native stage refers to data which has been loaded completely into Ruby‘s own types. (See +YAML::load+.)

The representation stage means data which has been composed into +YAML::BaseNode+ objects. In this stage, the document is available as a tree of node objects. You can perform YPath queries and transformations at this level. (See +YAML::parse+.)

The serialization stage happens inside the parser. The YAML parser used in Ruby is called Syck. Serialized nodes are available in the extension as SyckNode structs.

The presentation stage is the YAML document itself. This is accessible to you as a string. (See +YAML::dump+.)

For more information about the various information models, see Chapter 3 of the YAML 1.0 Specification (yaml.org/spec/#id2491269).

The YAML module provides quick access to the most common loading (YAML::load) and dumping (YAML::dump) tasks. This module also provides an API for registering global types (YAML::add_domain_type).

Example

A simple round-trip (load and dump) of an object. 

    require "yaml"

    test_obj = ["dogs", "cats", "badgers"]

    yaml_obj = YAML::dump( test_obj )
                        # -> ---
                             - dogs
                             - cats
                             - badgers
    ruby_obj = YAML::load( yaml_obj )
                        # => ["dogs", "cats", "badgers"]
    ruby_obj == test_obj
                        # => true

To register your custom types with the global resolver, use add_domain_type. 

    YAML::add_domain_type( "your-site.com,2004", "widget" ) do |type, val|
        Widget.new( val )
    end

Methods

add_builtin_type   add_domain_type   add_private_type   add_ruby_type   detect_implicit   dump   dump_stream   each_document   each_node   emitter   generic_parser   load   load_documents   load_file   load_stream   object_maker   parse   parse_documents   parse_file   parser   quick_emit   read_type_class   resolver   tagurize   transfer   try_implicit  

Constants

Resolver = YAML::Syck::Resolver
DefaultResolver = YAML::Syck::DefaultResolver
GenericResolver = YAML::Syck::GenericResolver
Parser = YAML::Syck::Parser
Emitter = YAML::Syck::Emitter

Public Class methods

add_domain_type( domain, type_tag, &transfer_proc )

Add a global handler for a YAML domain type.

detect_implicit( val )

Detect typing of a string

dump( obj, io = nil )

Converts obj to YAML and writes the YAML result to io. 

  File.open( 'animals.yaml', 'w' ) do |out|
    YAML.dump( ['badger', 'elephant', 'tiger'], out )
  end

If no io is provided, a string containing the dumped YAML is returned. 

  YAML.dump( :locked )
     #=> "--- :locked"
dump_stream( *objs )

Returns a YAML stream containing each of the items in objs, each having their own document. 

  YAML.dump_stream( 0, [], {} )
    #=> --- 0
        --- []
        --- {}
each_document( io, &block )

Calls block with each consecutive document in the YAML stream contained in io. 

  File.open( 'many-docs.yaml' ) do |yf|
    YAML.each_document( yf ) do |ydoc|
      ## ydoc contains the single object
      ## from the YAML document
    end
  end
each_node( io, &doc_proc )

Calls block with a tree of +YAML::BaseNodes+, one tree for each consecutive document in the YAML stream contained in io. 

  File.open( 'many-docs.yaml' ) do |yf|
    YAML.each_node( yf ) do |ydoc|
      ## ydoc contains a tree of nodes
      ## from the YAML document
    end
  end
emitter()

Returns a new default emitter

generic_parser()

Returns a new generic parser

load( io )

Load a document from the current io stream. 

  File.open( 'animals.yaml' ) { |yf| YAML::load( yf ) }
     #=> ['badger', 'elephant', 'tiger']

Can also load from a string. 

  YAML.load( "--- :locked" )
     #=> :locked
load_documents( io, &doc_proc )

Calls block with each consecutive document in the YAML stream contained in io. 

  File.open( 'many-docs.yaml' ) do |yf|
    YAML.load_documents( yf ) do |ydoc|
      ## ydoc contains the single object
      ## from the YAML document
    end
  end
load_file( filepath )

Load a document from the file located at filepath. 

  YAML.load_file( 'animals.yaml' )
     #=> ['badger', 'elephant', 'tiger']
load_stream( io )

Loads all documents from the current io stream, returning a +YAML::Stream+ object containing all loaded documents.

object_maker( obj_class, val )

Allocate blank object

parse( io )

Parse the first document from the current io stream 

  File.open( 'animals.yaml' ) { |yf| YAML::load( yf ) }
     #=> #<YAML::Syck::Node:0x82ccce0
          @kind=:seq,
          @value=
           [#<YAML::Syck::Node:0x82ccd94
             @kind=:scalar,
             @type_id="str",
             @value="badger">,
            #<YAML::Syck::Node:0x82ccd58
             @kind=:scalar,
             @type_id="str",
             @value="elephant">,
            #<YAML::Syck::Node:0x82ccd1c
             @kind=:scalar,
             @type_id="str",
             @value="tiger">]>

Can also load from a string. 

  YAML.parse( "--- :locked" )
     #=> #<YAML::Syck::Node:0x82edddc
           @type_id="tag:ruby.yaml.org,2002:sym",
           @value=":locked", @kind=:scalar>
parse_documents( io, &doc_proc )

Calls block with a tree of +YAML::BaseNodes+, one tree for each consecutive document in the YAML stream contained in io. 

  File.open( 'many-docs.yaml' ) do |yf|
    YAML.parse_documents( yf ) do |ydoc|
      ## ydoc contains a tree of nodes
      ## from the YAML document
    end
  end
parse_file( filepath )

Parse a document from the file located at filepath. 

  YAML.parse_file( 'animals.yaml' )
     #=> #<YAML::Syck::Node:0x82ccce0
          @kind=:seq,
          @value=
           [#<YAML::Syck::Node:0x82ccd94
             @kind=:scalar,
             @type_id="str",
             @value="badger">,
            #<YAML::Syck::Node:0x82ccd58
             @kind=:scalar,
             @type_id="str",
             @value="elephant">,
            #<YAML::Syck::Node:0x82ccd1c
             @kind=:scalar,
             @type_id="str",
             @value="tiger">]>
parser()

Returns a new default parser

quick_emit( oid, opts = {}, &e )

Allocate an Emitter if needed

read_type_class( type, obj_class )

Method to extract colon-seperated type and class, returning the type and the constant of the class

resolver()

Returns the default resolver

tagurize( val )

Convert a type_id to a taguri

transfer( type_id, obj )

Apply a transfer method to a Ruby object

try_implicit( obj )

Apply any implicit a node may qualify for

[Validate]

ruby-doc.org is a service of James Britt and Neurogami, a Ruby application development company in Phoenix, AZ.

Documentation content on ruby-doc.org is provided by remarkable members of the Ruby community.

For more information on the Ruby programming language, visit ruby-lang.org.

Want to help improve Ruby's API docs? See Ruby Documentation Guidelines.