1module Psych
2  ###
3  # YAML event parser class.  This class parses a YAML document and calls
4  # events on the handler that is passed to the constructor.  The events can
5  # be used for things such as constructing a YAML AST or deserializing YAML
6  # documents.  It can even be fed back to Psych::Emitter to emit the same
7  # document that was parsed.
8  #
9  # See Psych::Handler for documentation on the events that Psych::Parser emits.
10  #
11  # Here is an example that prints out ever scalar found in a YAML document:
12  #
13  #   # Handler for detecting scalar values
14  #   class ScalarHandler < Psych::Handler
15  #     def scalar value, anchor, tag, plain, quoted, style
16  #       puts value
17  #     end
18  #   end
19  #
20  #   parser = Psych::Parser.new(ScalarHandler.new)
21  #   parser.parse(yaml_document)
22  #
23  # Here is an example that feeds the parser back in to Psych::Emitter.  The
24  # YAML document is read from STDIN and written back out to STDERR:
25  #
26  #   parser = Psych::Parser.new(Psych::Emitter.new($stderr))
27  #   parser.parse($stdin)
28  #
29  # Psych uses Psych::Parser in combination with Psych::TreeBuilder to
30  # construct an AST of the parsed YAML document.
31
32  class Parser
33    class Mark < Struct.new(:index, :line, :column)
34    end
35
36    # The handler on which events will be called
37    attr_accessor :handler
38
39    # Set the encoding for this parser to +encoding+
40    attr_writer :external_encoding
41
42    ###
43    # Creates a new Psych::Parser instance with +handler+.  YAML events will
44    # be called on +handler+.  See Psych::Parser for more details.
45
46    def initialize handler = Handler.new
47      @handler = handler
48      @external_encoding = ANY
49    end
50  end
51end
52