simple.html

perl教程

<p>If your needs are not so simple, this may not be the module for you.  In that
case, you might want to read <a href="#where_to_from_here">WHERE TO FROM HERE?</a>.</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The XML::Simple module provides a simple API layer on top of an underlying XML
parsing module (either XML::Parser or one of the SAX2 parser modules).  Two
functions are exported: <code>XMLin()</code> and <code>XMLout()</code>.  Note: you can explicity
request the lower case versions of the function names: <code>xml_in()</code> and
<code>xml_out()</code>.</p>
<p>The simplest approach is to call these two functions directly, but an
optional object oriented interface (see <a href="#optional_oo_interface">OPTIONAL OO INTERFACE</a> below)
allows them to be called as methods of an <strong>XML::Simple</strong> object.  The object
interface can also be used at either end of a SAX pipeline.</p>
<p>
</p>
<h2><a name="xmlin__"><code>XMLin()</code></a></h2>
<p>Parses XML formatted data and returns a reference to a data structure which
contains the same information in a more readily accessible form.  (Skip
down to <a href="#examples">EXAMPLES</a> below, for more sample code).</p>
<p><code>XMLin()</code> accepts an optional XML specifier followed by zero or more 'name =&gt;
value' option pairs.  The XML specifier can be one of the following:</p>
<dl>
<dt><strong><a name="item_a_filename">A filename</a></strong>

<dd>
<p>If the filename contains no directory components <code>XMLin()</code> will look for the
file in each directory in the SearchPath (see <a href="#options">OPTIONS</a> below) or in the
current directory if the SearchPath option is not defined.  eg:</p>
</dd>
<dd>
<pre>
  <span class="variable">$ref</span> <span class="operator">=</span> <span class="variable">XMLin</span><span class="operator">(</span><span class="string">'/etc/params.xml'</span><span class="operator">);</span>
</pre>
</dd>
<dd>
<p>Note, the filename '-' can be used to parse from STDIN.</p>
</dd>
</li>
<dt><strong><a name="item_undef">undef</a></strong>

