concordia-publishing-house-syck 1.0.0.4

data/ext/syck/yaml2byte.c

@@ -0,0 +1,259 @@
+/*
+ * yaml2byte.c
+ *
+ * $Author$
+ *
+ * Copyright (C) 2003 why the lucky stiff, clark evans
+ *
+ *   WARNING WARNING WARNING  --- THIS IS *NOT JUST* PLAYING
+ *   ANYMORE! -- WHY HAS EMBRACED THIS AS THE REAL THING!
+ */
+#include "ruby/ruby.h"
+#include <syck.h>
+#include <assert.h>
+#define YAMLBYTE_UTF8
+#include "yamlbyte.h"
+
+#include <stdio.h>
+#define TRACE0(a)  \
+    do { printf(a); printf("\n"); fflush(stdout); } while(0)
+#define TRACE1(a,b) \
+    do { printf(a,b); printf("\n"); fflush(stdout); } while(0)
+#define TRACE2(a,b,c) \
+    do { printf(a,b,c); printf("\n"); fflush(stdout); } while(0)
+#define TRACE3(a,b,c,d) \
+    do { printf(a,b,c,d); printf("\n"); fflush(stdout); } while(0)
+
+/* Reinvent the wheel... */
+#define CHUNKSIZE 64
+#define HASH ((long)0xCAFECAFE)
+typedef struct {
+   long hash;
+   char *buffer;
+   long length;
+   long remaining;
+   int  printed;
+} bytestring_t;
+bytestring_t *bytestring_alloc(void) {
+    bytestring_t *ret;
+    /*TRACE0("bytestring_alloc()");*/
+    ret = S_ALLOC(bytestring_t);
+    ret->hash   = HASH;
+    ret->length = CHUNKSIZE;
+    ret->remaining = ret->length;
+    ret->buffer = S_ALLOC_N(char, ret->length + 1 );
+    ret->buffer[0] = 0;
+    ret->printed = 0;
+    return ret;
+}
+void bytestring_append(bytestring_t *str, char code,
+                       char *start, char *finish)
+{
+    long grow;
+    long length = 2;   /* CODE + LF */
+    char *curr;
+    assert(str && HASH == str->hash);
+    /*TRACE0("bytestring_append()");*/
+    if(start) {
+        if(!finish)
+            finish = start + strlen(start);
+        length += (finish-start);
+    }
+    if(length > str->remaining) {
+        grow = (length - str->remaining) + CHUNKSIZE;
+        str->remaining += grow;
+        str->length    += grow;
+        S_REALLOC_N( str->buffer, char, str->length + 1 );
+        assert(str->buffer);
+    }
+    curr = str->buffer + (str->length - str->remaining);
+    *curr = code;
+    curr += 1;
+    if(start)
+        while(start < finish)
+            *curr ++ = *start ++;
+    *curr = '\n';
+    curr += 1;
+    *curr = 0;
+    str->remaining = str->remaining - length;
+    assert( (str->buffer + str->length) - str->remaining );
+}
+void bytestring_extend(bytestring_t *str, bytestring_t *ext)
+{
+    char *from;
+    char *curr;
+    char *stop;
+    long grow;
+    long length;
+    assert(str && HASH == str->hash);
+    assert(ext && HASH == ext->hash);
+    if(ext->printed) {
+        assert(ext->buffer[0] ==YAMLBYTE_ANCHOR);
+        curr = ext->buffer;
+        while( '\n' != *curr)
+            curr++;
+        bytestring_append(str, YAMLBYTE_ALIAS, ext->buffer + 1, curr);
+    } else {
+        ext->printed = 1;
+        length  = (ext->length - ext->remaining);
+        if(length > str->remaining) {
+            grow = (length - str->remaining) + CHUNKSIZE;
+            str->remaining += grow;
+            str->length    += grow;
+            S_REALLOC_N( str->buffer, char, str->length + 1 );
+        }
+        curr = str->buffer + (str->length - str->remaining);
+        from = ext->buffer;
+        stop = ext->buffer + length;
+        while( from < stop )
+            *curr ++ = *from ++;
+        *curr = 0;
+        str->remaining = str->remaining - length;
+        assert( (str->buffer + str->length) - str->remaining );
+    }
+}
+
+/* convert SyckNode into yamlbyte_buffer_t objects */
+SYMID
+syck_yaml2byte_handler(p, n)
+    SyckParser *p;
+    SyckNode *n;
+{
+    SYMID oid;
+    long i;
+    char ch;
+    char nextcode;
+    char *start;
+    char *current;
+    char *finish;
+    bytestring_t *val = NULL;
+    bytestring_t *sav = NULL;
+    void *data;
+    /*TRACE0("syck_yaml2byte_handler()");*/
+    val = bytestring_alloc();
+    if(n->anchor) bytestring_append(val,YAMLBYTE_ANCHOR, n->anchor, NULL);
+    if ( n->type_id )
+    {
+        if ( p->taguri_expansion )
+        {
+            bytestring_append(val,YAMLBYTE_TRANSFER, n->type_id, NULL);
+        }
+        else
+        {
+            char *type_tag = S_ALLOC_N( char, strlen( n->type_id ) + 1 );
+            type_tag[0] = '\0';
+            strcat( type_tag, "!" );
+            strcat( type_tag, n->type_id );
+            bytestring_append( val, YAMLBYTE_TRANSFER, type_tag, NULL);
+	    S_FREE(type_tag);
+        }
+    }
+    switch (n->kind)
+    {
+        case syck_str_kind:
+            nextcode = YAMLBYTE_SCALAR;
+            start  = n->data.str->ptr;
+            finish = start + n->data.str->len - 1;
+            current = start;
+            /*TRACE2("SCALAR: %s %d", start, n->data.str->len); */
+            while(1) {
+                ch = *current;
+                if('\n' == ch || 0 == ch || current > finish) {
+                    if(current >= start) {
+                        bytestring_append(val, nextcode, start, current);
+                        nextcode = YAMLBYTE_CONTINUE;
+                    }
+                    start = current + 1;
+                    if(current > finish)
+                    {
+                        break;
+                    }
+                    else if('\n' == ch )
+                    {
+                        bytestring_append(val,YAMLBYTE_NEWLINE,NULL,NULL);
+                    }
+                    else if(0 == ch)
+                    {
+                        bytestring_append(val,YAMLBYTE_NULLCHAR,NULL,NULL);
+                    }
+                    else
+                    {
+                        assert("oops");
+                    }
+                }
+                current += 1;
+            }
+        break;
+        case syck_seq_kind:
+            bytestring_append(val,YAMLBYTE_SEQUENCE,NULL,NULL);
+            for ( i = 0; i < n->data.list->idx; i++ )
+            {
+                oid = syck_seq_read( n, i );
+                if (syck_lookup_sym( p, oid, &data )) sav = data;
+                bytestring_extend(val, sav);
+            }
+            bytestring_append(val,YAMLBYTE_END_BRANCH,NULL,NULL);
+        break;
+        case syck_map_kind:
+            bytestring_append(val,YAMLBYTE_MAPPING,NULL,NULL);
+            for ( i = 0; i < n->data.pairs->idx; i++ )
+            {
+                oid = syck_map_read( n, map_key, i );
+                if (syck_lookup_sym( p, oid, &data )) sav = data;
+                bytestring_extend(val, sav);
+                oid = syck_map_read( n, map_value, i );
+                if (syck_lookup_sym( p, oid, &data )) sav = data;
+                bytestring_extend(val, sav);
+            }
+            bytestring_append(val,YAMLBYTE_END_BRANCH,NULL,NULL);
+        break;
+    }
+    oid = syck_add_sym( p, (char *) val );
+    /*TRACE1("Saving: %s", val->buffer );*/
+    return oid;
+}
+
+char *
+syck_yaml2byte(char *yamlstr)
+{
+    SYMID oid;
+    char *ret;
+    bytestring_t *sav;
+    void *data;
+
+    SyckParser *parser = syck_new_parser();
+    syck_parser_str_auto( parser, yamlstr, NULL );
+    syck_parser_handler( parser, syck_yaml2byte_handler );
+    syck_parser_error_handler( parser, NULL );
+    syck_parser_implicit_typing( parser, 1 );
+    syck_parser_taguri_expansion( parser, 1 );
+    oid = syck_parse( parser );
+
+    if ( syck_lookup_sym( parser, oid, &data ) ) {
+	sav = data;
+        ret = S_ALLOC_N( char, strlen( sav->buffer ) + 3 );
+        ret[0] = '\0';
+        strcat( ret, "D\n" );
+        strcat( ret, sav->buffer );
+    }
+    else
+    {
+        ret = NULL;
+    }
+
+    syck_free_parser( parser );
+    return ret;
+}
+
+#ifdef TEST_YBEXT
+#include <stdio.h>
+int main() {
+   char *yaml = "test: 1\nand: \"with new\\nline\\n\"\nalso: &3 three\nmore: *3";
+   printf("--- # YAML \n");
+   printf(yaml);
+   printf("\n...\n");
+   printf(syck_yaml2byte(yaml));
+   return 0;
+}
+#endif
+

