simple.html

perl教程

<h2><a name="outputfile_____file_specifier____out__handy">OutputFile =&gt; &lt;file specifier&gt; <em># out - handy</em></a></h2>
<p>The default behaviour of <code>XMLout()</code> is to return the XML as a string.  If you
wish to write the XML to a file, simply supply the filename using the
'OutputFile' option.</p>
<p>This option also accepts an IO handle object - especially useful in Perl 5.8.0 
and later for output using an encoding other than UTF-8, eg:</p>
<pre>
  <span class="keyword">open</span> <span class="keyword">my</span> <span class="variable">$fh</span><span class="operator">,</span> <span class="string">'&gt;:encoding(iso-8859-1)'</span><span class="operator">,</span> <span class="variable">$path</span> <span class="keyword">or</span> <span class="keyword">die</span> <span class="string">"open($path): $!"</span><span class="operator">;</span>
  <span class="variable">XMLout</span><span class="operator">(</span><span class="variable">$ref</span><span class="operator">,</span> <span class="string">OutputFile</span> <span class="operator">=&gt;</span> <span class="variable">$fh</span><span class="operator">);</span>
</pre>
<p>Note, XML::Simple does not require that the object you pass in to the
OutputFile option inherits from <a href="../../lib/IO/Handle.html">the IO::Handle manpage</a> - it simply assumes the object
supports a <a href="../../lib/Pod/perlfunc.html#item_print"><code>print</code></a> method.</p>
<p>
</p>
<h2><a name="parseropts______xml__parser_options_____in__don_t_use_this">ParserOpts =&gt; [ XML::Parser Options ] <em># in - don't use this</em></a></h2>
<p><em>Note: This option is now officially deprecated.  If you find it useful, email
the author with an example of what you use it for.  Do not use this option to
set the ProtocolEncoding, that's just plain wrong - fix the XML</em>.</p>
<p>This option allows you to pass parameters to the constructor of the underlying
XML::Parser object (which of course assumes you're not using SAX).</p>
<p>
</p>
<h2><a name="rootname_____string____out__handy">RootName =&gt; 'string' <em># out - handy</em></a></h2>
<p>By default, when <code>XMLout()</code> generates XML, the root element will be named
'opt'.  This option allows you to specify an alternative name.</p>
<p>Specifying either undef or the empty string for the RootName option will
produce XML with no root elements.  In most cases the resulting XML fragment
will not be 'well formed' and therefore could not be read back in by <code>XMLin()</code>.
Nevertheless, the option has been found to be useful in certain circumstances.</p>
<p>
</p>
<h2><a name="searchpath______list_____in__handy">SearchPath =&gt; [ list ] <em># in - handy</em></a></h2>
<p>If you pass <code>XMLin()</code> a filename, but the filename include no directory
component, you can use this option to specify which directories should be
searched to locate the file.  You might use this option to search first in the
user's home directory, then in a global directory such as /etc.</p>
<p>If a filename is provided to <code>XMLin()</code> but SearchPath is not defined, the
file is assumed to be in the current directory.</p>
<p>If the first parameter to <code>XMLin()</code> is undefined, the default SearchPath
will contain only the directory in which the script itself is located.
Otherwise the default SearchPath will be empty.</p>
<p>
</p>
<h2><a name="suppressempty____1________undef___in_out__handy">SuppressEmpty =&gt; 1 | '' | undef <em># in+out - handy</em></a></h2>
<p>This option controls what <code>XMLin()</code> should do with empty elements (no
attributes and no content).  The default behaviour is to represent them as
empty hashes.  Setting this option to a true value (eg: 1) will cause empty
elements to be skipped altogether.  Setting the option to 'undef' or the empty
string will cause empty elements to be represented as the undefined value or
the empty string respectively.  The latter two alternatives are a little
easier to test for in your code than a hash with no keys.</p>
<p>The option also controls what <code>XMLout()</code> does with undefined values.  Setting
the option to undef causes undefined values to be output as empty elements
(rather than empty attributes), it also suppresses the generation of warnings
about undefined values.  Setting the option to a true value (eg: 1) causes
undefined values to be skipped altogether on output.</p>
<p>
</p>
<h2><a name="valueattr______names_____in__handy">ValueAttr =&gt; [ names ] <em># in - handy</em></a></h2>
<p>Use this option to deal elements which always have a single attribute and no
content.  Eg:</p>
<pre>
  &lt;opt&gt;
    &lt;colour value=&quot;red&quot; /&gt;
    &lt;size   value=&quot;XXL&quot; /&gt;
  &lt;/opt&gt;</pre>
<p>Setting <code>ValueAttr =&gt; [ 'value' ]</code> will cause the above XML to parse to:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">colour</span> <span class="operator">=&gt;</span> <span class="string">'red'</span><span class="operator">,</span>
    <span class="string">size</span>   <span class="operator">=&gt;</span> <span class="string">'XXL'</span>
  <span class="operator">}</span>
