Update of /cvsroot/perl-xml/xml-simple/lib/XML
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1289/lib/XML
Modified Files:
Simple.pm
Log Message:
- added documentation for hook methods
Index: Simple.pm
===================================================================
RCS file: /cvsroot/perl-xml/xml-simple/lib/XML/Simple.pm,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -d -r1.35 -r1.36
--- Simple.pm 25 Jan 2007 10:21:14 -0000 1.35
+++ Simple.pm 29 Jan 2007 10:17:06 -0000 1.36
@@ -324,7 +324,7 @@
# XML. If XML::SAX is installed, the default SAX parser will be used,
# otherwise XML::Parser will be used.
#
-# This routine expects to be passed a 'string' as argument 1 or a filename as
+# This routine expects to be passed a filename as argument 1 or a 'string' as
# argument 2. The 'string' might be a string of XML (passed by reference to
# save memory) or it might be a reference to an IO::Handle. (This
# non-intuitive mess results in part from the way XML::Parser works but that's
@@ -2735,11 +2735,6 @@
will be merged with the values specified when the object was created. Values
specified in a method call take precedence.
-Overriding methods is a more advanced topic but might be useful if for example
-you wished to provide an alternative routine for escaping character data (the
-escape_value method) or for building the initial parse tree (the build_tree
-method).
-
Note: when called as methods, the C<XMLin()> and C<XMLout()> routines may be
called as C<xml_in()> or C<xml_out()>. The method names are aliased so the
only difference is the aesthetics.
@@ -2752,17 +2747,17 @@
=over 4
-=item parse_string
+=item parse_string(text)
Works exactly like the C<xml_in()> method but assumes the first argument is
a string of XML (or a reference to a scalar containing a string of XML).
-=item parse_file
+=item parse_file(filename)
Works exactly like the C<xml_in()> method but assumes the first argument is
the name of a file containing XML.
-=item parse_fh
+=item parse_fh(file_handle)
Works exactly like the C<xml_in()> method but assumes the first argument is
a filehandle which can be read to get XML.
@@ -2772,23 +2767,77 @@
=head2 Hook Methods
You can make your own class which inherits from XML::Simple and overrides
-certain behaviour. The following methods may provide useful 'hooks' upon which
-to hang your modified behaviour. You may find other undocumented places by
-examining the source, but those methods may change in future releases.
+certain behaviours. The following methods may provide useful 'hooks' upon
+which to hang your modified behaviour. You may find other undocumented methods
+by examining the source, but those may be subject to change in future releases.
=over 4
-=item default_config_file
+=item handle_options(direction, name => value ...)
+
+This method will be called when one of the parsing methods or the C<XMLout()>
+method is called. The initial argument will be a string (either 'in' or 'out')
+and the remaining arguments will be name value pairs.
+
+=item default_config_file()
Calculates and returns the name of the file which should be parsed if no
filename is passed to C<XMLin()> (default: C<$0.xml>).
-=item TODO
+=item build_simple_tree(filename, string)
-more here
+Called from C<XMLin()> or any of the parsing methods. Takes either a file name
+as the first argument or C<undef> followed by a 'string' as the second
+argument. Returns a simple tree data structure. You could override this
+method to apply your own transformations before the data structure is returned
+to the caller.
+
+=item new_hashref()
+
+When the 'simple tree' data structure is being built, this method will be
+called to create any required anonymous hashrefs.
+
+=item sorted_keys(name, hashref)
+
+Called when C<XMLout()> is translating a hashref to XML. This routine returns
+a list of hash keys in the order that the corresponding attributes/elements
+should appear in the output.
+
+=item escape_value(string)
+
+Called from C<XMLout()>, takes a string and returns a copy of the string with
+XML character escaping rules applied.
+
+=item numeric_escape(string)
+
+Called from C<escape_value()>, to handle non-ASCII characters (depending on the
+value of the NumericEscape option).
+
+=item copy_hash(hashref, extra_key => value, ...)
+
+Called from C<XMLout()>, when 'unfolding' a hash of hashes into an array of
+hashes. You might wish to override this method if you're using tied hashes and
+don't want them to get untied.
=back
+=head2 Cache Methods
+
+XML::Simple implements three caching schemes ('storable', 'memshare' and
+'memcopy'). You can implement a custom caching scheme by implementing
+two methods - one for reading from the cache and one for writing to it.
+
+For example, you might implement a new 'dbm' scheme that stores cached data
+structures using the L<MLDBM> module. First, you would add a
+C<cache_read_dbm()> method which accepted a filename for use as a lookup key
+and returned a data structure on success, or undef on failure. Then, you would
+implement a C<cache_read_dbm()> method which accepted a data structure and a
+filename.
+
+You would use this caching scheme by specifying the option:
+
+ Cache => [ 'dbm' ]
+
=head1 STRICT MODE
If you import the B<XML::Simple> routines like this: