Module: YAML

Module

YAML

In:

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 loader, use add_domain_type.

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

Public Class methods

add_builtin_type( type_re, &transfer_proc )

Add a transfer method for a builtin type

     # File lib/yaml.rb, line 293
293:         def YAML.add_builtin_type( type_re, &transfer_proc )
294:             @@loader.add_builtin_type( type_re, &transfer_proc )
295:         end

add_domain_type( domain, type_re, &transfer_proc )

Add a global handler for a YAML domain type.

     # File lib/yaml.rb, line 286
286:         def YAML.add_domain_type( domain, type_re, &transfer_proc )
287:         @@loader.add_domain_type( domain, type_re, &transfer_proc )
288:         end

add_private_type( type_re, &transfer_proc )

Add a private document type

     # File lib/yaml.rb, line 307
307:         def YAML.add_private_type( type_re, &transfer_proc )
308:             @@loader.add_private_type( type_re, &transfer_proc )
309:         end

add_ruby_type( type, &transfer_proc )

Add a transfer method for a builtin type

     # File lib/yaml.rb, line 300
300:         def YAML.add_ruby_type( type, &transfer_proc )
301:         @@loader.add_ruby_type( type, &transfer_proc )
302:         end

detect_implicit( val )

Detect typing of a string

     # File lib/yaml.rb, line 314
314:     def YAML.detect_implicit( val )
315:         @@loader.detect_implicit( val )
316:     end

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"

     # File lib/yaml.rb, line 101
101:         def YAML.dump( obj, io = nil )
102:         io ||= ""
103:         io << obj.to_yaml
104:         io
105:         end

dump_stream( *objs )

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

  YAML.dump_stream( 0, [], {} )
    #=> --- 0
        --- []
        --- {}

     # File lib/yaml.rb, line 275
275:         def YAML.dump_stream( *objs )
276:                 d = YAML::Stream.new
277:         objs.each do |doc|
278:                         d.add( doc ) 
279:         end
280:         d.emit
281:         end

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

     # File lib/yaml.rb, line 202
202:         def YAML.each_document( io, &block )
203:                 yp = @@parser.new.load_documents( io, &block )
204:     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

     # File lib/yaml.rb, line 232
232:         def YAML.each_node( io, &doc_proc )
233:                 yp = @@parser.new( :Model => :Generic ).load_documents( io, &doc_proc )
234:     end

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

     # File lib/yaml.rb, line 118
118:         def YAML.load( io )
119:                 yp = @@parser.new.load( io )
120:         end

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

     # File lib/yaml.rb, line 217
217:         def YAML.load_documents( io, &doc_proc )
218:                 YAML.each_document( io, &doc_proc )
219:     end

load_file( filepath )

Load a document from the file located at filepath.

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

     # File lib/yaml.rb, line 128
128:     def YAML.load_file( filepath )
129:         File.open( filepath ) do |f|
130:             load( f )
131:         end
132:     end

load_stream( io )

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

     # File lib/yaml.rb, line 256
256:         def YAML.load_stream( io )
257:                 yp = @@parser.new
258:                 d = nil
259:                 yp.load_documents( io ) { |doc|
260:                         d = YAML::Stream.new( yp.options ) if not d
261:                         d.add( doc ) 
262:                 }
263:                 return d
264:         end

object_maker( obj_class, val )

Allocate blank object

     # File lib/yaml.rb, line 345
345:     def YAML.object_maker( obj_class, val )
346:         if Hash === val
347:             o = obj_class.allocate
348:             val.each_pair { |k,v|
349:                 o.instance_variable_set("@#{k}", v)
350:             }
351:             o
352:         else
353:             raise YAML::Error, "Invalid object explicitly tagged !ruby/Object: " + val.inspect
354:         end
355:     end

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.load( "--- :locked" )
     #=> #<YAML::Syck::Node:0x82edddc
           @type_id="tag:ruby.yaml.org,2002:sym",
           @value=":locked", @kind=:scalar>

     # File lib/yaml.rb, line 161
161:         def YAML.parse( io )
162:                 yp = @@parser.new( :Model => :Generic ).load( io )
163:         end

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

     # File lib/yaml.rb, line 247
247:         def YAML.parse_documents( io, &doc_proc )
248:                 YAML.each_node( io, &doc_proc )
249:     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">]>

     # File lib/yaml.rb, line 185
185:     def YAML.parse_file( filepath )
186:         File.open( filepath ) do |f|
187:             parse( f )
188:         end
189:     end

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

Allocate an Emitter if needed

     # File lib/yaml.rb, line 360
360:         def YAML.quick_emit( oid, opts = {}, &e )
361:                 old_opt = nil
362:                 if opts[:Emitter].is_a? @@emitter
363:                         out = opts.delete( :Emitter )
364:                         old_opt = out.options.dup
365:                         out.options.update( opts )
366:                 else
367:                         out = @@emitter.new( opts )
368:                 end
369:         aidx = out.start_object( oid )
370:         if aidx
371:             out.simple( "*#{ aidx }" )
372:         else
373:             e.call( out )
374:         end
375:                 if old_opt.is_a? Hash
376:                         out.options = old_opt
377:                 end 
378:                 out.end_object
379:         end

read_type_class( type, obj_class )

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

     # File lib/yaml.rb, line 336
336:     def YAML.read_type_class( type, obj_class )
337:         scheme, domain, type, tclass = type.split( ':', 4 )
338:         tclass.split( "::" ).each { |c| obj_class = obj_class.const_get( c ) } if tclass
339:         return [ type, obj_class ]
340:     end

transfer( type_id, obj )

Apply a transfer method to a Ruby object

     # File lib/yaml.rb, line 321
321:     def YAML.transfer( type_id, obj )
322:         @@loader.transfer( type_id, obj )
323:     end

try_implicit( obj )

Apply any implicit a node may qualify for

     # File lib/yaml.rb, line 328
328:         def YAML.try_implicit( obj )
329:                 YAML.transfer( YAML.detect_implicit( obj ), obj )
330:         end