diff options
author | why <why@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-05-25 15:04:16 +0000 |
---|---|---|
committer | why <why@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-05-25 15:04:16 +0000 |
commit | 439975d8964bf1dd9a89b97a0f3a868c477eb630 (patch) | |
tree | 9b3ec443dca118b72e7aae59d722e53ca04685ae /lib/yaml.rb | |
parent | adc10cab5181133a9f54f1b273fd3449b1dc2709 (diff) |
* 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
Diffstat (limited to 'lib/yaml.rb')
-rw-r--r-- | lib/yaml.rb | 199 |
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 |