simple.html

perl教程

<dd>
<p>Because each caller receives a reference to the same data structure, a change
made by one caller will be visible to all.  For this reason, the reference
returned should be treated as read-only.</p>
</dd>
</li>
<dt><strong><a name="item_memcopy">memcopy</a></strong>

<dd>
<p>This scheme works identically to 'memshare' (above) except that each caller
receives a reference to a new data structure which is a copy of the cached
version.  Copying the data structure will add a little processing overhead,
therefore this scheme should only be used where the caller intends to modify
the data structure (or wishes to protect itself from others who might).  This
scheme uses <strong>Storable.pm</strong> to perform the copy.</p>
</dd>
</li>
</dl>
<p>Warning! The memory-based caching schemes compare the timestamp on the file to
the time when it was last parsed.  If the file is stored on an NFS filesystem
(or other network share) and the clock on the file server is not exactly
synchronised with the clock where your script is run, updates to the source XML
file may appear to be ignored.</p>
<p>
</p>
<h2><a name="contentkey_____keyname____in_out__seldom_used">ContentKey =&gt; 'keyname' <em># in+out - seldom used</em></a></h2>
<p>When text content is parsed to a hash value, this option let's you specify a
name for the hash key to override the default 'content'.  So for example:</p>
<pre>
  XMLin('&lt;opt one=&quot;1&quot;&gt;Text&lt;/opt&gt;', ContentKey =&gt; 'text')</pre>