</pre>
<p>instead of this (the default):</p>
<pre>
  <span class="operator">{</span>
    <span class="string">colour</span> <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">value</span> <span class="operator">=&gt;</span> <span class="string">'red'</span> <span class="operator">}</span><span class="operator">,</span>
    <span class="string">size</span>   <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">value</span> <span class="operator">=&gt;</span> <span class="string">'XXL'</span> <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>Note: This form of the ValueAttr option is not compatible with <code>XMLout()</code> -
since the attribute name is discarded at parse time, the original XML cannot be
reconstructed.</p>
<p>
</p>
<h2><a name="valueattr______element____attribute__________in_out__handy">ValueAttr =&gt; { element =&gt; attribute, ... } <em># in+out - handy</em></a></h2>
<p>This (preferred) form of the ValueAttr option requires you to specify both
the element and the attribute names.  This is not only safer, it also allows
the original XML to be reconstructed by <code>XMLout()</code>.</p>
<p>Note: You probably don't want to use this option and the NoAttr option at the
same time.</p>
<p>
</p>
<h2><a name="variables______name____value_____in__handy">Variables =&gt; { name =&gt; value } <em># in - handy</em></a></h2>
<p>This option allows variables in the XML to be expanded when the file is read.
(there is no facility for putting the variable names back if you regenerate
XML using <code>XMLout</code>).</p>
<p>A 'variable' is any text of the form <code>${name}</code> which occurs in an attribute
value or in the text content of an element.  If 'name' matches a key in the
supplied hashref, <code>${name}</code> will be replaced with the corresponding value from
the hashref.  If no matching key is found, the variable will not be replaced.
Names must match the regex: <code>[\w.]+</code> (ie: only 'word' characters and dots are
allowed).</p>
<p>
</p>
<h2><a name="varattr_____attr_name____in__handy">VarAttr =&gt; 'attr_name' <em># in - handy</em></a></h2>
<p>In addition to the variables defined using <code>Variables</code>, this option allows
variables to be defined in the XML.  A variable definition consists of an
element with an attribute called 'attr_name' (the value of the <code>VarAttr</code>
option).  The value of the attribute will be used as the variable name and the
text content of the element will be used as the value.  A variable defined in
this way will override a variable defined using the <code>Variables</code> option.  For
example:</p>
<pre>
  <span class="variable">XMLin</span><span class="operator">(</span> <span class="string">'&lt;opt&gt;
            &lt;dir name="prefix"&gt;/usr/local/apache&lt;/dir&gt;
            &lt;dir name="exec_prefix"&gt;${prefix}&lt;/dir&gt;
            &lt;dir name="bindir"&gt;${exec_prefix}/bin&lt;/dir&gt;
          &lt;/opt&gt;'</span><span class="operator">,</span>
         <span class="string">VarAttr</span> <span class="operator">=&gt;</span> <span class="string">'name'</span><span class="operator">,</span> <span class="string">ContentKey</span> <span class="operator">=&gt;</span> <span class="string">'-content'</span>
        <span class="operator">);</span>
</pre>
<p>produces the following data structure:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">dir</span> <span class="operator">=&gt;</span> <span class="operator">{</span>
             <span class="string">prefix</span>      <span class="operator">=&gt;</span> <span class="string">'/usr/local/apache'</span><span class="operator">,</span>
             <span class="string">exec_prefix</span> <span class="operator">=&gt;</span> <span class="string">'/usr/local/apache'</span><span class="operator">,</span>
             <span class="string">bindir</span>      <span class="operator">=&gt;</span> <span class="string">'/usr/local/apache/bin'</span><span class="operator">,</span>
           <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>
</p>
<h2><a name="xmldecl____1_or_xmldecl_____string____out__handy">XMLDecl =&gt; 1  or  XMLDecl =&gt; 'string'  <em># out - handy</em></a></h2>
<p>If you want the output from <code>XMLout()</code> to start with the optional XML
declaration, simply set the option to '1'.  The default XML declaration is:</p>
<pre>
        &lt;?xml version='1.0' standalone='yes'?&gt;</pre>
<p>If you want some other string (for example to declare an encoding value), set
the value of this option to the complete string you require.</p>
<p>
</p>
<hr />
<h1><a name="optional_oo_interface">OPTIONAL OO INTERFACE</a></h1>
<p>The procedural interface is both simple and convenient however there are a
couple of reasons why you might prefer to use the object oriented (OO)
interface:</p>
<ul>
<li>
<p>to define a set of default values which should be used on all subsequent calls
to <code>XMLin()</code> or <code>XMLout()</code></p>
</li>
<li>
<p>to override methods in <strong>XML::Simple</strong> to provide customised behaviour</p>
</li>
</ul>
<p>The default values for the options described above are unlikely to suit
everyone.  The OO interface allows you to effectively override <strong>XML::Simple</strong>'s
defaults with your preferred values.  It works like this:</p>
<p>First create an XML::Simple parser object with your preferred defaults:</p>
<pre>
  <span class="keyword">my</span> <span class="variable">$xs</span> <span class="operator">=</span> <span class="variable">XML::Simple</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">(</span><span class="string">ForceArray</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">,</span> <span class="string">KeepRoot</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">);</span>
</pre>
<p>then call <code>XMLin()</code> or <code>XMLout()</code> as a method of that object:</p>
<pre>
  <span class="keyword">my</span> <span class="variable">$ref</span> <span class="operator">=</span> <span class="variable">$xs</span><span class="operator">-&gt;</span><span class="variable">XMLin</span><span class="operator">(</span><span class="variable">$xml</span><span class="operator">);</span>
  <span class="keyword">my</span> <span class="variable">$xml</span> <span class="operator">=</span> <span class="variable">$xs</span><span class="operator">-&gt;</span><span class="variable">XMLout</span><span class="operator">(</span><span class="variable">$ref</span><span class="operator">);</span>
</pre>
<p>You can also specify options when you make the method calls and these values
will be merged with the values specified when the object was created.  Values
specified in a method call take precedence.</p>
<p>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).</p>
<p>Note: when called as methods, the <code>XMLin()</code> and <code>XMLout()</code> routines may be
called as <code>xml_in()</code> or <code>xml_out()</code>.  The method names are aliased so the
only difference is the aesthetics.</p>
<p>
</p>
<hr />
<h1><a name="strict_mode">STRICT MODE</a></h1>
<p>If you import the <strong>XML::Simple</strong> routines like this:</p>
<pre>
  <span class="keyword">use</span> <span class="variable">XML::Simple</span> <span class="string">qw(:strict)</span><span class="operator">;</span>
</pre>
<p>the following common mistakes will be detected and treated as fatal errors</p>
<ul>
<li>
<p>Failing to explicitly set the <code>KeyAttr</code> option - if you can't be bothered
reading about this option, turn it off with: KeyAttr =&gt; [ ]</p>
</li>
<li>
<p>Failing to explicitly set the <code>ForceArray