1MAKE_METHOD(1) User Contributed Perl Documentation MAKE_METHOD(1)
2
6 make_method - Turn Perl code into an XML description for
7 RPC::XML::Server
8
10 make_method --name=system.identification --helptext='System ID string'
11 --signature=string --code=ident.pl --output=ident.xpl
12 make_method --base=methods/identification
14
16 This is a simple tool to create the XML descriptive files for
17 specifying methods to be published by an RPC::XML::Server-based server.
18 If a server is written such that the methods it exports (or publishes)
20 are a part of the running code, then there is no need for this tool.
21 However, in cases where the server may be separate and distinct from
22 the code (such as an Apache-based RPC server), specifying the routines
23 and filling in the supporting information can be cumbersome.
24 One solution that the RPC::XML::Server package offers is the means to
26 load publishable code from an external file. The file is in a simple
27 XML dialect that clearly delinates the externally-visible name, the
28 method signatures, the help text and the code itself. These files may
29 be created manually, or this tool may be used as an aide.
30
32 There are no required arguments, but if there are not sufficient
33 options passed you will be told by an error message.
34
36 The tool recognizes the following options:
37 --help
39 Prints a short summary of the options.
40 --name=STRING
42 Specifies the published name of the method being encoded. This is
43 the name by which it will be visible to clients of the server.
44 --namespace=STRING
46 Specifies a namespace that the code of the method will be evaluated
47 in, when the XPL file is loaded by a server instance.
48 --type=STRING
50 Specify the type for the resulting file. "Type" here refers to
51 whether the container tag used in the resulting XML will specify a
52 procedure or a method. The default is method. The string is treated
53 case-independant, and only the first character ("m" or "p") is
54 actually regarded.
55 --version=STRING
57 Specify a version stamp for the code routine.
58 --hidden
60 If this is passe, the resulting file will include a tag that tells
61 the server daemon to not make the routine visible through any
62 introspection interfaces.
63 --signature=STRING [ --signature=STRING ... ]
65 Specify one or more signatures for the method. Signatures should be
66 the type names as laid out in the documentation in RPC::XML, with
67 the elements separated by a colon. You may also separate them with
68 spaces, if you quote the argument. This option may be specified
69 more than once, as some methods may have several signatures.
70 --helptext=STRING
72 Specify the help text for the method as a simple string on the
73 command line. Not suited for terribly long help strings.
74 --helpfile=FILE
76 Read the help text for the method from the file specified.
77 --code=FILE
79 Read the actual code for the routine from the file specified. If
80 this option is not given, the code is read from the standard input
81 file descriptor.
82 --output=FILE
84 Write the resulting XML representation to the specified file. If
85 this option is not given, then the output goes to the standard
86 output file descriptor.
87 --base=NAME
89 This is a special, "all-in-one" option. If passed, all other
90 options are ignored.
91 The value is used as the base element for reading information from
93 a file named BASE.base. This file will contain specification of the
94 name, version, hidden status, signatures and other method
95 information. Each line of the file should look like one of the
96 following:
97 Name: STRING
99 Specify the name of the routine being published. If this line
100 does not appear, then the value of the --base argument with all
101 directory elements removed will be used.
102 Version: STRING
104 Provide a version stamp for the function. If no line matching
105 this pattern is present, no version tag will be written.
106 Hidden: STRING
108 If present, STRING should be either "yes" or "no" (case not
109 important). If it is "yes", then the method is marked to be
110 hidden from any introspection API.
111 Signature: STRING
113 This line may appear more than once, and is treated
114 cumulatively. Other options override previous values if they
115 appear more than once. The portion following the "Signature:"
116 part is taken to be a published signature for the method, with
117 elements separated by whitespace. Each method must have at
118 least one signature, so a lack of any will cause an error.
119 Helpfile: STRING
121 Specifies the file from which to read the help text. It is not
122 an error if no help text is specified.
123 Codefile: STRING
125 Specifies the file from which to read the code. Code is assumed
126 to be Perl, and will be tagged as such in the resulting file.
127 Codefile[lang]: string
129 Specifies the file from which to read code, while also
130 identifying the language that the code is in. This allows for
131 the creation of a XPL file that includes multiple language
132 implementations of the given method or procedure.
133 Any other lines than the above patterns are ignored.
135 If no code has been read, then the tool will exit with an error
137 message.
138 The output is written to BASE.xpl, preserving the path information
140 so that the resulting file is right alongside the source files.
141 This allows constructs such as:
142 make_method --base=methods/introspection
144
146 The file format for these published routines is a very simple XML
147 dialect. This is less due to XML being an ideal format than it is the
148 availability of the parser, given that the RPC::XML::Server class will
149 already have the parser code in core. Writing a completely new format
150 would not have gained anything.
151 The Document Type Declaration for the format can be summarized by:
153 <!ELEMENT proceduredef (name, namespace?, version?, hidden?,
155 signature+, help?, code)>
156 <!ELEMENT methoddef (name, namespace?, version?, hidden?,
157 signature+, help?, code)>
158 <!ELEMENT functiondef (name, namespace?, version?, hidden?,
159 signature+, help?, code)>
160 <!ELEMENT name (#PCDATA)>
161 <!ELEMENT namespace (#PCDATA)>
162 <!ELEMENT version (#PCDATA)>
163 <!ELEMENT hidden EMPTY>
164 <!ELEMENT signature (#PCDATA)>
165 <!ELEMENT help (#PCDATA)>
166 <!ELEMENT code (#PCDATA)>
167 <!ATTLIST code language (#PCDATA)>
168 The file "rpc-method.dtd" that comes with the distribution has some
170 commentary in addition to the actual specification.
171 A file is (for now) limited to one definition. This is started by the
173 one of the opening tags "<methoddef>", "<functiondef>" or
174 "<proceduredef>". This is followed by exactly one "<name>" container
175 specifying the method name, an optional version stamp, an optional
176 hide-from-introspection flag, one or more "<signature>" containers
177 specifying signatures, an optional "<help>" container with the help
178 text, then the "<code>" container with the actual program code. All
179 text should use entity encoding for the symbols:
180 & C<&> (ampersand)
182 E<lt> C<<> (less-than)
183 E<gt> C<>> (greater-than)
184 The parsing process within the server class will decode the entities.
186 To make things easier, the tool scans all text elements and encodes the
187 above entities before writing the file.
188 The Specification of Code
190 This is not "Programming 101", nor is it "Perl for the Somewhat Dim".
191 The code that is passed in via one of the "*.xpl" files gets passed to
192 "eval" with next to no modification (see below). Thus, badly-written or
193 malicious code can very well wreak havoc on your server. This is not
194 the fault of the server code. The price of the flexibility this system
195 offers is the responsibility on the part of the developer to ensure
196 that the code is tested and safe.
197 Code itself is treated as verbatim as possible. Some edits may occur on
199 the server-side, as it make the code suitable for creating an anonymous
200 subroutine from. The make_method tool will attempt to use a "CDATA"
201 section to embed the code within the XML document, so that there is no
202 need to encode entities or such. This allows for the resulting *.xpl
203 files to be syntax-testable with "perl -cx". You can aid this by
204 ensuring that the code does not contain either of the two following
205 character sequences:
206 ]]>
208 __DATA__
210 The first is the "CDATA" terminator. If it occurs naturally in the
212 code, it would trigger the end-of-section in the parser. The second is
213 the familiar Perl token, which is inserted so that the remainder of the
214 XML document does not clutter up the Perl parser.
215
217 The RPC::XML distribution comes with a number of default methods in a
218 subdirectory called (cryptically enough) "methods". Each of these is
219 expressed as a set of ("*.base", "*.code", "*.help") files. The
220 Makefile.PL file configures the resulting Makefile such that these are
221 used to create "*.xpl" files using this tool, and then install them.
222
224 Most problems come out in the form of error messages followed by an
225 abrupt exit.
226
228 The tool exits with a status of 0 upon success, and 255 otherwise.
229
231 I don't much like this approach to specifying the methods, but I liked
232 my other ideas even less.
233
235 Please report any bugs or feature requests to "bug-rpc-xml at
236 rt.cpan.org", or through the web interface at
237 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
238 notified, and then you'll automatically be notified of progress on your
239 bug as I make changes.
240
242 • RT: CPAN's request tracker
243 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
245 • AnnoCPAN: Annotated CPAN documentation
247 <http://annocpan.org/dist/RPC-XML>
249 • CPAN Ratings
251 <http://cpanratings.perl.org/d/RPC-XML>
253 • Search CPAN
255 <http://search.cpan.org/dist/RPC-XML>
257 • Source code on GitHub
259 <http://github.com/rjray/rpc-xml>
261
263 This module and the code within are released under the terms of the
264 Artistic License 2.0
265 (http://www.opensource.org/licenses/artistic-license-2.0.php). This
266 code may be redistributed under either the Artistic License or the GNU
267 Lesser General Public License (LGPL) version 2.1
268 (http://www.opensource.org/licenses/lgpl-2.1.php).
269
271 RPC::XML, RPC::XML::Server
272
274 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
275 Inc. See <http://www.xmlrpc.com> for more information about the XML-
276 RPC specification.
277
279 Randy J. Ray <rjray@blackperl.com>
280perl v5.36.0 2023-01-20 MAKE_METHOD(1)