diff options
| -rw-r--r-- | lib/psych.rb | 7 | ||||
| -rw-r--r-- | lib/psych/parser.rb | 44 |
2 files changed, 44 insertions, 7 deletions
diff --git a/lib/psych.rb b/lib/psych.rb index 848a71d..02925be 100644 --- a/lib/psych.rb +++ b/lib/psych.rb @@ -19,13 +19,16 @@ require 'psych/set' require 'psych/psych' ### -# Psych is a YAML parser and emitter. +# Psych is a YAML parser and emitter. Psych leverages +# libyaml[http://libyaml.org] for it's YAML parsing and emitting capabilities. +# In addition to wrapping libyaml, Psych also knows how to serialize and +# de-serialize most Ruby objects to and from the YAML format. # # == YAML Parsing # # Psych provides a range of interfaces for parsing a YAML document ranging from # low level to high level, depending on your parsing needs. At the lowest -# level, is an event based parser. Mid-level is access to the raw YAML AST, +# 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 diff --git a/lib/psych/parser.rb b/lib/psych/parser.rb index a59c435..caa544c 100644 --- a/lib/psych/parser.rb +++ b/lib/psych/parser.rb @@ -1,19 +1,53 @@ module Psych ### - # YAML parser class. + # YAML event parser class. This class parses a YAML document and calls + # events on the handler that is passed to the constructor. The events can + # be used for things such as constructing a YAML AST or deserializing YAML + # documents. It can even be fed back to Psych::Emitter to emit the same + # document that was parsed. # - # Example: + # See Psych::Handler for documentation on the events that Psych::Parser emits. # - # parser = Psych::Parser.new - # parser.parse(some_yaml) + # Here is an example that prints out ever scalar found in a YAML document: + # + # # Handler for detecting scalar values + # class ScalarHandler < Psych::Handler + # def scalar value, anchor, tag, plain, quoted, style + # puts value + # end + # end + # + # parser = Psych::Parser.new(ScalarHandler.new) + # parser.parse(yaml_document) + # + # Here is an example that feeds the parser back in to Psych::Emitter. The + # YAML document is read from STDIN and written back out to STDERR: + # + # parser = Psych::Parser.new(Psych::Emitter.new($stderr)) + # parser.parse($stdin) + # + # Psych uses Psych::Parser in combination with Psych::TreeBuilder to + # construct an AST of the parsed YAML document. + class Parser + # The handler on which events will be called attr_accessor :handler + ### + # Creates a new Psych::Parser instance with +handler+. YAML events will + # be called on +handler+. See Psych::Parser for more details. + def initialize handler = Handler.new @handler = handler end - def parse string + ### + # Parse the YAML document contained in +yaml+. Events will be called on + # the handler set on the parser instance. + # + # See Psych::Parser and Psych::Parser#handler + + def parse yaml parse_string string end end |