YAML

Inheritance

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

Classes & Modules

Constants

Name		Description
DEFAULTS	= { :Indent => 2, :UseHeader => false, :UseVersion => false, :Version => '1.0', :SortKeys => false, :AnchorFormat => 'id%03d', :ExplicitTypes => false, :WidthType => 'absolute', :BestWidth => 80, :UseBlock => false, :UseFold => false, :Encoding => :None	Default settings
DNS_COMP_RE	= "\\w(?:[-\\w]*\\w)?"
DNS_NAME_RE	= "(?:(?:#{DNS_COMP_RE}\\.)+#{DNS_COMP_RE}\|#{DNS_COMP_RE})"
DefaultResolver	= YAML::Syck::DefaultResolver
ERROR_ANCHOR_ALIAS	= "Can't define both an anchor and an alias"
ERROR_BAD_ALIAS	= "Invalid alias: %s"
ERROR_BAD_ANCHOR	= "Invalid anchor: %s"
ERROR_BAD_EXPLICIT	= "Unsupported explicit transfer: '%s'"
ERROR_MANY_ALIAS	= "More than one alias"
ERROR_MANY_ANCHOR	= "More than one anchor"
ERROR_MANY_EXPLICIT	= "More than one explicit transfer"
ERROR_MANY_IMPLICIT	= "More than one implicit request"
ERROR_NEED_HEADER	= "With UseHeader=false, the node must be an Array or Hash"
ERROR_NO_ANCHOR	= "No anchor for alias '%s'"
ERROR_NO_HEADER_NODE	= "With UseHeader=false, the node Array or Hash must have elements"	Error messages
ERROR_UNSUPPORTED_ENCODING	= "Attempt to use unsupported encoding: %s"
ERROR_UNSUPPORTED_VERSION	= "This release of YAML.rb does not support YAML version %s"
ERROR_ZERO_INDENT	= "Can't use zero as an indentation width"
ESCAPES	= %w{\x00 \x01 \x02 \x03 \x04 \x05 \x06 \a \x08 \t \n \v \f \r \x0e \x0f \x10 \x11 \x12 \x13 \x14 \x15 \x16 \x17 \x18 \x19 \x1a \e \x1c \x1d \x1e \x1f }
ESCAPE_CHAR	= '[\\x00-\\x09\\x0b-\\x1f]'
Emitter	= YAML::Syck::Emitter
GenericResolver	= YAML::Syck::GenericResolver
INDICATOR_CHAR	= '*&!\|\\\\^@%{}[]='
NOT_PLAIN_CHAR	= '\x7f\x0-\x1f\x80-\x9f'
PRINTABLE_CHAR	= '-_A-Za-z0-9!?/()$\'". '
Parser	= YAML::Syck::Parser
RESTRICTED_INDICATORS	= '#:,}]'
Resolver	= YAML::Syck::Resolver
SPACE_INDICATORS	= '-#:,?'
SUPPORTED_YAML_VERSIONS	= ['1.0']
UNESCAPES	= { 'a' => "\x07", 'b' => "\x08", 't' => "\x09", 'n' => "\x0a", 'v' => "\x0b", 'f' => "\x0c", 'r' => "\x0d", 'e' => "\x1b", '\\' => '\\', }
VERSION	= '0.60'	Constants
WORD_CHAR	= 'A-Za-z0-9'	Parser tokens

Methods

Class

Visibility	Signature
public	add_builtin_type ( type_tag, &transfer_proc )
public	add_domain_type ( domain, type_tag, &transfer_proc )
public	add_private_type ( type_re, &transfer_proc )
public	add_ruby_type ( type_tag, &transfer_proc )
public	detect_implicit ( val )
public	dump ( obj, io = nil )
public	dump_stream ( *objs )
public	each_document ( io, &block )
public	each_node ( io, &doc_proc )
public	emitter ()
public	escape ( value, skip = "" )
public	generic_parser ()
public	load ( io )
public	load_documents ( io, &doc_proc )
public	load_file ( filepath )
public	load_stream ( io )
public	make_stream ( io )
public	object_maker ( obj_class, val )
public	parse ( io )
public	parse_documents ( io, &doc_proc )
public	parse_file ( filepath )
public	parser ()
public	quick_emit ( oid, opts = {}, &e )
public	read_type_class ( type, obj_class )
public	resolver ()
public	tag_class ( tag, cls )
public	tagged_classes ()
public	tagurize ( val )
public	transfer ( type_id, obj )
public	try_implicit ( obj )
public	unescape ( value )

Class Method Detail

add_builtin_type( type_tag, &transfer_proc )

Add a transfer method for a builtin type

add_domain_type( domain, type_tag, &transfer_proc )

Add a global handler for a YAML domain type.

add_private_type( type_re, &transfer_proc )

Add a private document type

add_ruby_type( type_tag, &transfer_proc )

Add a transfer method for a builtin 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

escape( value, skip = "" )

Escape the string, condensing common escapes

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.

make_stream( io )

Class method for creating streams

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

tag_class( tag, cls )

Associates a taguri tag with a Ruby class cls. The taguri is used to give types to classes when loading YAML. Taguris are of the form:

  tag:authorityName,date:specific

The authorityName is a domain name or email address. The date is the date the type was issued in YYYY or YYYY-MM or YYYY-MM-DD format. The specific is a name for the type being added.

For example, built-in YAML types have ‘yaml.org’ as the authorityName and ‘2002’ as the date. The specific is simply the name of the type:

 tag:yaml.org,2002:int
 tag:yaml.org,2002:float
 tag:yaml.org,2002:timestamp

The domain must be owned by you on the date declared. If you don‘t own any domains on the date you declare the type, you can simply use an e-mail address.

 tag:why@ruby-lang.org,2004:notes/personal

tagged_classes()

Returns the complete dictionary of taguris, paired with classes. The key for the dictionary is the full taguri. The value for each key is the class constant associated to that taguri.

 YAML.tagged_classes["tag:yaml.org,2002:int"] => Integer

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

unescape( value )

Unescape the condenses escapes