Module: YAML

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

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

### 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_builtin_type( type_tag, &transfer_proc )

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_domain_type( domain, type_tag, &transfer_proc )

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_private_type( type_re, &transfer_proc )

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_ruby_type( type, &transfer_proc )

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_implicit( val )

Detect typing of a string

[Source]

    # File yaml.rb, line 327
        def YAML.detect_implicit( val )
            resolver.detect_implicit( val )
        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"

[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

dump_stream( *objs )

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

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

[Source]

    # File yaml.rb, line 216
            def YAML.each_document( io, &block )
                    yp = parser.load_documents( io, &block )
        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

[Source]

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

emitter()

Returns a new default emitter

[Source]

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

escape( value, skip = "" )

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

generic_parser()

Returns a new generic parser

[Source]

    # File yaml.rb, line 97
        def YAML.generic_parser; Parser.new.set_resolver( GenericResolver ); end

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

[Source]

    # File yaml.rb, line 132
            def YAML.load( io )
                    yp = parser.load( io )
            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

[Source]

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

load_file( filepath )

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

load_stream( io )

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

make_stream( io )

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

object_maker( obj_class, val )

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( 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>

[Source]

    # File yaml.rb, line 175
            def YAML.parse( io )
                    yp = generic_parser.load( io )
            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

[Source]

    # File yaml.rb, line 261
            def YAML.parse_documents( io, &doc_proc )
                    YAML.each_node( io, &doc_proc )
        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">]>

[Source]

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

parser()

Returns a new default parser

[Source]

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

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

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

read_type_class( type, obj_class )

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

resolver()

Returns the default resolver

[Source]

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

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

[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

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

[Source]

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

tagurize( val )

Convert a type_id to a taguri

[Source]

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

transfer( type_id, obj )

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

try_implicit( obj )

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( value )

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]