ruby-changes:27488
From: zzak <ko1@a...>
Date: Fri, 1 Mar 2013 03:27:10 +0900 (JST)
Subject: [ruby-changes:27488] zzak:r39540 (trunk): * ext/psych/lib/psych.rb: rdoc for Psych overview by Adam Stankiewicz
zzak 2013-03-01 03:27:00 +0900 (Fri, 01 Mar 2013) New Revision: 39540 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=39540 Log: * ext/psych/lib/psych.rb: rdoc for Psych overview by Adam Stankiewicz [Github tenderlove/psych#134] Modified files: trunk/ChangeLog trunk/ext/psych/lib/psych.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 39539) +++ ChangeLog (revision 39540) @@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Fri Mar 1 03:25:00 2013 Zachary Scott <zachary@z...> + + * ext/psych/lib/psych.rb: rdoc for Psych overview by Adam Stankiewicz + [Github tenderlove/psych#134] + Thu Feb 28 22:57:48 2013 Koichi Sasada <ko1@a...> * compile.c (iseq_compile_each): remove redundant trace(line) Index: ext/psych/lib/psych.rb =================================================================== --- ext/psych/lib/psych.rb (revision 39539) +++ ext/psych/lib/psych.rb (revision 39540) @@ -43,14 +43,72 @@ require 'psych/handlers/document_stream' https://github.com/ruby/ruby/blob/trunk/ext/psych/lib/psych.rb#L43 # level, is an event based parser. Mid level is access to the raw YAML AST, # and at the highest level is the ability to unmarshal YAML to ruby objects. # -# === Low level parsing +# == YAML Emitting # -# The lowest level parser should be used when the YAML input is already known, -# and the developer does not want to pay the price of building an AST or -# automatic detection and conversion to ruby objects. See Psych::Parser for -# more information on using the event based parser. +# Psych provides a range of interfaces ranging from low to high level for +# producing YAML documents. Very similar to the YAML parsing interfaces, Psych +# provides at the lowest level, an event based system, mid-level is building +# a YAML AST, and the highest level is converting a Ruby object straight to +# a YAML document. +# +# == High-level API +# +# === Parsing +# +# The high level YAML parser provided by Psych simply takes YAML as input and +# returns a Ruby data structure. For information on using the high level parser +# see Psych.load +# +# ==== Reading from a string +# +# Psych.load("--- a") # => 'a' +# Psych.load("---\n - a\n - b") # => ['a', 'b'] +# +# ==== Reading from a file +# +# Psych.load_file("database.yml") +# +# ==== Exception handling # -# === Mid level parsing +# begin +# # The second argument chnages only the exception contents +# Psych.parse("--- `", "file.txt") +# rescue Psych::SyntaxError => ex +# ex.file # => 'file.txt' +# ex.message # => "(file.txt): found character that cannot start any token" +# end +# +# === Emitting +# +# The high level emitter has the easiest interface. Psych simply takes a Ruby +# data structure and converts it to a YAML document. See Psych.dump for more +# information on dumping a Ruby data structure. +# +# ==== Writing to a string +# +# # Dump an array, get back a YAML string +# Psych.dump(['a', 'b']) # => "---\n- a\n- b\n" +# +# # Dump an array to an IO object +# Psych.dump(['a', 'b'], StringIO.new) # => #<StringIO:0x000001009d0890> +# +# # Dump an array with indentation set +# Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n- - b\n" +# +# # Dump an array to an IO with indentation set +# Psych.dump(['a', ['b']], StringIO.new, :indentation => 3) +# +# ==== Writing to a file +# +# Currently there is no direct API for dumping Ruby structure to file: +# +# File.open('database.yml', 'w') do |file| +# file.write(Psych.dump(['a', 'b'])) +# end +# +# == Mid-level API +# +# === Parsing # # Psych provides access to an AST produced from parsing a YAML document. This # tree is built using the Psych::Parser and Psych::TreeBuilder. The AST can @@ -58,28 +116,33 @@ require 'psych/handlers/document_stream' https://github.com/ruby/ruby/blob/trunk/ext/psych/lib/psych.rb#L116 # Psych::Nodes, and Psych::Nodes::Node for more information on dealing with # YAML syntax trees. # -# === High level parsing +# ==== Reading from a string # -# The high level YAML parser provided by Psych simply takes YAML as input and -# returns a Ruby data structure. For information on using the high level parser -# see Psych.load +# # Returns Psych::Nodes::Stream +# Psych.parse_stream("---\n - a\n - b") # -# == YAML Emitting +# # Returns Psych::Nodes::Document +# Psych.parse("---\n - a\n - b") # -# Psych provides a range of interfaces ranging from low to high level for -# producing YAML documents. Very similar to the YAML parsing interfaces, Psych -# provides at the lowest level, an event based system, mid-level is building -# a YAML AST, and the highest level is converting a Ruby object straight to -# a YAML document. +# ==== Reading from a file # -# === Low level emitting +# # Returns Psych::Nodes::Stream +# Psych.parse_stream(File.read('database.yml')) # -# The lowest level emitter is an event based system. Events are sent to a -# Psych::Emitter object. That object knows how to convert the events to a YAML -# document. This interface should be used when document format is known in -# advance or speed is a concern. See Psych::Emitter for more information. +# # Returns Psych::Nodes::Document +# Psych.parse_file('database.yml') +# +# ==== Exception handling # -# === Mid level emitting +# begin +# # The second argument chnages only the exception contents +# Psych.parse("--- `", "file.txt") +# rescue Psych::SyntaxError => ex +# ex.file # => 'file.txt' +# ex.message # => "(file.txt): found character that cannot start any token" +# end +# +# === Emitting # # At the mid level is building an AST. This AST is exactly the same as the AST # used when parsing a YAML document. Users can build an AST by hand and the @@ -87,11 +150,69 @@ require 'psych/handlers/document_stream' https://github.com/ruby/ruby/blob/trunk/ext/psych/lib/psych.rb#L150 # Psych::Nodes::Node, and Psych::TreeBuilder for more information on building # a YAML AST. # -# === High level emitting +# ==== Writing to a string # -# The high level emitter has the easiest interface. Psych simply takes a Ruby -# data structure and converts it to a YAML document. See Psych.dump for more -# information on dumping a Ruby data structure. +# # We need Psych::Nodes::Stream (not Psych::Nodes::Document) +# stream = Psych.parse_stream("---\n - a\n - b") +# +# stream.to_yaml # => "---\n- a\n- b\n" +# +# ==== Writing to a file +# +# # We need Psych::Nodes::Stream (not Psych::Nodes::Document) +# stream = Psych.parse_stream(File.read('database.yml')) +# +# File.open('database.yml', 'w') do |file| +# file.write(stream.to_yaml) +# end +# +# == Low-level API +# +# === Parsing +# +# The lowest level parser should be used when the YAML input is already known, +# and the developer does not want to pay the price of building an AST or +# automatic detection and conversion to ruby objects. See Psych::Parser for +# more information on using the event based parser. +# +# ==== Reading to Psych::Nodes::Stream structure +# +# parser = Psych::Parser.new(TreeBuilder.new) # => #<Psych::Parser> +# parser = Psych.parser # it's an alias for the above +# +# parser.parse("---\n - a\n - b") # => #<Psych::Parser> +# parser.handler # => #<Psych::TreeBuilder> +# parser.handler.root # => #<Psych::Nodes::Stream> +# +# ==== Receiving an events stream +# +# parser = Psych::Parser.new(Psych::Handlers::Recorder.new) +# +# parser.parse("---\n - a\n - b") +# parser.events # => [list of [event, args] lists] +# # event is one of: Psych::Handler::EVENTS +# # args are the arguments passed to the event +# +# === Emitting +# +# The lowest level emitter is an event based system. Events are sent to a +# Psych::Emitter object. That object knows how to convert the events to a YAML +# document. This interface should be used when document format is known in +# advance or speed is a concern. See Psych::Emitter for more information. +# +# ==== Writing to a ruby structure +# +# Psych.parser.parse("--- a") # => #<Psych::Parser> +# +# parser.handler.first # => #<Psych::Nodes::Stream> +# parser.handler.first.to_ruby # => ["a"] +# +# parser.handler.root.first # => #<Psych::Nodes::Document> +# parser.handler.root.first.to_ruby # => "a" +# +# # You can instantiate an Emitter manually +# Psych::Visitors::ToRuby.new.accept(parser.handler.root.first) +# # => "a" module Psych # The version is Psych you're using -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/