docs/index.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>XmlSimple - XML made easy</title>
    <link type="text/css" rel="stylesheet" href="main.css"/>
  </head>

  <body>
    <div><div id="Header">XmlSimple - XML made easy</div></div>

    <div id="Content">
      <h2>Introduction</h2>
      <p>
      Class <em>XmlSimple</em> offers an easy API to read and write XML.
      It is a Ruby translation of Grant McLean's
      <a href="http://www.cpan.org/modules/by-module/XML/GRANTM/">Perl module XML::Simple</a>.
      Please note, that this tutorial was originally written by Grant
      McLean. I have only converted it to HTML and adjusted it for the
      Ruby version.
      </p>
      <h2>Installation</h2>
      <p>
        XmlSimple is available as a Gem and the easiest way to install
        it is to:
      </p>
<pre>
  gem install xml-simple</pre>
      <p>
      If you do not want to use RubyGem you have to <a
      href="http://rubyforge.org/frs/?group_id=638">download</a>
      <em>XmlSimple</em>. <em>XmlSimple</em> depends on <a
      href="http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML">REXML</a>,
      (version 2.7.1 or higher) so you will have to install it first
      (if you have Ruby 1.8 or higher, REXML will be installed by
      default). After unpacking the distribution run the following
      commands from the main directory:
      </p>
<pre>
  ruby install.rb config
  ruby install.rb setup
  ruby install.rb install</pre>
      <h2>Quick Start</h2>
      <p>
      Say you have a script called <em>foo</em> and a file of configuration options
      called <em>foo.xml</em> containing this:
      </p>
<pre>
  &lt;config logdir="/var/log/foo/" debugfile="/tmp/foo.debug"&gt;
    &lt;server name="sahara" osname="solaris" osversion="2.6"&gt;
      &lt;address&gt;10.0.0.101&lt;/address&gt;
      &lt;address&gt;10.0.1.101&lt;/address&gt;
    &lt;/server&gt;
    &lt;server name="gobi" osname="irix" osversion="6.5"&gt;
      &lt;address&gt;10.0.0.102&lt;/address&gt;
    &lt;/server&gt;
    &lt;server name="kalahari" osname="linux" osversion="2.0.34"&gt;
      &lt;address&gt;10.0.0.103&lt;/address&gt;
      &lt;address&gt;10.0.1.103&lt;/address&gt;
    &lt;/server&gt;
  &lt;/config&gt;</pre>
      <p>The following lines of code in <em>foo</em>:</p>
<pre>
  require 'xmlsimple'
  config = XmlSimple.xml_in('foo.xml', { 'KeyAttr' =&gt; 'name' })</pre>
      <p>
      will 'slurp' the configuration options into the Hash <em>config</em>
      (if no arguments are passed to <em>xml_in</em> the name and location of
      the XML file will be inferred from name and location of the script).
      You can dump out the contents of the Hash using <code>p config</code>,
      which will produce something like this (formatting has been adjusted
      for brevity):
      </p>
<pre>
{
  'logdir'        =&gt; '/var/log/foo/',
  'debugfile'     =&gt; '/tmp/foo.debug',
  'server'        =&gt; {
    'sahara'        =&gt; {
      'osversion'     =&gt; '2.6',
      'osname'        =&gt; 'solaris',
      'address'       =&gt; [ '10.0.0.101', '10.0.1.101' ]
    },
    'gobi'          =&gt; {
      'osversion'     =&gt; '6.5',
      'osname'        =&gt; 'irix',
      'address'       =&gt; [ '10.0.0.102' ]
    },
    'kalahari'      =&gt; {
      'osversion'     =&gt; '2.0.34',
      'osname'        =&gt; 'linux',
      'address'       =&gt; [ '10.0.0.103', '10.0.1.103' ]
    }
  }
}</pre>
      <p>
      Your script could then access the name of the log directory like this:
      </p>
<pre>
  puts config['logdir']</pre>
      <p>
      Similarly, the second address on the server 'kalahari' could be
      referenced as:
      </p>
<pre>
  puts config['server']['kalahari']['address'][1]</pre>
      <p>What could be simpler? (Rhetorical).</p>
      <p>
      For simple requirements, that's really all there is to it. If you want
      to store your XML in a different directory or file, or pass it in as a
      string, you'll need to check out the section on <a href="#options">options</a>.
      If you want to turn off or tweak the array folding feature (that neat
      little transformation that produced <em>config['server'])</em> you'll
      find options for that as well.
      </p>
      <p>
      If you want to generate XML (for example to write a modified version of
      <em>config</em> back out as XML), check out <em>xml_out</em>.
      </p>
      <h2>Description</h2>
      <p>
      The <em>XmlSimple</em> class provides a simple API layer on top of the
      <a href="http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML">REXML</a>
      parser. Additionally, two functions are exported: <em>xml_in</em> and
      <em>xml_out</em>.
      </p>
      <p>
      The simplest approach is to call these two functions directly,
      but an optional object oriented interface (see the section on <a href="#OOInterface">"Optional OO Interface"</a>
      below) allows them to be called as methods of an <em>XmlSimple</em> object.
      </p>
      <h3>xml_in</h3>
      <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 the section on <a href="#examples">examples</a> below, for more
      sample code).
      </p>
      <p>
      <em>xml_in</em> accepts an optional XML specifier followed by a Hash
      containing 'name =&gt; value' option pairs. The XML specifier can be
      a filename, nil, or an IO object.
      </p>
      <h4>A Filename</h4>
      <p>
      If the filename contains no directory components <em>xml_in</em> will look
      for the file in each directory in the searchpath (see the section on
      <a href="#options">options</a> below). For example:
      </p>
