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

  [Github Fixes #134]

2 files changed, 152 insertions, 26 deletions

diff --git a/CHANGELOG.rdoc b/CHANGELOG.rdoc
index 33a8ce4..cb66a48 100644
--- a/CHANGELOG.rdoc
+++ b/CHANGELOG.rdoc
@@ -1,3 +1,8 @@
+Fri Mar  1 03:22:00 2013  Zachary Scott <zachary@zacharyscott.net>
+
+        * lib/psych.rb: rdoc for Psych overview by Adam Stankiewicz
+          [Github Fixes #134]
+
 Sun Feb  17 01:13:00 2013  Zachary Scott <zachary@zacharyscott.net>
 
         * lib/psych/y.rb: Document Kernel#y by Adam Stankiewicz
diff --git a/lib/psych.rb b/lib/psych.rb
index e9571b7..1384345 100644
--- a/lib/psych.rb
+++ b/lib/psych.rb
@@ -43,14 +43,72 @@ 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
+# == 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'
 # 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'
 # 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