<dd>
<p>If there is no XML specifier, <code>XMLin()</code> will check the script directory and
each of the SearchPath directories for a file with the same name as the script
but with the extension '.xml'.  Note: if you wish to specify options, you
must specify the value 'undef'.  eg:</p>
</dd>
<dd>
<pre>
  <span class="variable">$ref</span> <span class="operator">=</span> <span class="variable">XMLin</span><span class="operator">(</span><span class="keyword">undef</span><span class="operator">,</span> <span class="string">ForceArray</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">);</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_a_string_of_xml">A string of XML</a></strong>

<dd>
<p>A string containing XML (recognised by the presence of '&lt;' and '&gt;' characters)
will be parsed directly.  eg:</p>
</dd>
<dd>
<pre>
  <span class="variable">$ref</span> <span class="operator">=</span> <span class="variable">XMLin</span><span class="operator">(</span><span class="string">'&lt;opt username="bob" password="flurp" /&gt;'</span><span class="operator">);</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_an_io_3a_3ahandle_object">An IO::Handle object</a></strong>

<dd>
<p>An IO::Handle object will be read to EOF and its contents parsed. eg:</p>
</dd>
<dd>
<pre>
  <span class="variable">$fh</span> <span class="operator">=</span> <span class="variable">IO::File</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">(</span><span class="string">'/etc/params.xml'</span><span class="operator">);</span>
  <span class="variable">$ref</span> <span class="operator">=</span> <span class="variable">XMLin</span><span class="operator">(</span><span class="variable">$fh</span><span class="operator">);</span>
</pre>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="xmlout__"><code>XMLout()</code></a></h2>
<p>Takes a data structure (generally a hashref) and returns an XML encoding of
that structure.  If the resulting XML is parsed using <code>XMLin()</code>, it should
return a data structure equivalent to the original (see caveats below).</p>
<p>The <code>XMLout()</code> function can also be used to output the XML as SAX events
see the <code>Handler</code> option and <a href="#sax_support">SAX SUPPORT</a> for more details).</p>
<p>When translating hashes to XML, hash keys which have a leading '-' will be
silently skipped.  This is the approved method for marking elements of a
data structure which should be ignored by <code>XMLout</code>.  (Note: If these items
were not skipped the key names would be emitted as element or attribute names
with a leading '-' which would not be valid XML).</p>
<p>
</p>
<h2><a name="caveats">Caveats</a></h2>
<p>Some care is required in creating data structures which will be passed to
<code>XMLout()</code>.  Hash keys from the data structure will be encoded as either XML
element names or attribute names.  Therefore, you should use hash key names 
which conform to the relatively strict XML naming rules:</p>
<p>Names in XML must begin with a letter.  The remaining characters may be
letters, digits, hyphens (-), underscores (_) or full stops (.).  It is also
allowable to include one colon (:) in an element name but this should only be
used when working with namespaces (<strong>XML::Simple</strong> can only usefully work with
namespaces when teamed with a SAX Parser).</p>
<p>You can use other punctuation characters in hash values (just not in hash
keys) however <strong>XML::Simple</strong> does not support dumping binary data.</p>
<p>If you break these rules, the current implementation of <code>XMLout()</code> will 
simply emit non-compliant XML which will be rejected if you try to read it
back in.  (A later version of <strong>XML::Simple</strong> might take a more proactive
approach).</p>
<p>Note also that although you can nest hashes and arrays to arbitrary levels,
circular data structures are not supported and will cause <code>XMLout()</code> to die.</p>
<p>If you wish to 'round-trip' arbitrary data structures from Perl to XML and back 
to Perl, then you should probably disable array folding (using the KeyAttr
option) both with <code>XMLout()</code> and with <code>XMLin()</code>.  If you still don't get the 
expected results, you may prefer to use <a href="../../XML/Dumper.html">the XML::Dumper manpage</a> which is designed for
exactly that purpose.</p>
<p>Refer to <a href="#where_to_from_here">WHERE TO FROM HERE?</a> if <code>XMLout()</code> is too simple for your needs.</p>
<p>
</p>
<hr />
<h1><a name="options">OPTIONS</a></h1>
<p><strong>XML::Simple</strong> supports a number of options (in fact as each release of
<strong>XML::Simple</strong> adds more options, the module's claim to the name 'Simple'
becomes increasingly tenuous).  If you find yourself repeatedly having to
specify the same options, you might like to investigate <a href="#optional_oo_interface">OPTIONAL OO INTERFACE</a> below.</p>
<p>If you can't be bothered reading the documentation, refer to
<a href="#strict_mode">STRICT MODE</a> to automatically catch common mistakes.</p>
<p>Because there are so many options, it's hard for new users to know which ones
are important, so here are the two you really need to know about:</p>
<ul>
<li>
<p>check out <code>ForceArray</code> because you'll almost certainly want to turn it on</p>
</li>
<li>
<p>make sure you know what the <code>KeyAttr</code> option does and what its default value is
because it may surprise you otherwise (note in particular that 'KeyAttr'
affects both <code>XMLin</code> and <code>XMLout</code>)</p>
</li>
</ul>
<p>The option name headings below have a trailing 'comment' - a hash followed by
two pieces of metadata:</p>
<ul>
<li>
<p>Options are marked with '<em>in</em>' if they are recognised by <code>XMLin()</code> and
'<em>out</em>' if they are recognised by <code>XMLout()</code>.</p>
</li>
<li>
<p>Each option is also flagged to indicate whether it is:</p>
<pre>
 'important'   - don't use the module until you understand this one
 'handy'       - you can skip this on the first time through
 'advanced'    - you can skip this on the second time through
 'SAX only'    - don't worry about this unless you're using SAX (or
                 alternatively if you need this, you also need SAX)
 'seldom used' - you'll probably never use this unless you were the
                 person that requested the feature</pre>
</li>
</ul>
<p>The options are listed alphabetically:</p>
<p>Note: option names are no longer case sensitive so you can use the mixed case
versions shown here; all lower case as required by versions 2.03 and earlier;
or you can add underscores between the words (eg: key_attr).</p>
<p>
</p>
<h2><a name="attrindent____1___out__handy">AttrIndent =&gt; 1 <em># out - handy</em></a></h2>
<p>When you are using <code>XMLout()</code>, enable this option to have attributes printed
one-per-line with sensible indentation rather than all on one line.</p>
<p>
</p>
<h2><a name="cache______cache_schemes_____in__advanced">Cache =&gt; [ cache schemes ] <em># in - advanced</em></a></h2>
<p>Because loading the <strong>XML::Parser</strong> module and parsing an XML file can consume a
significant number of CPU cycles, it is often desirable to cache the output of
<code>XMLin()</code> for later reuse.</p>
<p>When parsing from a named file, <strong>XML::Simple</strong> supports a number of caching
schemes.  The 'Cache' option may be used to specify one or more schemes (using
an anonymous array).  Each scheme will be tried in turn in the hope of finding
a cached pre-parsed representation of the XML file.  If no cached copy is
found, the file will be parsed and the first cache scheme in the list will be
used to save a copy of the results.  The following cache schemes have been
implemented:</p>
<dl>
<dt><strong><a name="item_storable">storable</a></strong>

<dd>
<p>Utilises <strong>Storable.pm</strong> to read/write a cache file with the same name as the
XML file but with the extension .stor</p>
</dd>
</li>
<dt><strong><a name="item_memshare">memshare</a></strong>

<dd>
<p>When a file is first parsed, a copy of the resulting data structure is retained
in memory in the <strong>XML::Simple</strong> module's namespace.  Subsequent calls to parse
the same file will return a reference to this structure.  This cached version
will persist only for the life of the Perl interpreter (which in the case of
mod_perl for example, may be some significant time).</p>
</dd>