<pre>
    ref = XmlSimple.xml_in('/etc/params.xml')</pre>
      <h4>nil</h4>
      <p>
      If there is no XML specifier, <em>xml_in</em> 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 <em>nil</em>:
      </p>
<pre>
    ref = XmlSimple.xml_in(nil, { 'ForceArray' =&gt; false })</pre>
      <h4>A String of XML</h4>
      <p>
      A string containing XML (recognised by the presence of '&lt;' and '&gt;'
      characters) will be parsed directly. For example:
      </p>
<pre>
    ref = XmlSimple.xml_in('&lt;opt username="bob" password="flurp" /&gt;')</pre>
      <h4>An IO object</h4>
      <p>
      An IO object will be read to EOF and its contents parsed. For example:
      </p>
<pre>
    file = File.open('/etc/params.xml')
    ref  = XmlSimple.xml_in(file)</pre>
      <h3>xml_out</h3>
      <p>
      Takes a data structure (generally a Hash) and returns an XML encoding
      of that structure. If the resulting XML is parsed using <em>xml_in</em>, it
      will return a data structure equivalent to the original.
      </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 <em>xml_out</em>. (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>
      <h3>Caveats</h3>
      <p>
      Some care is required in creating data structures which will be passed
      to <em>xml_out</em>. 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 - a facility well
      beyond the scope of <em>XmlSimple</em>.
      </p>
      <p>
      You can use other punctuation characters in hash values (just not in
      hash keys) however <em>XmlSimple</em> does not support dumping binary
      data.
      </p>
      <p>
      If you break these rules, the current implementation of <em>xml_out</em> will
      simply emit non-compliant XML which will be rejected if you try to read
      it back in. (A later version of <em>XmlSimple</em> might take a more
      proactive approach).
      </p>
      <p>
      Note also that although you can nest hashes and arrays to arbitrary
      levels, recursive data structures are not supported and will cause
      <em>xml_out</em> to raise an exception.
      </p>
      <h2><a name="options">Options</a></h2>
      <p>
      <em>IMPORTANT NOTE FOR USERS OF THE PERL VERSION!</em> The default values
      of some options have changed, some options are not supported and I have
      added new options, too:
      </p>
      <ul>
        <li>'ForceArray' is <em>true</em> by default.</li>
        <li>'KeyAttr' defaults to <em>[]</em> and not to <em>['name', 'key', 'id']</em>.</li>
        <li>The SAX parts of XML::Simple are currently not supported.</li>
        <li>Namespaces are currently not supported.</li>
        <li>Currently, there is no 'strict mode'.</li>
        <li>'AnonymousTag' is not available in the current Perl version.</li>
        <li>'Indent' is not available in the current Perl version.</li>
        <li>The Perl version does not support so called blessed references
        and raises an exception ("can't encode value of type"), if one is
        used. The Ruby version supports all object types, because every
        object in Ruby has a <em>to_s</em> method.</li>
      </ul>
      <p>
      <em>XmlSimple</em> supports a number of options. If you find yourself
      repeatedly having to specify the same options, you might like to
      investigate the section on <a href="#OOInterface">"Optional OO Interface"</a>
      below.
      </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>Check out 'ForceArray' because you'll almost certainly want to
        leave it on.</li>
        <li>Make sure you know what the 'KeyAttr' option does and what its
        default value is because it may surprise you otherwise.</li>
      </ul>
      <p>
      Both <em>xml_in</em> and <em>xml_out</em> expect a single argument followed
      by a Hash containing options. So, an option takes the form of a 'name =&gt;
      value' pair. The options listed below are marked with 'in' if they are
      recognised by <em>xml_in</em> and 'out' if they are recognised by <em>xml_out</em>.
      </p>
      <p>
      Each option is also flagged to indicate whether it is:
      </p>
      <ul>
        <li>'important' - don't use the module until you understand this</li>
        <li>'handy' - you can skip this on the first time through</li>
        <li>'advanced' - you can skip this on the second time through</li>
        <li>'seldom used' - you'll probably never use this unless you
        were the person that requested the feature</li>
      </ul>
      <p>The options are listed alphabetically.</p>
      <p>
      <em>Note</em>: Option names are not case sensitive, so you can use the mixed case
      versions shown here. Additionally, you can put underscores between the
      words (e.g. 'key_attr').
      </p>
      <h3>AnonymousTag =&gt; 'tag name' (in + out) (seldom used)</h3>
      <p>
      By default, the tag to declare an anonymous value is 'anon'. Using option
      'AnonymousTag' you can set it to an arbitrary string (that must obey to
      the XML naming rules, of course).
      </p>
      <h3>Cache =&gt; [ cache scheme(s) ] (in) (advanced)</h3>
      <p>
      Because loading the REXML parser module and parsing an XML file can
      consume a significant number of CPU cycles, it is often desirable to
      cache the output of <em>xml_in</em> for later reuse.
      </p>
      <p>
      When parsing from a named file, <em>XmlSimple</em> 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>
      <h4>storable</h4>
      <p>
      Utilises Marshal to read/write a cache file with the same
      name as the XML file but with the extension <em>.stor</em>.
      </p>
      <h4>mem_share</h4>
      <p>
      When a file is first parsed, a copy of the resulting data
      structure is retained in memory in <em>XmlSimple</em>'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 Ruby interpreter (which in the case of
      mod_ruby for example, may be some significant time).
      </p>
      <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>
      <h4>mem_copy</h4>
      <p>
      This scheme works identically to 'mem_share' (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 the Marshal module to perform the copy.
      </p>
      <p>
      <em>Warning!</em> 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>

      <h3>ContentKey =&gt; 'keyname' (in + out) (seldom used)</h3>
      <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>    XmlSimple.xml_in('&lt;opt one="1"&gt;Text&lt;/opt&gt;', { 'ContentKey' =&gt; 'text' })</pre>
      <p>will parse to:</p>
<pre>    { 'one' =&gt; '1', 'text' =&gt; 'Text' }</pre>
      <p>instead of:</p>
<pre>    { 'one' =&gt; '1', 'content' =&gt; 'Text' }</pre>
      <p>
      <em>xml_out</em> will also honour the value of this option when converting
      a hash to XML.
      </p>
      <p>
      You can also prefix your selected key name with a '-' character to
      have <em>xml_in</em> try a little harder to eliminate unnecessary
      'content' keys after array folding. For example:
      </p>
<pre>
  XmlSimple.xml_in(%q(
    &lt;opt&gt;
      &lt;item name="one"&gt;First&lt;item&gt;
      &lt;item name="two"&gt;Second&lt;item&gt;
    &lt;opt&gt;), {
  'KeyAttr'    =&gt; { 'item' =&gt; 'name' },
  'ForceArray' =&gt; [ 'item' ],
  'ContentKey' =&gt; '-content'
})</pre>
      <p>will parse to:</p>
<pre>
{
  'item' =&gt; {
    'one'  =&gt;  'First',
    'two'  =&gt;  'Second'
  }
}</pre>
      <p>rather than this (without the '-'):</p>
<pre>
{
  'item' =&gt; {
    'one'  =&gt; { 'content' =&gt; 'First' },
    'two'  =&gt; { 'content' =&gt; 'Second' }
  }
}</pre>

      <h3>ForceArray =&gt; true | false (in) (IMPORTANT!)</h3>
      <p>
      This option should be set to <em>true</em> to force nested elements to be
      represented as arrays even when there is only one. For example, 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>
{
  'name' =&gt; [ 'value' ]
}</pre>
      <p>instead of this (the default):</p>
<pre>
{
  'name' =&gt; 'value'
}</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.
      </p>
      <p>
      The option is <em>true</em> by default.
      </p>

      <h3>ForceArray =&gt; [ name(s) ] (in) (IMPORTANT!)</h3>
      <p>
      This alternative 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 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 Array. E.g.
      </p>
<pre>
'ForceArray' =&gt; %r(_list$)</pre>

      <h3>ForceContent (in) (seldom used)</h3>
      <p>
      When <em>xml_in</em> 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>
  xml =%q(
    &lt;opt&gt;
      &lt;x&gt;text1&lt;/x&gt;
      &lt;y a="2"&gt;text2&lt;/y&gt;
    &lt;/opt&gt;)
  XmlSimple.xml_in(xml, { 'ForceContent' =&gt; true })</pre>
      <p>will parse to:</p>
<pre>
    {
      'x' =&gt; {             'content' =&gt; 'text1' },
      'y' =&gt; { 'a' =&gt; '2', 'content' =&gt; 'text2' }
    }</pre>
      <p>instead of:</p>
<pre>
    {
      'x' =&gt; 'text1',
      'y' =&gt; { 'a' =&gt; '2', 'content' =&gt; 'text2' }
    }</pre>

      <h3>GroupTags =&gt; { grouping tag =&gt; grouped tag } (in + out) (handy)</h3>
      <p>
      You can use this option to eliminate extra levels of indirection in
      your Ruby data structure. For example this XML:
      </p>
<pre>
  xml = %q(
  &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>
 {
   'searchpath' =&gt; {
     'dir' =&gt; [ '/usr/bin', '/usr/local/bin', '/usr/X11/bin' ]
   }
 }</pre>
      <p>But when read in with the appropriate value for 'GroupTags':</p>
<pre>
    opt = XmlSimple.xml_in(xml, { 'GroupTags' =&gt; { 'searchpath' =&gt; 'dir' })</pre>
      <p>It will return this simpler structure:</p>
<pre>
    {
      'searchpath' =&gt; [ '/usr/bin', '/usr/local/bin', '/usr/X11/bin' ]
    }</pre>
      <p>
      You can specify multiple 'grouping element' to 'grouped element'
      mappings in the same Hash. If this option is combined with
      'KeyAttr', the array folding will occur first and then the grouped
      element names will be eliminated.
      </p>
      <p>
      <em>xml_out</em> 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>

      <h3>Indent =&gt; 'string' (out) (seldom used)</h3>
      <p>
      By default <em>xml_out</em>'s pretty printing mode indents the output
      document using two blanks. 'Indent' allows you to use an arbitrary
      string for indentation.
      </p>
      <p>
      If the 'NoIndent' option is set, 'Indent' will be ignored.
      </p>

      <h3>KeepRoot =&gt; true | false (in + out) (handy)</h3>
      <p>
      In its attempt to return a data structure free of superfluous detail
      and unnecessary levels of indirection, <em>xml_in</em> normally discards the
      root element name. Setting the 'KeepRoot' option to <em>true</em> will
      cause the root element name to be retained. So after executing this
      code:
      </p>
<pre>
    config = XmlSimple.xml_in('&lt;config tempdir="/tmp" /&gt;', { 'KeepRoot' =&gt; true })</pre>
      <p>
      you'll be able to reference the tempdir as <em>config['config']['tempdir']</em>
      instead of the default <em>config['tempdir']</em>.
      </p>
      <p>
      Similarly, setting the 'KeepRoot' option to <em>true</em> will tell
      <em>xml_out</em> that the data structure already contains a root element name
      and it is not necessary to add another.
      </p>

      <h3>KeyAttr =&gt; [ list ] (in + out) (IMPORTANT!)</h3>
      <p>
      This option controls the 'array folding' feature which translates
      nested elements from an array to a hash. For example, this XML:
      </p>
    <pre>
        &lt;opt&gt;
          &lt;user login="grep" fullname="Gary R Epstein" /&gt;
          &lt;user login="stty" fullname="Simon T Tyson" /&gt;
        &lt;/opt&gt;</pre>
      <p>would, by default, parse to this:</p>
<pre>
{
  'user' =&gt; [
     {
       'login'    =&gt; 'grep',
       'fullname' =&gt; 'Gary R Epstein'
     },
     {
       'login'    =&gt; 'stty',
       'fullname' =&gt; 'Simon T Tyson'
     }
   ]
}</pre>
      <p>
      If the option 'KeyAttr =&gt; "login"' were used to specify that
      the 'login' attribute is a key, the same XML would parse to:
      </p>
<pre>
{
  'user' =&gt; {
    'stty' =&gt; {
      'fullname' =&gt; 'Simon T Tyson'
    },
    'grep' =&gt; {
      'fullname' =&gt; 'Gary R Epstein'
    }
  }
}</pre>
      <p>
      The key attribute names should be supplied in an array if there is
      more than one. <em>xml_in</em> will attempt to match attribute names
      in the order supplied. <em>xml_out</em> will use the first attribute
      name supplied when 'unfolding' a hash into an array.
      </p>
      <p>
      <em>Note:</em> the 'KeyAttr' option controls the folding of arrays. By
      default a single nested element will be rolled up into a scalar rather
      than an array and therefore will not be folded. Use the 'ForceArray'
      option to force nested elements to be parsed into arrays and
      therefore candidates for folding into hashes.
      </p>
      <p>
      The default value for 'KeyAttr' is <em>[]</em>, i.e. the array folding feature
      is disabled.
      </p>

      <h3>KeyAttr =&gt; { list } (in + out) (IMPORTANT!)</h3>
      <p>
      This alternative method of specifiying the key attributes allows
      more fine grained control over which elements are folded and on
      which attributes. For example the option 'KeyAttr =&gt; { 'package' =&gt;
      'id' } will cause any package elements to be folded on the 'id'
      attribute. No other elements which have an 'id' attribute will be
      folded at all.
      </p>
      <p>
      <em>Note:</em> <em>xml_in</em> will generate a warning if this syntax is
      used and an element which does not have the specified key attribute is
      encountered (e.g.: a 'package' element without an 'id' attribute, to
      use the example above).
      </p>
      <p>
      Two further variations are made possible by prefixing a '+' or a '-'
      character to the attribute name:
      </p>
      <p>
      The option
      </p>
<pre>
  'KeyAttr' =&gt; { 'user' =&gt; "+login" }'</pre>
      <p>
      will cause this XML:
      </p>
<pre>
&lt;opt&gt;
  &lt;user login="grep" fullname="Gary R Epstein" /&gt;
  &lt;user login="stty" fullname="Simon T Tyson" /&gt;
&lt;/opt&gt;</pre>
      <p>
      to parse to this data structure:
      </p>
<pre>
{
  'user' =&gt; {
    'stty' =&gt; {
      'fullname' =&gt; 'Simon T Tyson',
      'login'    =&gt; 'stty'
    },
    'grep' =&gt; {
      'fullname' =&gt; 'Gary R Epstein',
      'login'    =&gt; 'grep'
    }
  }
}</pre>
      <p>
      The '+' indicates that the value of the key attribute should be
      copied rather than moved to the folded hash key.
      </p>
      <p>
      A '-' prefix would produce this result:
      </p>
<pre>
{
  'user' =&gt; {
    'stty' =&gt; {
      'fullname' =&gt; 'Simon T Tyson',
      '-login'   =&gt; 'stty'
    },
    'grep' =&gt; {
      'fullname' =&gt; 'Gary R Epstein',
      '-login'   =&gt; 'grep'
    }
  }
}</pre>
      <p>
      As described earlier, <em>xml_out</em> will ignore hash keys starting with a
      '-'.
      </p>

      <h3>AttrPrefix =&gt; true | false (in + out) (handy)</h3>
      <p>
      XmlSimple treats attributes and elements equally and there is no way to
      determine, if a certain hash key has been derived from an element name
      or from an attribute name. Sometimes you need this information and
      that's when you use the <em>AttrPrefix</em> option:
      </p>
<pre>
xml_str = &lt;&lt;XML_STR
&lt;Customer id="12253"&gt;
  &lt;first_name&gt;Joe&lt;/first_name&gt;
  &lt;last_name&gt;Joe&lt;/last_name&gt;
  &lt;Address type="home"&gt;
    &lt;line1&gt;211 Over There&lt;/line1&gt;
    &lt;city&gt;Jacksonville&lt;/city&gt;
    &lt;state&gt;FL&lt;/state&gt;
    &lt;zip_code&gt;11234&lt;/zip_code&gt;
  &lt;/Address&gt;
  &lt;Address type="postal"&gt;
    &lt;line1&gt;3535 Head Office&lt;/line1&gt;
    &lt;city&gt;Jacksonville&lt;/city&gt;
    &lt;state&gt;FL&lt;/state&gt;
    &lt;zip_code&gt;11234&lt;/zip_code&gt;
  &lt;/Address&gt;
&lt;/Customer&gt;
XML_STR

result = XmlSimple.xml_in xml_str, { 'ForceArray' =&gt; false, 'AttrPrefix' =&gt; true }
p result
</pre>
      <p>produces:</p>
<pre>
{
  "@id" =&gt; "12253",
  "first_name" =&gt; "Joe",
  "Address" =&gt; [
    {
      "city" =&gt; "Jacksonville",
      "line1" =&gt; "211 Over There",
      "zip_code" =&gt; "11234",
      "@type" =&gt; "home",
      "state" =&gt; "FL"
    },
    {
      "city" =&gt; "Jacksonville",
      "line1" =&gt; "3535 Head Office",
      "zip_code" =&gt; "11234",
      "@type" =&gt; "postal",
      "state" =&gt; "FL"
    }
  ],
  "last_name" =&gt; "Joe"
}
</pre>
      <p>
      As you can see all hash keys that have been derived from attributes are
      prefixed by an @ character, so now you know if they have been elements
      or attributes before. Of course, <em>xml_out</em> knows how to
      correctly transform hash keys prefixed by an @ character, too:
      </p>
<pre>
    doc = REXML::Document.new XmlSimple.xml_out(result, 'AttrPrefix' =&gt; true)
    d = ''
    doc.write(d)
    puts d
</pre>
     <p>produces:</p>
<pre>
&lt;opt id="12253"&gt;
  &lt;first_name&gt;Joe&lt;/first_name&gt;
  &lt;last_name&gt;Joe&lt;/last_name&gt;
  &lt;Address type="home"&gt;
    &lt;line1&gt;211 Over There&lt;/line1&gt;
    &lt;city&gt;Jacksonville&lt;/city&gt;
    &lt;state&gt;FL&lt;/state&gt;
    &lt;zip_code&gt;11234&lt;/zip_code&gt;
  &lt;/Address&gt;
  &lt;Address type="postal"&gt;
    &lt;line1&gt;3535 Head Office&lt;/line1&gt;
    &lt;city&gt;Jacksonville&lt;/city&gt;
    &lt;state&gt;FL&lt;/state&gt;
    &lt;zip_code&gt;11234&lt;/zip_code&gt;
  &lt;/Address&gt;
&lt;/opt&gt;
</pre>

      <h3>NoAttr =&gt; true | false (in + out) (handy)</h3>
      <p>
      When used with <em>xml_out</em>, the generated XML will contain no attributes.
      All hash key/values will be represented as nested elements instead.
      </p>
      <p>
      When used with <em>xml_in</em>, any attributes in the XML will be ignored.
      </p>

      <h3>NormaliseSpace =&gt; 0 | 1 | 2 (in) (handy)</h3>
      <p>
      This option controls how whitespace in text content is handled.
      Recognised values for the option are:
      </p>
      <ul>
        <li>0 - The default behaviour is for whitespace to be passed through
        unaltered (except of course for the normalisation of whitespace
        in attribute values which is mandated by the XML recommendation).
        </li>
        <li>1 - Whitespace is normalised in any value used as a hash key
        (normalising means removing leading and trailing whitespace and
        collapsing sequences of whitespace characters to a single space).
        </li>
        <li>2 - Whitespace is normalised in all text content.</li>
      </ul>
      <p>
      Note: you can spell this option with a 'z' if that is more natural
      for you.
      </p>

      <h3>NoEscape =&gt; true | false (out) (seldom used)</h3>
      <p>
      By default, <em>xml_out</em> will translate the characters &lt;,
      &gt;, &amp;, &apos;, and " to '&amp;lt;', '&amp;gt;',
      '&amp;amp', '&amp;apos', and '&amp;quot' respectively. Use this
      option to suppress escaping (presumably because you've already escaped
      the data in some more sophisticated manner).
      </p>

      <h3>NoIndent =&gt; true | false (out) (seldom used)</h3>
      <p>
      Set this option to <em>true</em> to disable <em>xml_out</em>'s default 'pretty
      printing' mode. With this option enabled, the XML output will all be
      on one line (unless there are newlines in the data) - this may be
      easier for downstream processing.
      </p>

      <h3>KeyToSymbol =&gt; true | false (in) (handy)</h3>
      <p>
      If set to <em>true</em> (default is <em>false</em>) all keys are turned into
      symbols, i.e. the following snippet
      </p>
<pre>
  doc = &lt;&lt;-DOC
  &lt;atts&gt;
    &lt;x&gt;Hello&lt;/x&gt;
    &lt;y&gt;world&lt;/y&gt;
    &lt;z&gt;
      &lt;inner&gt;Inner&lt;/inner&gt;
    &lt;/z&gt;
  &lt;/atts&gt;
  DOC
  p XmlSimple.xml_in(doc, 'KeyToSymbol' =&gt; true)
</pre>
      <p>produces:</p>
<pre>
  {
    :x =&gt; ["Hello"],
    :y =&gt; ["World"],
    :z =&gt; [ { :inner =&gt; ["Inner"] } ]
  }
</pre>

      <h3>AttrToSymbol =&gt; true | false (in) (handy)</h3>
      <p>
      If set to <em>true</em> (default is <em>false</em>) all keys are turned into
      symbols, i.e. the following snippet
      </p>
<pre>
  doc = &lt;&lt;-DOC
  &lt;atts&gt;
    &lt;msg text=&quot;Hello, world!&quot; /&gt;
  &lt;/atts&gt;
  DOC
  p XmlSimple.xml_in(doc, 'AttrToSymbol' =&gt; true)
</pre>
      <p>produces:</p>
<pre>
  {
    "msg" =&gt; [ { :text =&gt; "Hello, world!" } ]
  }
</pre>

      <h3>OutputFile =&gt; &lt;file specifier&gt; (out) (handy)</h3>
      <p>
      The default behavior of <em>xml_out</em> 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. Alternatively, you can
      supply an object derived from IO instead of a filename.
      </p>

      <h3>RootName =&gt; 'string' (out) (handy)</h3>
      <p>
      By default, when <em>xml_out</em> generates XML, the root element will be
      named 'opt'. This option allows you to specify an alternative name.
      </p>
      <p>
      Specifying either <em>nil</em> 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 <em>xml_in</em>. Nevertheless, the option has been found
      to be useful in certain circumstances.
      </p>

      <h3>SearchPath =&gt; [ list ] (in) (handy)</h3>
      <p>
      Where the XML is being read from a file, and no path to the file is
      specified, this attribute allows you to specify which directories
      should be searched.
      </p>
      <p>
      If the first parameter to <em>xml_in</em> 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>
      <em>Note:</em> the current directory ('.') is not searched unless it is the
      directory containing the script.
      </p>
      <h3>SuppressEmpty =&gt; true | '' | nil (in + out) (handy)</h3>
      <p>
      This option controls what <em>xml_in</em> should do with empty elements
      (no attributes and no content). The default behaviour is to represent
      them as empty hashes. Setting this option to <em>true</em> will cause
      empty elements to be skipped altogether. Setting the option to <em>nil</em>
      or the empty string will cause empty elements to be represented as <em>nil</em>
      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>
      <h3>Variables =&gt; { name =&gt; value } (in) (handy)</h3>
      <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 <em>xml_out</em>).
      </p>
      <p>
      A 'variable' is any text of the form "${name}" which occurs in an
      attribute value or in the text content of an element. If 'name'
      matches a key in the supplied Hash, "${name}" will be replaced
      with the corresponding value from the Hash. If no matching key is
      found, the variable will not be replaced.
      </p>
      <h3>VarAttr =&gt; 'attr_name' (in) (handy)</h3>
      <p>
      In addition to the variables defined using 'Variables', 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 'VarAttr' 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 'Variables' option. For example:
      </p>
<pre>
    XmlSimple.xml_in(%q(&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;), {
     'VarAttr' =&gt; 'name', 'ContentKey' =&gt; '-content'
     })</pre>
      <p>produces the following data structure:</p>
<pre>
{
  'dir' =&gt; {
           'prefix'      =&gt; '/usr/local/apache',
           'exec_prefix' =&gt; '/usr/local/apache',
           'bindir'      =&gt; '/usr/local/apache/bin',
      }
}</pre>
      <h3>XmlDeclaration =&gt; <em>true</em> | 'string' (out) (handy)</h3>
      <p>
      If you want the output from <em>xml_out</em> to start with the optional
      XML declaration, simply set the option to <em>true</em>. The default XML
      declaration is:
      </p>
<pre>
    &lt;?xml version='1.0' standalone='yes'?&gt;</pre>
        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.
      <h3>conversions =&gt; { regex =&gt; lambda } (in) (handy)</h3>
      <p>
      When importing XML documents it's often necessary to filter or transform certain elements or attributes.
      The <em>conversions</em> option helps you to do this. It expects a Hash object where the
      keys are regular expressions identifying element or attribute names. The values are lambda functions
      that will be applied to the matching elements.
      </p>
      <p>
        Let's say we have a file named status.xml containing the following document:
      </p>
<pre>
&lt;result&gt;
  &lt;status&gt;OK&lt;/status&gt;
  &lt;total&gt;10&lt;/total&gt;
  &lt;failed&gt;2&lt;/failed&gt;
&lt;/result&gt;
</pre>
      <p>
        The following statement
      </p>
<pre>
  conversions = {
    /^total|failed$/ =&gt; lambda { |v| v.to_i },
    /^status$/       =&gt; lambda { |v| v.downcase }
  }

  p XmlSimple.xml_in(
    'status.xml',
    :conversions =&gt; conversions,
    :forcearray  =&gt; false
  )
</pre>
      <p>
        produces the following output:
      </p>
<pre>
{
  'status' =&gt; 'ok',
  'total'  =&gt; 10,
  'failed' =&gt; 2
}
</pre>
      <h2><a name="OOInterface">Optional OO Interface</a></h2>
      <p>
      The procedural interface is both simple and convenient, but if you have
      to define a set of default values which should be used on all subsequent
      calls to <em>xml_in</em> or <em>xml_out</em>, you might prefer to
      use the object oriented (OO) interface.
      </p>
      <p>
      The default values for the options described above are unlikely to suit
      everyone. The OO interface allows you to effectively override
      <em>XmlSimple</em>'s defaults with your preferred values. It works like this:
      </p>
      <p>
      First create an <em>XmlSimple</em> parser object with your preferred
      defaults:
      </p>
<pre>
    xs = XmlSimple.new({ 'ForceArray' =&gt; false, 'KeepRoot' =&gt; true)</pre>
      <p>
      then call <em>xml_in</em> or <em>xml_out</em> as a method of that object:
      </p>
<pre>
    ref = xs.xml_in(xml)
    xml = xs.xml_out(ref)</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>
      <h2>Error Handling</h2>
      <p>
      The XML standard is very clear on the issue of non-compliant documents.
      An error in parsing any single element (for example a missing end tag)
      must cause the whole document to be rejected. <em>XmlSimple</em> will
      raise an appropriate exception if it encounters a parsing error.
      </p>
      <h2><a name="examples">Examples</a></h2>
      <p>
      When <em>xml_in</em> reads the following very simple piece of XML:
      </p>
<pre>
    &lt;opt username="testuser" password="frodo"&gt;&lt;/opt&gt;</pre>
      <p>
      it returns the following data structure:
      </p>
<pre>
    {
      'username' =&gt; 'testuser',
      'password' =&gt; 'frodo'
    }</pre>
      <p>
      The identical result could have been produced with this alternative XML:
      </p>
<pre>
    &lt;opt username="testuser" password="frodo" /&gt;</pre>
      <p>
      Or this (although see 'ForceArray' option for variations):
      </p>
<pre>
    &lt;opt&gt;
      &lt;username&gt;testuser&lt;/username&gt;
      &lt;password&gt;frodo&lt;/password&gt;
    &lt;/opt&gt;</pre>
      <p>
      Repeated nested elements are represented as anonymous arrays:
      </p>
<pre>
    &lt;opt&gt;
      &lt;person firstname="Joe" lastname="Smith"&gt;
        &lt;email&gt;joe@smith.com&lt;/email&gt;
        &lt;email&gt;jsmith@yahoo.com&lt;/email&gt;
      &lt;/person&gt;
      &lt;person firstname="Bob" lastname="Smith"&gt;
        &lt;email&gt;bob@smith.com&lt;/email&gt;
      &lt;/person&gt;
    &lt;/opt&gt;

    {
      'person' =&gt; [
        {
          'email' =&gt; [
            'joe@smith.com',
            'jsmith@yahoo.com'
          ],
          'firstname' =&gt; 'Joe',
          'lastname' =&gt; 'Smith'
        },
        {
          'email' =&gt; ['bob@smith.com'],
          'firstname' =&gt; 'Bob',
          'lastname' =&gt; 'Smith'
        }
      ]
    }</pre>
      <p>
      Nested elements with a recognised key attribute are transformed (folded)
      from an array into a hash keyed on the value of that attribute, i.e.
      calling <em>xml_in</em> with the 'KeyAttr' set to <em>[key]</em> will
      transform
      </p>
<pre>
    &lt;opt&gt;
      &lt;person key="jsmith" firstname="Joe" lastname="Smith" /&gt;
      &lt;person key="tsmith" firstname="Tom" lastname="Smith" /&gt;
      &lt;person key="jbloggs" firstname="Joe" lastname="Bloggs" /&gt;
    &lt;/opt&gt;</pre>
      <p>into</p>
<pre>
    {
      'person' =&gt; {
        'jbloggs' =&gt; {
          'firstname' =&gt; 'Joe',
          'lastname' =&gt; 'Bloggs'
        },
        'tsmith' =&gt; {
          'firstname' =&gt; 'Tom',
          'lastname' =&gt; 'Smith'
        },
        'jsmith' =&gt; {
          'firstname' =&gt; 'Joe',
          'lastname' =&gt; 'Smith'
        }
      }
    }</pre>
      <p>
      The &lt;anon&gt; tag can be used to form anonymous arrays:
      </p>
<pre>
    &lt;opt&gt;
      &lt;head&gt;&lt;anon&gt;Col 1&lt;/anon&gt;&lt;anon&gt;Col 2&lt;/anon&gt;&lt;anon&gt;Col 3&lt;/anon&gt;&lt;/head&gt;
      &lt;data&gt;&lt;anon&gt;R1C1&lt;/anon&gt;&lt;anon&gt;R1C2&lt;/anon&gt;&lt;anon&gt;R1C3&lt;/anon&gt;&lt;/data&gt;
      &lt;data&gt;&lt;anon&gt;R2C1&lt;/anon&gt;&lt;anon&gt;R2C2&lt;/anon&gt;&lt;anon&gt;R2C3&lt;/anon&gt;&lt;/data&gt;
      &lt;data&gt;&lt;anon&gt;R3C1&lt;/anon&gt;&lt;anon&gt;R3C2&lt;/anon&gt;&lt;anon&gt;R3C3&lt;/anon&gt;&lt;/data&gt;
    &lt;/opt&gt;

    {
      'head' =&gt; [
        [ 'Col 1', 'Col 2', 'Col 3' ]
      ],
      'data' =&gt; [
        [ 'R1C1', 'R1C2', 'R1C3' ],
        [ 'R2C1', 'R2C2', 'R2C3' ],
        [ 'R3C1', 'R3C2', 'R3C3' ]
      ]
    }</pre>
      <p>
      Anonymous arrays can be nested to arbirtrary levels and as a special
      case, if the surrounding tags for an XML document contain only an
      anonymous array the array will be returned directly rather than the
      usual hash:
      </p>
<pre>
    &lt;opt&gt;
      &lt;anon&gt;&lt;anon&gt;Col 1&lt;/anon&gt;&lt;anon&gt;Col 2&lt;/anon&gt;&lt;/anon&gt;
      &lt;anon&gt;&lt;anon&gt;R1C1&lt;/anon&gt;&lt;anon&gt;R1C2&lt;/anon&gt;&lt;/anon&gt;
      &lt;anon&gt;&lt;anon&gt;R2C1&lt;/anon&gt;&lt;anon&gt;R2C2&lt;/anon&gt;&lt;/anon&gt;
    &lt;/opt&gt;

    [
      [ 'Col 1', 'Col 2' ],
      [ 'R1C1', 'R1C2' ],
      [ 'R2C1', 'R2C2' ]
    ]</pre>
      <p>
      Elements which only contain text content will simply be represented as a
      scalar. Where an element has both attributes and text content, the
      element will be represented as a hash with the text content in the
      'content' key:
      </p>
<pre>
    &lt;opt&gt;
      &lt;one&gt;first&lt;/one&gt;
      &lt;two attr="value"&gt;second&lt;/two&gt;
    &lt;/opt&gt;

    {
      'one' =&gt; 'first',
      'two' =&gt; { 'attr' =&gt; 'value', 'content' =&gt; 'second' }
    }</pre>
      <p>
      Mixed content (elements which contain both text content and nested
      elements) will be not be represented in a useful way - element order and
      significant whitespace will be lost. If you need to work with mixed
      content, then <em>XmlSimple</em> is not the right tool for your job - check
      out the next section.
      </p>
      <h2><a name="further">Where to from here?</a></h2>
      <p>
      <em>XmlSimple</em> is by nature very simple.
      </p>
      <ul>
        <li>The parsing process liberally disposes of 'surplus' whitespace -
        some applications will be sensitive to this.</li>
        <li>Slurping data into a hash will implicitly discard information about
        attribute order. Normally this would not be a problem because any items
        for which order is important would typically be encoded as elements
        rather than attributes. However <em>XmlSimple</em>'s aggressive slurping and
        folding algorithms can defeat even these techniques.</li>
        <li>The API offers little control over the output of <em>xml_out</em>. In
        particular, it is not especially likely that feeding the output from
        <em>xml_in</em> into <em>xml_out</em> will reproduce the original XML (although
        passing the output from <em>xml_out</em> into <em>xml_in</em> should reproduce
        the original data structure).</li>
        <li><em>xml_out</em> cannot produce well formed HTML unless you feed it with
        care - hash keys must conform to XML element naming rules and
        <em>nil</em> values should be avoided.</li>
        <li><em>xml_out</em> does not currently support encodings (although it shouldn't
        stand in your way if you feed it encoded data).</li>
        <li>If you're attempting to get the output from <em>xml_out</em> to conform to
        a specific DTD, you're almost certainly using the wrong tool for the job.</li>
      </ul>
      <p>
      If any of these points are a problem for you, then <em>XmlSimple</em> is
      probably not the right class for your application.
      </p>
      <h2>FAQ</h2>
      <div>
    Question: if I include XmlSimple in a rails app and run for example
    'rake' in the root of the app, I always get the following warnings:

    <pre>
  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:275:
  warning: already initialized constant KNOWN_OPTIONS

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:280:
  warning: already initialized constant DEF_KEY_ATTRIBUTES

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:281:
  warning: already initialized constant DEF_ROOT_NAME

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:282:
  warning: already initialized constant DEF_CONTENT_KEY

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:283:
  warning: already initialized constant DEF_XML_DECLARATION

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:284:
  warning: already initialized constant DEF_ANONYMOUS_TAG

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:285:
  warning: already initialized constant DEF_FORCE_ARRAY

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:286:
  warning: already initialized constant DEF_INDENTATION

  /usr/local/lib/ruby/gems/1.8/gems/xml-simple-1.0.10/lib/xmlsimple.rb:287:
  warning: already initialized constant DEF_KEY_TO_SYMBOL</pre>
    </div>

      <div>
    <p>Answer: The reason for this is, that you're using XmlSimple explicitly in a rails app. XmlSimple is part of rails (you can find it in ./actionpack-1.12.5/lib/action_controller/vendor/xml_simple.rb). Unfortunately, the library is named "xml_simple.rb" and not "xmlsimple.rb". Ruby's "require" prevents you from loading a library two times and it does so by checking if a file name occurs more than once. In your case somewhere in the rails framework "require 'xml_simple'" is performed and you run "require 'xmlsimple'" afterwards. Hence, the library is loaded twice and all constants are redefined.</p>
    <p>A solution is to only require XmlSimple unless XmlSimple has not been defined already.</p>
    </div>
      <h2>Acknowledgements</h2>
      <p>
      A big "Thank you!" goes to
      </p>
      <ul>
        <li>Grant McLean for Perl's <a href="http://www.cpan.org/modules/by-module/XML/GRANTM/">XML::Simple</a></li>
        <li>Yukihiro Matsumoto for Ruby.</li>
        <li>Sean Russell for REXML.</li>
        <li>Dave Thomas for Rdoc.</li>
        <li>Nathaniel Talbott for Test::Unit.</li>
        <li>Minero Aoki for his setup package.</li>
      </ul>
      <h2>Contact</h2>
      <p>
      If you have any suggestions or want to report bugs, please
      <a href='mailto:contact@maik-schmidt.de'>contact</a> me.
      </p>
    </div>
  </body>
</html>

<!--
vim:tw=0:sw=2
Copyright 2003-2009 by Maik Schmidt.
-->