<p>will parse to:</p>
<pre>
  <span class="operator">{</span> <span class="string">'one'</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">,</span> <span class="string">'text'</span> <span class="operator">=&gt;</span> <span class="string">'Text'</span> <span class="operator">}</span>
</pre>
<p>instead of:</p>
<pre>
  <span class="operator">{</span> <span class="string">'one'</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">,</span> <span class="string">'content'</span> <span class="operator">=&gt;</span> <span class="string">'Text'</span> <span class="operator">}</span>
</pre>
<p><code>XMLout()</code> will also honour the value of this option when converting a hashref
to XML.</p>
<p>You can also prefix your selected key name with a '-' character to have 
<code>XMLin()</code> try a little harder to eliminate unnecessary 'content' keys after
array folding.  For example:</p>
<pre>
  <span class="variable">XMLin</span><span class="operator">(</span>
    <span class="string">'&lt;opt&gt;&lt;item name="one"&gt;First&lt;/item&gt;&lt;item name="two"&gt;Second&lt;/item&gt;&lt;/opt&gt;'</span><span class="operator">,</span> 
    <span class="string">KeyAttr</span> <span class="operator">=&gt;</span> <span class="operator">{</span><span class="string">item</span> <span class="operator">=&gt;</span> <span class="string">'name'</span><span class="operator">}</span><span class="operator">,</span> 
    <span class="string">ForceArray</span> <span class="operator">=&gt;</span> <span class="operator">[</span> <span class="string">'item'</span> <span class="operator">]</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>will parse to:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">'item'</span> <span class="operator">=&gt;</span> <span class="operator">{</span>
      <span class="string">'one'</span> <span class="operator">=&gt;</span>  <span class="string">'First'</span>
      <span class="string">'two'</span> <span class="operator">=&gt;</span>  <span class="string">'Second'</span>
    <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>rather than this (without the '-'):</p>
<pre>
  <span class="operator">{</span>
    <span class="string">'item'</span> <span class="operator">=&gt;</span> <span class="operator">{</span>
      <span class="string">'one'</span> <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">'content'</span> <span class="operator">=&gt;</span> <span class="string">'First'</span> <span class="operator">}</span>
      <span class="string">'two'</span> <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">'content'</span> <span class="operator">=&gt;</span> <span class="string">'Second'</span> <span class="operator">}</span>
    <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>
</p>
<h2><a name="datahandler____code_ref___in__sax_only">DataHandler =&gt; code_ref <em># in - SAX only</em></a></h2>
<p>When you use an <strong>XML::Simple</strong> object as a SAX handler, it will return a
'simple tree' data structure in the same format as <code>XMLin()</code> would return.  If
this option is set (to a subroutine reference), then when the tree is built the
subroutine will be called and passed two arguments: a reference to the
<strong>XML::Simple</strong> object and a reference to the data tree.  The return value from
the subroutine will be returned to the SAX driver.  (See <a href="#sax_support">SAX SUPPORT</a> for
more details).</p>
<p>
</p>
<h2><a name="forcearray____1___in__important">ForceArray =&gt; 1 <em># in - important</em></a></h2>
<p>This option should be set to '1' to force nested elements to be represented
as arrays even when there is only one.  Eg, with ForceArray enabled, this
XML:</p>
<pre>
    &lt;opt&gt;
      &lt;name&gt;value&lt;/name&gt;
    &lt;/opt&gt;</pre>
<p>would parse to this:</p>
<pre>
    <span class="operator">{</span>
      <span class="string">'name'</span> <span class="operator">=&gt;</span> <span class="operator">[</span>
                  <span class="string">'value'</span>
                <span class="operator">]</span>
    <span class="operator">}</span>
</pre>
<p>instead of this (the default):</p>
<pre>
    <span class="operator">{</span>
      <span class="string">'name'</span> <span class="operator">=&gt;</span> <span class="string">'value'</span>
    <span class="operator">}</span>
</pre>
<p>This option is especially useful if the data structure is likely to be written
back out as XML and the default behaviour of rolling single nested elements up
into attributes is not desirable.</p>
<p>If you are using the array folding feature, you should almost certainly enable
this option.  If you do not, single nested elements will not be parsed to
arrays and therefore will not be candidates for folding to a hash.  (Given that
the default value of 'KeyAttr' enables array folding, the default value of this
option should probably also have been enabled too - sorry).</p>
<p>
</p>
<h2><a name="forcearray______names_____in__important">ForceArray =&gt; [ names ] <em># in - important</em></a></h2>
<p>This alternative (and preferred) form of the 'ForceArray' option allows you to
specify a list of element names which should always be forced into an array
representation, rather than the 'all or nothing' approach above.</p>
<p>It is also possible (since version 2.05) to include compiled regular
expressions in the list - any element names which match the pattern will be
forced to arrays.  If the list contains only a single regex, then it is not
necessary to enclose it in an arrayref.  Eg:</p>
<pre>
  ForceArray =&gt; qr/_list$/</pre>
<p>
</p>
<h2><a name="forcecontent____1___in__seldom_used">ForceContent =&gt; 1 <em># in - seldom used</em></a></h2>
<p>When <code>XMLin()</code> parses elements which have text content as well as attributes,
the text content must be represented as a hash value rather than a simple
scalar.  This option allows you to force text content to always parse to
a hash value even when there are no attributes.  So for example:</p>
<pre>
  XMLin('&lt;opt&gt;&lt;x&gt;text1&lt;/x&gt;&lt;y a=&quot;2&quot;&gt;text2&lt;/y&gt;&lt;/opt&gt;', ForceContent =&gt; 1)</pre>
<p>will parse to:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">'x'</span> <span class="operator">=&gt;</span> <span class="operator">{</span>           <span class="string">'content'</span> <span class="operator">=&gt;</span> <span class="string">'text1'</span> <span class="operator">}</span><span class="operator">,</span>
    <span class="string">'y'</span> <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">'a'</span> <span class="operator">=&gt;</span> <span class="number">2</span><span class="operator">,</span> <span class="string">'content'</span> <span class="operator">=&gt;</span> <span class="string">'text2'</span> <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>instead of:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">'x'</span> <span class="operator">=&gt;</span> <span class="string">'text1'</span><span class="operator">,</span>
    <span class="string">'y'</span> <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">'a'</span> <span class="operator">=&gt;</span> <span class="number">2</span><span class="operator">,</span> <span class="string">'content'</span> <span class="operator">=&gt;</span> <span class="string">'text2'</span> <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>
</p>
<h2><a name="grouptags______grouping_tag____grouped_tag_____in_out__handy">GroupTags =&gt; { grouping tag =&gt; grouped tag } <em># in+out - handy</em></a></h2>
<p>You can use this option to eliminate extra levels of indirection in your Perl
data structure.  For example this XML:</p>
<pre>
  &lt;opt&gt;
   &lt;searchpath&gt;
     &lt;dir&gt;/usr/bin&lt;/dir&gt;
     &lt;dir&gt;/usr/local/bin&lt;/dir&gt;
     &lt;dir&gt;/usr/X11/bin&lt;/dir&gt;
   &lt;/searchpath&gt;
 &lt;/opt&gt;</pre>
<p>Would normally be read into a structure like this:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">searchpath</span> <span class="operator">=&gt;</span> <span class="operator">{</span>
                    <span class="string">dir</span> <span class="operator">=&gt;</span> <span class="operator">[</span> <span class="string">'/usr/bin'</span><span class="operator">,</span> <span class="string">'/usr/local/bin'</span><span class="operator">,</span> <span class="string">'/usr/X11/bin'</span> <span class="operator">]</span>
                  <span class="operator">}</span>
  <span class="operator">}</span>
</pre>
<p>But when read in with the appropriate value for 'GroupTags':</p>
<pre>
  <span class="keyword">my</span> <span class="variable">$opt</span> <span class="operator">=</span> <span class="variable">XMLin</span><span class="operator">(</span><span class="variable">$xml</span><span class="operator">,</span> <span class="string">GroupTags</span> <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">searchpath</span> <span class="operator">=&gt;</span> <span class="string">'dir'</span> <span class="operator">}</span><span class="operator">);</span>
</pre>
<p>It will return this simpler structure:</p>
<pre>
  <span class="operator">{</span>
    <span class="string">searchpath</span> <span class="operator">=&gt;</span> <span class="operator">[</span> <span class="string">'/usr/bin'</span><span class="operator">,</span> <span class="string">'/usr/local/bin'</span><span class="operator">,</span> <span class="string">'/usr/X11/bin'</span> <span class="operator">]</span>
  <span class="operator">}</span>
</pre>
<p>The grouping element (<code>&lt;searchpath&gt;</code> in the example) must not contain any
attributes or elements other than the grouped element.</p>
<p>You can specify multiple 'grouping element' to 'grouped element' mappings in
the same hashref.  If this option is combined with <code>KeyAttr</code>, the array
folding will occur first and then the grouped element names will be eliminated.</p>
<p><code>XMLout</code> will also use the grouptag mappings to re-introduce the tags around
the grouped elements.  Beware though that this will occur in all places that
the 'grouping tag' name occurs - you probably don't want to use the same name
for elements as well as attributes.</p>
<p>
</p>
<h2><a name="handler____object_ref___out__sax_only">Handler =&gt; object_ref <em># out - SAX only</em></a></h2>
<p>Use the 'Handler' option to have <code>XMLout()</code> generate SAX events rather than 
returning a string of XML.  For more details see <a href="#sax_support">SAX SUPPORT</a> below.</p>
<p>Note: the current implementation of this option generates a string of XML
and uses a SAX parser to translate it into SAX events.  The normal encoding
rules apply here - your data must be UTF8 encoded unless you specify an 
alternative encoding via the 'XMLDecl' option; and by the time the data reaches
the handler object, it will be in UTF8 form regardless of the encoding you
supply.  A future implementation of this option may generate the events 
directly.</p>