Permalink
Browse files

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

  [Github Fixes #134]
  • Loading branch information...
1 parent 0b72234 commit 03659ce6d3e7db458c38f1c0973cf1bdf0824acf @zzak zzak committed Feb 28, 2013
Showing with 152 additions and 26 deletions.
  1. +5 −0 CHANGELOG.rdoc
  2. +147 −26 lib/psych.rb
View
5 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
View
173 lib/psych.rb
@@ -43,55 +43,176 @@
# 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
# 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
+# ==== 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
# AST knows how to emit itself as a YAML document. See Psych::Nodes,
# 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

0 comments on commit 03659ce

Please sign in to comment.