* ext/syck/syck.c (syck_new_parser): clear parser on init.

  thanks, ts. [ruby-core:02931]

* ext/syck/token.c (sycklex_yaml_utf8): buffer underflow.
  thanks, ts. [ruby-core:02929]

* lib/yaml/baseemitter.rb (indent_text): simpler flow block code.

* lib/yaml.rb: added rdoc to beginning of lib.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@6404 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 176 insertions, 23 deletions

diff --git a/lib/yaml.rb b/lib/yaml.rb
index 3e1b56b7ad..023c4ab84b 100644
--- a/lib/yaml.rb
+++ b/lib/yaml.rb
@@ -1,22 +1,103 @@
 # -*- mode: ruby; ruby-indent-level: 4; tab-width: 4 -*- vim: sw=4 ts=4
 # $Id$
 #
-#   YAML.rb
+# = yaml.rb: top-level module with methods for loading and parsing YAML documents
 #
-#   Loads the parser/loader and emitter/writer.
+# Author:: why the lucky stiff
+# 
+
+require 'yaml/syck'
+require 'yaml/loader'
+require 'yaml/stream'
+
+# == 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 loader, use +add_domain_type+.
+#
+#     YAML::add_domain_type( "your-site.com,2004", "widget" ) do |type, val|
+#         Widget.new( val )
+#     end
 #
 module YAML
 
-        require 'yaml/syck'
-        @@parser = YAML::Syck::Parser
-        @@loader = YAML::Syck::DefaultLoader
-        @@emitter = YAML::Syck::Emitter
-    require 'yaml/loader'
-    require 'yaml/stream'
+    @@parser = YAML::Syck::Parser
+    @@loader = YAML::Syck::DefaultLoader
+    @@emitter = YAML::Syck::Emitter
 
 	#
-	# Load a single document from the current stream
+	# 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 YAML.dump( obj, io = nil )
         io ||= ""
         io << obj.to_yaml
@@ -24,49 +105,115 @@ module YAML
 	end
 
 	#
-	# Load a single document from the current stream
+	# Load the first 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 YAML.load( io )
 		yp = @@parser.new.load( io )
 	end
 
 	#
-	# Parse a single document from the current stream
+	# 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>
+    #
 	def YAML.parse( io )
 		yp = @@parser.new( :Model => :Generic ).load( io )
 	end
 
 	#
-	# Load all documents from the current stream
+	# 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 YAML.each_document( io, &doc_proc )
-		yp = @@parser.new.load_documents( io, &doc_proc )
+	def YAML.each_document( io, &block )
+		yp = @@parser.new.load_documents( io, &block )
     end
 
 	#
-	# Identical to each_document
+	# 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 YAML.load_documents( io, &doc_proc )
 		YAML.each_document( io, &doc_proc )
     end
 
 	#
-	# Parse all documents from the current stream
+	# 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 YAML.each_node( io, &doc_proc )
 		yp = @@parser.new( :Model => :Generic ).load_documents( io, &doc_proc )
     end
 
 	#
-	# Parse all documents from the current stream
+	# 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 YAML.parse_documents( io, &doc_proc )
 		YAML.each_node( io, &doc_proc )
     end
 
 	#
-	# Load all documents from the current stream
+	# Loads all documents from the current _io_ stream, 
+    # returning a +YAML::Stream+ object containing all
+    # loaded documents.
 	#
 	def YAML.load_stream( io )
 		yp = @@parser.new
@@ -79,7 +226,13 @@ module YAML
 	end
 
 	#
-    # Dump documents to a stream
+    # Returns a YAML stream containing each of the items in +objs+,
+    # each having their own document.
+    #
+    #   YAML.dump_stream( 0, [], {} )
+    #     #=> --- 0
+    #         --- []
+    #         --- {}
     #
 	def YAML.dump_stream( *objs )
 		d = YAML::Stream.new
@@ -90,7 +243,7 @@ module YAML
 	end
 
 	#
-	# Add a transfer method to a domain
+	# Add a global handler for a YAML domain type.
 	#
 	def YAML.add_domain_type( domain, type_re, &transfer_proc )
         @@loader.add_domain_type( domain, type_re, &transfer_proc )
@@ -154,9 +307,9 @@ module YAML
     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)
-                }
+            val.each_pair { |k,v|
+                o.instance_variable_set("@#{k}", v)
+            }
             o
         else
             raise YAML::Error, "Invalid object explicitly tagged !ruby/Object: " + val.inspect