data/ext/syck/yamlbyte.h

@@ -0,0 +1,171 @@
+/*  yamlbyte.h
+ *
+ *  The YAML bytecode "C" interface header file.   See the YAML bytecode
+ *  reference for bytecode sequence rules and for the meaning of each
+ *  bytecode.
+ */
+
+#ifndef YAMLBYTE_H
+#define YAMLBYTE_H
+#include <stddef.h>
+
+/* define what a character is */
+typedef unsigned char yamlbyte_utf8_t;
+typedef unsigned short yamlbyte_utf16_t;
+#ifdef YAMLBYTE_UTF8
+  #ifdef YAMLBYTE_UTF16
+    #error Must only define YAMLBYTE_UTF8 or YAMLBYTE_UTF16
+  #endif
+  typedef yamlbyte_utf8_t yamlbyte_char_t;
+#else
+  #ifdef YAMLBYTE_UTF16
+    typedef yamlbyte_utf16_t yamlbyte_char_t;
+  #else
+    #error Must define YAMLBYTE_UTF8 or YAMLBYTE_UTF16
+  #endif
+#endif
+
+/* specify list of bytecodes */
+#define YAMLBYTE_FINISH          ((yamlbyte_char_t) 0)
+#define YAMLBYTE_DOCUMENT        ((yamlbyte_char_t)'D')
+#define YAMLBYTE_DIRECTIVE       ((yamlbyte_char_t)'V')
+#define YAMLBYTE_PAUSE           ((yamlbyte_char_t)'P')
+#define YAMLBYTE_MAPPING         ((yamlbyte_char_t)'M')
+#define YAMLBYTE_SEQUENCE        ((yamlbyte_char_t)'Q')
+#define YAMLBYTE_END_BRANCH      ((yamlbyte_char_t)'E')
+#define YAMLBYTE_SCALAR          ((yamlbyte_char_t)'S')
+#define YAMLBYTE_CONTINUE        ((yamlbyte_char_t)'C')
+#define YAMLBYTE_NEWLINE         ((yamlbyte_char_t)'N')
+#define YAMLBYTE_NULLCHAR        ((yamlbyte_char_t)'Z')
+#define YAMLBYTE_ANCHOR          ((yamlbyte_char_t)'A')
+#define YAMLBYTE_ALIAS           ((yamlbyte_char_t)'R')
+#define YAMLBYTE_TRANSFER        ((yamlbyte_char_t)'T')
+/* formatting bytecodes */
+#define YAMLBYTE_COMMENT         ((yamlbyte_char_t)'c')
+#define YAMLBYTE_INDENT          ((yamlbyte_char_t)'i')
+#define YAMLBYTE_STYLE           ((yamlbyte_char_t)'s')
+/* other bytecodes */
+#define YAMLBYTE_LINE_NUMBER     ((yamlbyte_char_t)'#')
+#define YAMLBYTE_WHOLE_SCALAR    ((yamlbyte_char_t)'<')
+#define YAMLBYTE_NOTICE          ((yamlbyte_char_t)'!')
+#define YAMLBYTE_SPAN            ((yamlbyte_char_t)')')
+#define YAMLBYTE_ALLOC           ((yamlbyte_char_t)'@')
+
+/* second level style bytecodes, ie "s>" */
+#define YAMLBYTE_FLOW            ((yamlbyte_char_t)'>')
+#define YAMLBYTE_LITERAL         ((yamlbyte_char_t)'|')
+#define YAMLBYTE_BLOCK           ((yamlbyte_char_t)'b')
+#define YAMLBYTE_PLAIN           ((yamlbyte_char_t)'p')
+#define YAMLBYTE_INLINE_MAPPING  ((yamlbyte_char_t)'{')
+#define YAMLBYTE_INLINE_SEQUENCE ((yamlbyte_char_t)'[')
+#define YAMLBYTE_SINGLE_QUOTED   ((yamlbyte_char_t)39)
+#define YAMLBYTE_DOUBLE_QUOTED   ((yamlbyte_char_t)'"')
+
+/*
+ * The "C" API has two variants, one based on instructions,
+ * with events delivered via pointers; and the other one
+ * is character based where one or more instructions are
+ * serialized into a buffer.
+ *
+ * Note: In the instruction based API, WHOLE_SCALAR does
+ *       not have the '<here' marshalling stuff.
+ */
+
+typedef void * yamlbyte_consumer_t;
+typedef void * yamlbyte_producer_t;
+
+/* push and pull APIs need a way to communicate results */
+typedef enum {
+    YAMLBYTE_OK          = 0,     /* proceed                        */
+    YAMLBYTE_E_MEMORY    = 'M',   /* could not allocate memory      */
+    YAMLBYTE_E_READ      = 'R',   /* input stream read error        */
+    YAMLBYTE_E_WRITE     = 'W',   /* output stream write error      */
+    YAMLBYTE_E_OTHER     = '?',   /* some other error condition     */
+    YAMLBYTE_E_PARSE     = 'P',   /* parse error, check bytecodes   */
+    YAMLBYTE_MAX
+} yamlbyte_result_t;
+
+typedef const yamlbyte_char_t *yamlbyte_buff_t;
+
+/*
+ *  The "Instruction" API
+ */
+
+typedef struct yaml_instruction {
+    yamlbyte_char_t bytecode;
+    yamlbyte_buff_t start;
+    yamlbyte_buff_t finish;  /* open range, *finish is _not_ part */
+} *yamlbyte_inst_t;
+
+/* producer pushes the instruction with one bytecode event to the
+ * consumer; if the consumer's result is not YAMLBYTE_OK, then
+ * the producer should stop */
+typedef
+  yamlbyte_result_t
+   (*yamlbyte_push_t)(
+     yamlbyte_consumer_t self,
+     yamlbyte_inst_t  inst
+   );
+
+/* consumer pulls a bytecode instruction from the producer; in this
+ * case the instruction (and is buffer) are owned by the producer and
+ * will remain valid till the pull function is called once again;
+ * if the instruction is NULL, then there are no more results; and
+ * it is important to call the pull function till it returns NULL so
+ * that the producer can clean up its memory allocations */
+typedef
+   yamlbyte_result_t
+    (*yamlbyte_pull_t)(
+      yamlbyte_producer_t self,
+      yamlbyte_inst_t *inst   /* to be filled in by the producer */
+    );
+
+/*
+ *  Buffer based API
+ */
+
+/* producer pushes a null terminated buffer filled with one or more
+ * bytecode events to the consumer; if the consumer's result is not
+ * YAMLBYTE_OK, then the producer should stop */
+typedef
+  yamlbyte_result_t
+   (*yamlbyte_pushbuff_t)(
+     yamlbyte_consumer_t self,
+     yamlbyte_buff_t  buff
+   );
+
+/* consumer pulls bytecode events from the producer; in this case
+ * the buffer is owned by the producer, and will remain valid till
+ * the pull function is called once again; if the buffer pointer
+ * is set to NULL, then there are no more results; it is important
+ * to call the pull function till it returns NULL so that the
+ * producer can clean up its memory allocations */
+typedef
+   yamlbyte_result_t
+    (*yamlbyte_pullbuff_t)(
+      yamlbyte_producer_t self,
+      yamlbyte_buff_t *buff   /* to be filled in by the producer */
+    );
+
+/* convert a pull interface to a push interface; the reverse process
+ * requires threads and thus is language dependent */
+#define YAMLBYTE_PULL2PUSH(pull,producer,push,consumer,result)       \
+    do {                                                         \
+        yamlbyte_pullbuff_t _pull = (pull);                              \
+        yamlbyte_pushbuff_t _push = (push);                              \
+        yamlbyte_result_t _result = YAMLBYTE_OK;                         \
+        yamlbyte_producer_t _producer = (producer);                  \
+        yamlbyte_consumer_t _consumer = (consumer);                  \
+        while(1) {                                               \
+            yamlbyte_buff_t buff = NULL;                           \
+            _result = _pull(_producer,&buff);                    \
+            if(YAMLBYTE_OK != result || NULL == buff)                \
+                break;                                           \
+            _result = _push(_consumer,buff);                     \
+            if(YAMLBYTE_OK != result)                                \
+                break;                                           \
+        }                                                        \
+        (result) = _result;                                      \
+    } while(0)
+
+#endif

