Module YAML
In: yaml.rb
yaml/ypath.rb
yaml/yamlnode.rb
yaml/types.rb
yaml/tag.rb
yaml/syck.rb
yaml/stream.rb
yaml/loader.rb
yaml/error.rb
yaml/encoding.rb
yaml/dbm.rb
yaml/constants.rb
yaml/basenode.rb
yaml/baseemitter.rb

Constants used throughout the library

Methods

Classes and Modules

Module YAML::BaseEmitter
Module YAML::BaseNode
Module YAML::Syck
Class YAML::DBM
Class YAML::DomainType
Class YAML::Error
Class YAML::Loader
Class YAML::Mapping
Class YAML::Object
Class YAML::Omap
Class YAML::Pairs
Class YAML::ParseError
Class YAML::PrivateType
Class YAML::Sequence
Class YAML::Set
Class YAML::SpecialHash
Class YAML::Store
Class YAML::Stream
Class YAML::TypeError
Class YAML::YPath
Class YAML::YamlNode

Constants

Resolver = YAML::Syck::Resolver
DefaultResolver = YAML::Syck::DefaultResolver
GenericResolver = YAML::Syck::GenericResolver
Parser = YAML::Syck::Parser
Emitter = YAML::Syck::Emitter
ERROR_NO_HEADER_NODE = "With UseHeader=false, the node Array or Hash must have elements"   Error messages
ERROR_NEED_HEADER = "With UseHeader=false, the node must be an Array or Hash"
ERROR_BAD_EXPLICIT = "Unsupported explicit transfer: '%s'"
ERROR_MANY_EXPLICIT = "More than one explicit transfer"
ERROR_MANY_IMPLICIT = "More than one implicit request"
ERROR_NO_ANCHOR = "No anchor for alias '%s'"
ERROR_BAD_ANCHOR = "Invalid anchor: %s"
ERROR_MANY_ANCHOR = "More than one anchor"
ERROR_ANCHOR_ALIAS = "Can't define both an anchor and an alias"
ERROR_BAD_ALIAS = "Invalid alias: %s"
ERROR_MANY_ALIAS = "More than one alias"
ERROR_ZERO_INDENT = "Can't use zero as an indentation width"
ERROR_UNSUPPORTED_VERSION = "This release of YAML.rb does not support YAML version %s"
ERROR_UNSUPPORTED_ENCODING = "Attempt to use unsupported encoding: %s"
VERSION = '0.60'   Constants
SUPPORTED_YAML_VERSIONS = ['1.0']
WORD_CHAR = 'A-Za-z0-9'   Parser tokens
PRINTABLE_CHAR = '-_A-Za-z0-9!?/()$\'". '
NOT_PLAIN_CHAR = '\x7f\x0-\x1f\x80-\x9f'
ESCAPE_CHAR = '[\\x00-\\x09\\x0b-\\x1f]'
INDICATOR_CHAR = '*&!|\\\\^@%{}[]='
SPACE_INDICATORS = '-#:,?'
RESTRICTED_INDICATORS = '#:,}]'
DNS_COMP_RE = "\\w(?:[-\\w]*\\w)?"
DNS_NAME_RE = "(?:(?:#{DNS_COMP_RE}\\.)+#{DNS_COMP_RE}|#{DNS_COMP_RE})"
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 }
UNESCAPES = { 'a' => "\x07", 'b' => "\x08", 't' => "\x09", 'n' => "\x0a", 'v' => "\x0b", 'f' => "\x0c", 'r' => "\x0d", 'e' => "\x1b", '\\' => '\\', }
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

Public Class methods

Add a transfer method for a builtin type

[Source]

# File yaml.rb, line 306
        def YAML.add_builtin_type( type_tag, &transfer_proc )
            resolver.add_type( "tag:yaml.org,2002:#{ type_tag }", transfer_proc )
        end

Add a global handler for a YAML domain type.

[Source]

# File yaml.rb, line 299
        def YAML.add_domain_type( domain, type_tag, &transfer_proc )
        resolver.add_type( "tag:#{ domain }:#{ type_tag }", transfer_proc )
        end

Add a private document type

[Source]

# File yaml.rb, line 320
        def YAML.add_private_type( type_re, &transfer_proc )
            resolver.add_type( "x-private:" + type_re, transfer_proc )
        end

Add a transfer method for a builtin type

[Source]

# File yaml.rb, line 313
        def YAML.add_ruby_type( type, &transfer_proc )
            resolver.add_type( "tag:ruby.yaml.org,2002:#{ type_tag }", transfer_proc )
        end

Detect typing of a string

[Source]

# File yaml.rb, line 327
    def YAML.detect_implicit( val )
        resolver.detect_implicit( val )
    end

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"

[Source]

# File yaml.rb, line 116
        def YAML.dump( obj, io = nil )
        obj.to_yaml( io || io2 = StringIO.new )
        io || ( io2.rewind; io2.read )
        end

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

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

[Source]

# File yaml.rb, line 288
        def YAML.dump_stream( *objs )
                d = YAML::Stream.new
        objs.each do |doc|
                        d.add( doc ) 
        end
        d.emit
        end

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

[Source]

# File yaml.rb, line 216
        def YAML.each_document( io, &block )
                yp = parser.load_documents( io, &block )
    end

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

[Source]

