summaryrefslogtreecommitdiff
path: root/ext/psych
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-02-28 18:27:00 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-02-28 18:27:00 +0000
commit9460a750e181f02f57bb8ce8b0a28f57404b2778 (patch)
tree646e33327bccdafbd4deaf3146689d7097ef724c /ext/psych
parent4cf0918e8e3d8b06d84c3cd3e875c82edb8b87e6 (diff)
* 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
Diffstat (limited to 'ext/psych')
-rw-r--r--ext/psych/lib/psych.rb173
1 files changed, 147 insertions, 26 deletions
diff --git a/ext/psych/lib/psych.rb b/ext/psych/lib/psych.rb
index e9571b7414..1384345da1 100644
--- a/ext/psych/lib/psych.rb
+++ b/ext/psych/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