data/lib/syck.rb

@@ -0,0 +1,448 @@
+# -*- mode: ruby; ruby-indent-level: 4; tab-width: 4 -*- vim: sw=4 ts=4
+# $Id$
+#
+# = yaml.rb: top-level module with methods for loading and parsing YAML documents
+#
+# Author:: why the lucky stiff
+#
+
+require 'yaml/syck'
+require File.expand_path('../yaml/engine_manager', __FILE__)
+
+# == 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 http://yaml.org/ for more information.  For a quick tutorial, please
+# visit YAML In Five Minutes (http://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 (http://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
+#
+module Syck
+
+    DefaultResolver.use_types_at( @@tagged_classes )
+
+    # Returns a new default parser
+    def self.parser; Parser.new.set_resolver( self.resolver ); end
+
+    # Returns a new generic parser
+    def self.generic_parser
+        warn "#{caller[0]}: YAML.generic_parser is deprecated, switch to psych" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        Parser.new.set_resolver( GenericResolver )
+    end
+
+    # Returns the default resolver
+    def self.resolver
+        warn "#{caller[0]}: YAML.resolver is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        DefaultResolver
+    end
+
+    # Returns a new default emitter
+    def self.emitter
+        warn "#{caller[0]}: YAML.emitter is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        Emitter.new.set_resolver( self.resolver )
+    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"
+    #
+    def self.dump( obj, io = nil )
+        obj.to_yaml( io || io2 = StringIO.new )
+        io || ( io2.rewind; io2.read )
+    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
+    #
+    def self.load( io )
+        parser.load( io )
+    end
+
+    #
+    # Load a document from the file located at _filepath_.
+    #
+    #   YAML.load_file( 'animals.yaml' )
+    #      #=> ['badger', 'elephant', 'tiger']
+    #
+    def self.load_file( filepath )
+        File.open( filepath ) do |f|
+            load( f )
+        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>
+    #
+    def self.parse( io )
+        generic_parser.load( io )
+    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">]>
+    #
+    def self.parse_file( filepath )
+        File.open( filepath ) do |f|
+            parse( f )
+        end
+    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
+    #
+    def self.each_document( io, &block )
+        warn "#{caller[0]}: YAML.each_document is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        parser.load_documents( io, &block )
+    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
+    #
+    def self.load_documents( io, &doc_proc )
+        parser.load_documents( io, &doc_proc )
+    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
+    #
+    def self.each_node( io, &doc_proc )
+        warn "#{caller[0]}: YAML.each_node is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        generic_parser.load_documents( io, &doc_proc )
+    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
+    #
+    def self.parse_documents( io, &doc_proc )
+        warn "#{caller[0]}: YAML.parse_documents is deprecated, use load_stream" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        self.each_node( io, &doc_proc )
+    end
+
+    #
+    # Loads all documents from the current _io_ stream,
+    # returning a +YAML::Stream+ object containing all
+    # loaded documents.
+    #
+    def self.load_stream( io )
+        d = nil
+        parser.load_documents( io ) do |doc|
+            d = Stream.new if not d
+            d.add( doc )
+        end
+        return d
+    end
+
+    #
+    # Returns a YAML stream containing each of the items in +objs+,
+    # each having their own document.
+    #
+    #   YAML.dump_stream( 0, [], {} )
+    #     #=> --- 0
+    #         --- []
+    #         --- {}
+    #
+    def self.dump_stream( *objs )
+        d = Stream.new
+        objs.each do |doc|
+            d.add( doc )
+        end
+        d.emit
+    end
+
+    #
+    # Add a global handler for a YAML domain type.
+    #
+    def self.add_domain_type( domain, type_tag, &transfer_proc )
+        resolver.add_type( "tag:#{ domain }:#{ type_tag }", transfer_proc )
+    end
+
+    #
+    # Add a transfer method for a builtin type
+    #
+    def self.add_builtin_type( type_tag, &transfer_proc )
+        resolver.add_type( "tag:yaml.org,2002:#{ type_tag }", transfer_proc )
+    end
+
+    #
+    # Add a transfer method for a builtin type
+    #
+    def self.add_ruby_type( type_tag, &transfer_proc )
+        warn "#{caller[0]}: YAML.add_ruby_type is deprecated, use add_domain_type" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        resolver.add_type( "tag:ruby.yaml.org,2002:#{ type_tag }", transfer_proc )
+    end
+
+    #
+    # Add a private document type
+    #
+    def self.add_private_type( type_re, &transfer_proc )
+        warn "#{caller[0]}: YAML.add_private_type is deprecated, use add_domain_type" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        resolver.add_type( "x-private:" + type_re, transfer_proc )
+    end
+
+    #
+    # Detect typing of a string
+    #
+    def self.detect_implicit( val )
+        warn "#{caller[0]}: YAML.detect_implicit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        resolver.detect_implicit( val )
+    end
+
+    #
+    # Convert a type_id to a taguri
+    #
+    def self.tagurize( val )
+        warn "#{caller[0]}: YAML.tagurize is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        resolver.tagurize( val )
+    end
+
+    #
+    # Apply a transfer method to a Ruby object
+    #
+    def self.transfer( type_id, obj )
+        warn "#{caller[0]}: YAML.transfer is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        resolver.transfer( tagurize( type_id ), obj )
+    end
+
+    #
+    # Apply any implicit a node may qualify for
+    #
+    def self.try_implicit( obj )
+        warn "#{caller[0]}: YAML.try_implicit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        transfer( detect_implicit( obj ), obj )
+    end
+
+    #
+    # Method to extract colon-seperated type and class, returning
+    # the type and the constant of the class
+    #
+    def self.read_type_class( type, obj_class )
+        warn "#{caller[0]}: YAML.read_type_class is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        type, tclass = type.split( ':', 4 ).last(2)
+        tclass.split( "::" ).each { |c| obj_class = obj_class.const_get( c ) } if tclass
+        return [ type, obj_class ]
+    end
+
+    #
+    # Allocate blank object
+    #
+    def self.object_maker( obj_class, val )
+        warn "#{caller[0]}: YAML.object_maker is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        if Hash === val
+            o = obj_class.allocate
+            val.each_pair { |k,v|
+                o.instance_variable_set("@#{k}", v)
+            }
+            o
+        else
+            raise Error, "Invalid object explicitly tagged !ruby/Object: " + val.inspect
+        end
+    end
+
+    #
+    # Allocate an Emitter if needed
+    #
+    def self.quick_emit( oid, opts = {}, &e )
+        warn "#{caller[0]}: YAML.quick_emit is deprecated" if $VERBOSE && !caller[0].start_with?(File.dirname(__FILE__))
+        out =
+            if opts.is_a? Emitter
+                opts
+            else
+                emitter.reset( opts )
+            end
+        out.emit( oid, &e )
+    end
+
+end
+
+module Kernel
+    #
+    # ryan:: You know how Kernel.p is a really convenient way to dump ruby
+    #        structures?  The only downside is that it's not as legible as
+    #        YAML.
+    #
+    # _why:: (listening)
+    #
+    # ryan:: I know you don't want to urinate all over your users' namespaces.
+    #        But, on the other hand, convenience of dumping for debugging is,
+    #        IMO, a big YAML use case.
+    #
+    # _why:: Go nuts!  Have a pony parade!
+    #
+    # ryan:: Either way, I certainly will have a pony parade.
+    #
+
+    # Prints any supplied _objects_ out in YAML.  Intended as
+    # a variation on +Kernel::p+.
+    #
+    #   S = Struct.new(:name, :state)
+    #   s = S['dave', 'TX']
+    #   y s
+    #
+    # _produces:_
+    #
+    #   --- !ruby/struct:S
+    #   name: dave
+    #   state: TX
+    #
+    def y( object, *objects )
+        objects.unshift object
+        puts( if objects.length == 1
+                  Syck.dump( *objects )
+              else
+                  Syck.dump_stream( *objects )
+              end )
+    end
+    private :y
+end
+
+