# File yaml.rb, line 246
        def YAML.each_node( io, &doc_proc )
                yp = generic_parser.load_documents( io, &doc_proc )
    end

Returns a new default emitter

[Source]

# File yaml.rb, line 101
    def YAML.emitter; Emitter.new.set_resolver( YAML.resolver ); end

Escape the string, condensing common escapes

[Source]

# File yaml/encoding.rb, line 10
        def YAML.escape( value, skip = "" )
                value.gsub( /\\/, "\\\\\\" ).
              gsub( /"/, "\\\"" ).
              gsub( /([\x00-\x1f])/ ) do |x|
                 skip[x] || ESCAPES[ x.unpack("C")[0] ]
             end
        end

Returns a new generic parser

[Source]

# File yaml.rb, line 97
    def YAML.generic_parser; Parser.new.set_resolver( GenericResolver ); 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

[Source]

# File yaml.rb, line 132
        def YAML.load( io )
                yp = parser.load( io )
        end

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

[Source]

# File yaml.rb, line 231
        def YAML.load_documents( io, &doc_proc )
                YAML.each_document( io, &doc_proc )
    end

Load a document from the file located at filepath.

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

[Source]

# File yaml.rb, line 142
    def YAML.load_file( filepath )
        File.open( filepath ) do |f|
            load( f )
        end
    end

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

[Source]

# File yaml.rb, line 270
        def YAML.load_stream( io )
                d = nil
                parser.load_documents( io ) do |doc|
                        d = YAML::Stream.new if not d
                        d.add( doc ) 
        end
                return d
        end

Class method for creating streams

[Source]

# File yaml/stringio.rb, line 55
        def YAML.make_stream( io )
        if String === io
            io = StringIO.new( io )
        elsif not IO === io
            raise YAML::Error, "YAML stream must be an IO or String object."
        end
        if YAML::unicode
            def io.readline
                YAML.utf_to_internal( readline( @ln_sep ), @utf_encoding )
            end
            def io.check_unicode
                @utf_encoding = YAML.sniff_encoding( read( 4 ) )
                @ln_sep = YAML.enc_separator( @utf_encoding )
                seek( -4, IO::SEEK_CUR )
            end
                    def io.utf_encoding
                      @utf_encoding
                    end
            io.check_unicode
        else
            def io.utf_encoding
                :None
            end
        end
        io
        end

Allocate blank object

[Source]

# File yaml.rb, line 365
    def YAML.object_maker( obj_class, val )
        if Hash === val
            o = obj_class.allocate
            val.each_pair { |k,v|
                o.instance_variable_set("@#{k}", v)
            }
            o
        else
            raise YAML::Error, "Invalid object explicitly tagged !ruby/Object: " + val.inspect
        end
    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.parse( "--- :locked" )
     #=> #<YAML::Syck::Node:0x82edddc
           @type_id="tag:ruby.yaml.org,2002:sym",
           @value=":locked", @kind=:scalar>

[Source]

# File yaml.rb, line 175
        def YAML.parse( io )
                yp = generic_parser.load( io )
        end

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

[Source]

# File yaml.rb, line 261
        def YAML.parse_documents( io, &doc_proc )
                YAML.each_node( io, &doc_proc )
    end

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">]>

[Source]

# File yaml.rb, line 199
    def YAML.parse_file( filepath )
        File.open( filepath ) do |f|
            parse( f )
        end
    end

Returns a new default parser

[Source]

# File yaml.rb, line 95
    def YAML.parser; Parser.new.set_resolver( YAML.resolver ); end

Allocate an Emitter if needed

[Source]

# File yaml.rb, line 380
        def YAML.quick_emit( oid, opts = {}, &e )
        out = 
            if opts.is_a? YAML::Emitter
                opts
            else
                emitter.reset( opts )
            end
        out.emit( oid, &e )
        end

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

[Source]

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

Returns the default resolver

[Source]

# File yaml.rb, line 99
    def YAML.resolver; DefaultResolver; end

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

[Source]

# File yaml/tag.rb, line 35
    def YAML.tag_class( tag, cls )
        if @@tagged_classes.has_key? tag
            warn "class #{ @@tagged_classes[tag] } held ownership of the #{ tag } tag"
        end
        @@tagged_classes[tag] = cls
    end

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

[Source]

# File yaml/tag.rb, line 48
    def YAML.tagged_classes
        @@tagged_classes
    end

Convert a type_id to a taguri

[Source]

# File yaml.rb, line 334
    def YAML.tagurize( val )
        resolver.tagurize( val )
    end

Apply a transfer method to a Ruby object

[Source]

# File yaml.rb, line 341
    def YAML.transfer( type_id, obj )
        resolver.transfer( YAML.tagurize( type_id ), obj )
    end

Apply any implicit a node may qualify for

[Source]

# File yaml.rb, line 348
        def YAML.try_implicit( obj )
                YAML.transfer( YAML.detect_implicit( obj ), obj )
        end

Unescape the condenses escapes

[Source]

# File yaml/encoding.rb, line 21
        def YAML.unescape( value )
                value.gsub( /\\(?:([nevfbart\\])|0?x([0-9a-fA-F]{2})|u([0-9a-fA-F]{4}))/ ) { |x| 
                        if $3
                                ["#$3".hex ].pack('U*')
                        elsif $2
                                [$2].pack( "H2" ) 
                        else
                                UNESCAPES[$1] 
                        end
                }
        end

[Validate]