Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 187 lines (175 sloc) 5.354 kB
1e1b03f @tenderlove moving handler
authored
1 module Psych
2 ###
95343e1 @tenderlove adding more documentation
authored
3 # Psych::Handler is an abstract base class that defines the events used
4 # when dealing with Psych::Parser. Clients who want to use Psych::Parser
5 # should implement a class that inherits from Psych::Handler and define
6 # events that they can handle.
7 #
8 # Psych::Handler defines all events that Psych::Parser can possibly send to
9 # event handlers.
10 #
11 # See Psych::Parser for more details
1e1b03f @tenderlove moving handler
authored
12 class Handler
13 ###
95343e1 @tenderlove adding more documentation
authored
14 # Called with +encoding+ when the YAML stream starts. This method is
15 # called once per stream. A stream may contain multiple documents.
16 #
17 # See the constants in Psych::Parser for the possible values of +encoding+.
1e1b03f @tenderlove moving handler
authored
18 def start_stream encoding
19 end
20
21 ###
22 # Called when the document starts with the declared +version+,
95343e1 @tenderlove adding more documentation
authored
23 # +tag_directives+, if the document is +implicit+.
24 #
25 # +version+ will be an array of integers indicating the YAML version being
26 # dealt with, +tag_directives+ is a list of tuples indicating the prefix
27 # and suffix of each tag, and +implicit+ is a boolean indicating whether
28 # the document is started implicitly.
29 #
30 # === Example
31 #
32 # Given the following YAML:
33 #
34 # %YAML 1.1
35 # %TAG ! tag:tenderlovemaking.com,2009:
36 # --- !squee
37 #
38 # The parameters for start_document must be this:
39 #
40 # version # => [1, 1]
41 # tag_directives # => [["!", "tag:tenderlovemaking.com,2009:"]]
42 # implicit # => false
9f5da8f @tenderlove documents can convert to ruby
authored
43 def start_document version, tag_directives, implicit
1e1b03f @tenderlove moving handler
authored
44 end
45
46 ###
95343e1 @tenderlove adding more documentation
authored
47 # Called with the document ends. +implicit+ is a boolean value indicating
48 # whether or not the document has an implicit ending.
49 #
50 # === Example
51 #
52 # Given the following YAML:
53 #
54 # ---
55 # hello world
56 #
57 # +implicit+ will be true. Given this YAML:
58 #
59 # ---
60 # hello world
61 # ...
62 #
63 # +implicit+ will be false.
64 def end_document implicit
1e1b03f @tenderlove moving handler
authored
65 end
66
67 ###
95343e1 @tenderlove adding more documentation
authored
68 # Called when an alias is found to +anchor+. +anchor+ will be the name
69 # of the anchor found.
70 #
71 # === Example
72 #
73 # Here we have an example of an array that references itself in YAML:
74 #
75 # --- &ponies
76 # - first element
77 # - *ponies
78 #
79 # &ponies is the achor, *ponies is the alias. In this case, alias is
80 # called with "ponies".
1e1b03f @tenderlove moving handler
authored
81 def alias anchor
82 end
83
84 ###
85 # Called when a scalar +value+ is found. The scalar may have an
86 # +anchor+, a +tag+, be implicitly +plain+ or implicitly +quoted+
ed1d041 @tenderlove scalar documentation
authored
87 #
88 # +value+ is the string value of the scalar
89 # +anchor+ is an associated anchor or nil
90 # +tag+ is an associated tag or nil
91 # +plain+ is a boolean value
92 # +quoted+ is a boolean value
93 # +style+ is an integer idicating the string style
94 #
9a6eb3f @tenderlove sequence documentation
authored
95 # See the constants in Psych::Nodes::Scalar for the possible values of
ed1d041 @tenderlove scalar documentation
authored
96 # +style+
97 #
98 # === Example
99 #
100 # Here is a YAML document that exercises most of the possible ways this
101 # method can be called:
102 #
103 # ---
104 # - !str "foo"
105 # - &anchor fun
106 # - many
107 # lines
108 # - |
109 # many
110 # newlines
111 #
112 # The above YAML document contains a list with four strings. Here are
113 # the parameters sent to this method in the same order:
114 #
115 # # value anchor tag plain quoted style
116 # ["foo", nil, "!str", false, false, 3 ]
117 # ["fun", "anchor", nil, true, false, 1 ]
118 # ["many lines", nil, nil, true, false, 1 ]
119 # ["many\nnewlines\n", nil, nil, false, true, 4 ]
120 #
f3fcb96 @tenderlove moving constants around, starting the to_ruby visitor
authored
121 def scalar value, anchor, tag, plain, quoted, style
1e1b03f @tenderlove moving handler
authored
122 end
123
124 ###
125 # Called when a sequence is started.
9a6eb3f @tenderlove sequence documentation
authored
126 #
127 # +anchor+ is the anchor associated with the sequence or nil.
128 # +tag+ is the tag associated with the sequence or nil.
129 # +implicit+ a boolean indicating whether or not the sequence was implcitly
130 # started.
131 # +style+ is an integer indicating the list style.
132 #
133 # See the constants in Psych::Nodes::Sequence for the possible values of
134 # +style+.
135 #
136 # === Example
137 #
138 # Here is a YAML document that exercises most of the possible ways this
139 # method can be called:
140 #
141 # ---
142 # - !!seq [
143 # a
144 # ]
145 # - &pewpew
146 # - b
147 #
148 # The above YAML document consists of three lists, an outer list that
149 # contains two inner lists. Here is a matrix of the parameters sent
150 # to represent these lists:
151 #
152 # # anchor tag implicit style
153 # [nil, nil, true, 1 ]
154 # [nil, "tag:yaml.org,2002:seq", false, 2 ]
155 # ["pewpew", nil, true, 1 ]
156
f3fcb96 @tenderlove moving constants around, starting the to_ruby visitor
authored
157 def start_sequence anchor, tag, implicit, style
1e1b03f @tenderlove moving handler
authored
158 end
159
160 ###
161 # Called when a sequence ends.
162 def end_sequence
163 end
164
165 ###
166 # Called when a map starts
f3fcb96 @tenderlove moving constants around, starting the to_ruby visitor
authored
167 def start_mapping anchor, tag, implicit, style
1e1b03f @tenderlove moving handler
authored
168 end
169
170 ###
171 # Called when a map ends
172 def end_mapping
173 end
174
175 ###
176 # Called when an empty event happens. (Which, as far as I can tell, is
177 # never).
178 def empty
179 end
180
181 ###
182 # Called when the YAML stream ends
183 def end_stream
184 end
185 end
186 end
Something went wrong with that request. Please try again.