From: Grant M. <gr...@us...> - 2007-01-29 10:17:09
|
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: |