1RPC::XML::Parser(3)   User Contributed Perl Documentation  RPC::XML::Parser(3)
2
3
4

NAME

6       RPC::XML::Parser - Interface for parsers created by
7       RPC::XML::ParserFactory
8

SYNOPSIS

10       This class is not instantiated directly; see RPC::XML::ParserFactory.
11

DESCRIPTION

13       The RPC::XML::Parser class encapsulates the interface for the parsing
14       process. It is an empty class that is used in conjuntion with the
15       RPC::XML::ParserFactory class.
16
17       All parser implementations that are intended to be returned by calls to
18       RPC::XML::ParserFactory::new() should declare this as their parent
19       class.
20

SUBROUTINES/METHODS

22       This class provides empty implementations for the following methods. A
23       parser implementation must provide definitions for both of these
24       methods. If the versions from this class are triggered they will throw
25       exceptions ("die").
26
27       The descriptions below define the interface that implementations must
28       adhere to.
29
30       new([ARGS])
31           Create a new instance of the class. Any extra data passed to the
32           constructor is taken as key/value pairs (not a hash reference) and
33           attached to the object.
34
35           The following parameters are currently recognized:
36
37           base64_to_fh
38                   If passed with a true value, this tells the parser that
39                   incoming Base64 data is to be spooled to a filehandle
40                   opened onto an anonymous temporary file. The file itself is
41                   unlinked after opening, though the resulting
42                   RPC::XML::base64 object can use its "to_file" method to
43                   save the data to a specific file at a later point. No
44                   checks on size are made; if this option is set, all Base64
45                   data goes to filehandles.
46
47           base64_temp_dir
48                   If this argument is passed, the value is taken as the
49                   directory under which the temporary files are created. This
50                   is so that the application is not locked in to the list of
51                   directories that File::Spec defaults to with its "tmpdir"
52                   method. If this is not passed, the previously-mentioned
53                   method is used to derive the directory in which to create
54                   the temporary files. Only relevant if base64_to_fh is set.
55
56           The "base64*" parameters do not have to be implemented if the user
57           has no plans to use the "to_file" method of the RPC::XML::base64
58           data-class.
59
60           As a special-case, to preserve backwards compatibility with
61           pre-0.69 versions of this package, new() has special behavior when
62           specifically called for the package RPC::XML::Parser. When called
63           for this package, the constructor quietly loads
64           RPC::XML::ParserFactory and uses it to construct and return an
65           instance of a parser based on XML::Parser.
66
67       parse [ STRING | STREAM ]
68           Parse the XML document specified in either a string or a stream.
69           The stream may be any file descriptor, derivative of IO::Handle,
70           etc.
71
72           The value returned must be one of the following:
73
74           RPC::XML::request instance
75               When passed a valid XML-RPC request message, the return value
76               should be an instance of the RPC::XML::request class.
77
78           RPC::XML::response instance
79               Likewise, when passed a valid XML-RPC response, the return
80               value should be an instance of the RPC::XML::response class.
81
82           string containing an error message
83               If the message does not conform to either a request or a
84               response, or does not properly parse, the return value must be
85               a string containing the error message.
86
87           A non-blocking (push) parser instance
88               If no arguments are passed in, the return value must be a
89               parser object that implements push-parsing (non-blocking). It
90               does not have to be of the same class as the original object,
91               but it must support the remaining two methods
92
93       The next two methods are only called on push-parser instances, and as
94       such do not have to be implemented by the actual factory-compatible
95       parser. It is enough if the non-blocking parser instance it returns
96       from the no-argument call to parse() implements these:
97
98       parse_more STRING
99           Send a chunk of the current XML document to the parser for
100           processing.
101
102       parse_done
103           Signal the end of parsing. The return value from this should be one
104           of the same three possibilities that the direct use of parse()
105           (above) returns:
106
107           RPC::XML::request instance
108           RPC::XML::response instance
109           string containing an error message
110
111           parse_done() may also signal an error by throwing an exception.
112

DIAGNOSTICS

114       Unless otherwises specified, routines return the object reference
115       itself upon a successful operation, and an error string (which is not a
116       blessed reference) upon error.
117

BUGS

119       Please report any bugs or feature requests to "bug-rpc-xml at
120       rt.cpan.org", or through the web interface at
121       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
122       notified, and then you'll automatically be notified of progress on your
123       bug as I make changes.
124

SUPPORT

126       •   RT: CPAN's request tracker
127
128           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
129
130       •   AnnoCPAN: Annotated CPAN documentation
131
132           <http://annocpan.org/dist/RPC-XML>
133
134       •   CPAN Ratings
135
136           <http://cpanratings.perl.org/d/RPC-XML>
137
138       •   Search CPAN
139
140           <http://search.cpan.org/dist/RPC-XML>
141
142       •   MetaCPAN
143
144           <https://metacpan.org/release/RPC-XML>
145
146       •   Source code on GitHub
147
148           <http://github.com/rjray/rpc-xml>
149
151       This file and the code within are copyright (c) 2011 by Randy J. Ray.
152
153       Copying and distribution are permitted under the terms of the Artistic
154       License 2.0
155       (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
156       GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
157

CREDITS

159       The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
160       Inc.  See <http://www.xmlrpc.com> for more information about the XML-
161       RPC specification.
162

SEE ALSO

164       RPC::XML, RPC::XML::ParserFactory, RPC::XML::Parser::XMLParser
165

AUTHOR

167       Randy J. Ray <rjray@blackperl.com>
168
169
170
171perl v5.38.0                      2023-07-21               RPC::XML::Parser(3)
Impressum