summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog12
-rw-r--r--ext/syck/syck.c1
-rw-r--r--ext/syck/token.c2
-rw-r--r--lib/yaml.rb199
4 files changed, 190 insertions, 24 deletions
diff --git a/ChangeLog b/ChangeLog
index 124cc39..6185821 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+Wed May 26 00:00:00 2004 why the lucky stiff <why@ruby-lang.org>
+
+ * 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.
+
Mon May 24 10:46:26 2004 Kazuhiro NISHIYAMA <zn@mbf.nifty.com>
* lib/rdoc/generators/template/html/html.rb: SYSTEM identifiers
diff --git a/ext/syck/syck.c b/ext/syck/syck.c
index a4a3bd0..5a15ab4 100644
--- a/ext/syck/syck.c
+++ b/ext/syck/syck.c
@@ -159,6 +159,7 @@ syck_new_parser()
{
SyckParser *p;
p = S_ALLOC( SyckParser );
+ S_MEMZERO( p, SyckParser, 1 );
p->lvl_capa = ALLOC_CT;
p->levels = S_ALLOC_N( SyckLevel, p->lvl_capa );
p->input_type = syck_yaml_utf8;
diff --git a/ext/syck/token.c b/ext/syck/token.c
index ac9986f..ff192f2 100644
--- a/ext/syck/token.c
+++ b/ext/syck/token.c
@@ -2297,7 +2297,7 @@ yy215:
#line 938
{ if ( YYTOKEN == YYLINEPTR )
{
- if ( blockType == BLOCK_FOLD )
+ if ( blockType == BLOCK_FOLD && qidx > 0 )
{
qidx -= 1;
}
diff --git a/lib/yaml.rb b/lib/yaml.rb
index 3e1b56b..023c4ab 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