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 The tool recognizes the following options:
33 --help
35 Prints a short summary of the options.
36 --name=STRING
38 Specifies the published name of the method being encoded. This is
39 the name by which it will be visible to clients of the server.
40 --namespace=STRING
42 Specifies a namespace that the code of the method will be evaluated
43 in, when the XPL file is loaded by a server instance.
44 --type=STRING
46 Specify the type for the resulting file. "Type" here refers to
47 whether the container tag used in the resulting XML will specify a
48 procedure or a method. The default is method. The string is treated
49 case-independant, and only the first character ("m" or "p") is
50 actually regarded.
51 --version=STRING
53 Specify a version stamp for the code routine.
54 --hidden
56 If this is passe, the resulting file will include a tag that tells
57 the server daemon to not make the routine visible through any
58 introspection interfaces.
59 --signature=STRING [ --signature=STRING ... ]
61 Specify one or more signatures for the method. Signatures should be
62 the type names as laid out in the documentation in RPC::XML, with
63 the elements separated by a colon. You may also separate them with
64 spaces, if you quote the argument. This option may be specified
65 more than once, as some methods may have several signatures.
66 --helptext=STRING
68 Specify the help text for the method as a simple string on the
69 command line. Not suited for terribly long help strings.
70 --helpfile=FILE
72 Read the help text for the method from the file specified.
73 --code=FILE
75 Read the actual code for the routine from the file specifed. If
76 this option is not given, the code is read from the standard input
77 file descriptor.
78 --output=FILE
80 Write the resulting XML representation to the specified file. If
81 this option is not given, then the output goes to the standard
82 output file descriptor.
83 --base=NAME
85 This is a special, "all-in-one" option. If passed, all other
86 options are ignored.
87 The value is used as the base element for reading information from
89 a file named BASE.base. This file will contain specification of the
90 name, version, hidden status, signatures and other method
91 information. Each line of the file should look like one of the
92 following:
93 Name: STRING
95 Specify the name of the routine being published. If this line
96 does not appear, then the value of the --base argument with all
97 directory elements removed will be used.
98 Version: STRING
100 Provide a version stamp for the function. If no line matching
101 this pattern is present, no version tag will be written.
102 Hidden: STRING
104 If present, STRING should be either "yes" or "no" (case not
105 important). If it is "yes", then the method is marked to be
106 hidden from any introspection API.
107 Signature: STRING
109 This line may appear more than once, and is treated
110 cumulatively. Other options override previous values if they
111 appear more than once. The portion following the "Signature:"
112 part is taken to be a published signature for the method, with
113 elements separated by whitespace. Each method must have at
114 least one signature, so a lack of any will cause an error.
115 Helpfile: STRING
117 Specifies the file from which to read the help text. It is not
118 an error if no help text is specified.
119 Codefile: STRING
121 Specifies the file from which to read the code. Code is assumed
122 to be Perl, and will be tagged as such in the resulting file.
123 Codefile[lang]: string
125 Specifies the file from which to read code, while also
126 identifying the language that the code is in. This allows for
127 the creation of a XPL file that includes multiple language
128 implementations of the given method or procedure.
129 Any other lines than the above patterns are ignored.
131 If no code has been read, then the tool will exit with an error
133 message.
134 The output is written to BASE.xpl, preserving the path information
136 so that the resulting file is right alongside the source files.
137 This allows constructs such as:
138 make_method --base=methods/introspection
140
142 The file format for these published routines is a very simple XML
143 dialect. This is less due to XML being an ideal format than it is the
144 availability of the parser, given that the RPC::XML::Server class will
145 already have the parser code in core. Writing a completely new format
146 would not have gained anything.
147 The Document Type Declaration for the format can be summarized by:
149 <!ELEMENT proceduredef (name, version?, hidden?, signature+,
151 help?, code)>
152 <!ELEMENT methoddef (name, version?, hidden?, signature+,
153 help?, code)>
154 <!ELEMENT functiondef (name, version?, hidden?, signature+,
155 help?, code)>
156 <!ELEMENT name (#PCDATA)>
157 <!ELEMENT version (#PCDATA)>
158 <!ELEMENT hidden EMPTY>
159 <!ELEMENT signature (#PCDATA)>
160 <!ELEMENT help (#PCDATA)>
161 <!ELEMENT code (#PCDATA)>
162 <!ATTLIST code language (#PCDATA)>
163 The file "rpc-method.dtd" that comes with the distribution has some
165 commentary in addition to the actual specification.
166 A file is (for now) limited to one definition. This is started by the
168 one of the opening tags "<methoddef>", "<functiondef>" or
169 "<proceduredef>". This is followed by exactly one "<name>" container
170 specifying the method name, an optional version stamp, an optional
171 hide-from-introspection flag, one or more "<signature>" containers
172 specifying signatures, an optional "<help>" container with the help
173 text, then the "<code>" container with the actual program code. All
174 text should use entity encoding for the symbols:
175 & C<&> (ampersand)
177 E<lt> C<<> (less-than)
178 E<gt> C<>> (greater-than)
179 The parsing process within the server class will decode the entities.
181 To make things easier, the tool scans all text elements and encodes the
182 above entities before writing the file.
183 The Specification of Code
185 This is not "Programming 101", nor is it "Perl for the Somewhat Dim".
186 The code that is passed in via one of the "*.xpl" files gets passed to
187 "eval" with next to no modification (see below). Thus, badly-written or
188 malicious code can very well wreak havoc on your server. This is not
189 the fault of the server code. The price of the flexibility this system
190 offers is the responsibility on the part of the developer to ensure
191 that the code is tested and safe.
192 Code itself is treated as verbatim as possible. Some edits may occur on
194 the server-side, as it make the code suitable for creating an anonymous
195 subroutine from. The make_method tool will attempt to use a "CDATA"
196 section to embed the code within the XML document, so that there is no
197 need to encode entities or such. This allows for the resulting *.xpl
198 files to be syntax-testable with "perl -cx". You can aid this by
199 ensuring that the code does not contain either of the two following
200 character sequences:
201 ]]>
203 __DATA__
205 The first is the "CDATA" terminator. If it occurs naturally in the
207 code, it would trigger the end-of-section in the parser. The second is
208 the familiar Perl token, which is inserted so that the remainder of the
209 XML document does not clutter up the Perl parser.
210
212 The RPC::XML distribution comes with a number of default methods in a
213 subdirectory called (cryptically enough) "methods". Each of these is
214 expressed as a set of ("*.base", "*.code", "*.help") files. The
215 Makefile.PL file configures the resulting Makefile such that these are
216 used to create "*.xpl" files using this tool, and then install them.
217
219 Most problems come out in the form of error messages followed by an
220 abrupt exit.
221
223 I don't much like this approach to specifying the methods, but I liked
224 my other ideas even less.
225
227 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
228 Inc. See <http://www.xmlrpc.com> for more information about the XML-
229 RPC specification.
230
232 This module and the code within are released under the terms of the
233 Artistic License 2.0
234 (http://www.opensource.org/licenses/artistic-license-2.0.php). This
235 code may be redistributed under either the Artistic License or the GNU
236 Lesser General Public License (LGPL) version 2.1
237 (http://www.opensource.org/licenses/lgpl-2.1.php).
238
240 RPC::XML, RPC::XML::Server
241
243 Randy J. Ray <rjray@blackperl.com>
244perl v5.12.0 2009-09-03 MAKE_METHOD(1)