* ext/psych/lib/psych.rb: rdoc for Psych overview by Adam Stankiewicz

[Github tenderlove/psych#134]


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

ChangeLog

@@ -1,3 +1,8 @@
+Fri Mar 1 03:25:00 2013  Zachary Scott  <zachary@zacharyscott.net>
+
+	* 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@atdot.net>
 
 	* compile.c (iseq_compile_each): remove redundant trace(line)

ext/psych/lib/psych.rb

@@ -43,27 +43,6 @@ require 'psych/handlers/document_stream'
 # 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
-#
-# 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.
-#
-# === Mid level 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
-# be examined and manipulated freely.  Please see Psych::parse_stream,
-# Psych::Nodes, and Psych::Nodes::Node for more information on dealing with
-# YAML syntax trees.
-#
-# === High level 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
-#
 # == YAML Emitting
 #
 # Psych provides a range of interfaces ranging from low to high level for
@@ -72,14 +51,98 @@ require 'psych/handlers/document_stream'
 # a YAML AST, and the highest level is converting a Ruby object straight to
 # a YAML document.
 #
-# === Low level emitting
+# == High-level API
 #
-# 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.
+# === Parsing
 #
-# === Mid level emitting
+# 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
+#
+#   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
+# be examined and manipulated freely.  Please see Psych::parse_stream,
+# Psych::Nodes, and Psych::Nodes::Node for more information on dealing with
+# YAML syntax trees.
+#
+# ==== Reading from a string
+#
+#   # Returns Psych::Nodes::Stream
+#   Psych.parse_stream("---\n - a\n - b")
+#
+#   # Returns Psych::Nodes::Document
+#   Psych.parse("---\n - a\n - b")
+#
+# ==== Reading from a file
+#
+#   # Returns Psych::Nodes::Stream
+#   Psych.parse_stream(File.read('database.yml'))
+#
+#   # Returns Psych::Nodes::Document
+#   Psych.parse_file('database.yml')
+#
+# ==== Exception handling
+#
+#   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'
 # 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