XmlSimple - XML made easy

  gem install xml-simple

  <config logdir="/var/log/foo/" debugfile="/tmp/foo.debug">
    <server name="sahara" osname="solaris" osversion="2.6">
      <address>10.0.0.101</address>
      <address>10.0.1.101</address>
    </server>
    <server name="gobi" osname="irix" osversion="6.5">
      <address>10.0.0.102</address>
    </server>
    <server name="kalahari" osname="linux" osversion="2.0.34">
      <address>10.0.0.103</address>
      <address>10.0.1.103</address>
    </server>
  </config>

  require 'xmlsimple'
  config = XmlSimple.xml_in('foo.xml', { 'KeyAttr' => 'name' })

{
  'logdir'        => '/var/log/foo/',
  'debugfile'     => '/tmp/foo.debug',
  'server'        => {
    'sahara'        => {
      'osversion'     => '2.6',
      'osname'        => 'solaris',
      'address'       => [ '10.0.0.101', '10.0.1.101' ]
    },
    'gobi'          => {
      'osversion'     => '6.5',
      'osname'        => 'irix',
      'address'       => [ '10.0.0.102' ]
    },
    'kalahari'      => {
      'osversion'     => '2.0.34',
      'osname'        => 'linux',
      'address'       => [ '10.0.0.103', '10.0.1.103' ]
    }
  }
}

  puts config['logdir']

  puts config['server']['kalahari']['address'][1]

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 examples below, for more sample code).

xml_in accepts an optional XML specifier followed by a Hash containing 'name ⇒ value' option pairs. The XML specifier can be a filename, nil, or an IO object.

Takes a data structure (generally a Hash) and returns an XML encoding of that structure. If the resulting XML is parsed using xml_in, it will return a data structure equivalent to the original.

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 xml_out. (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).

Some care is required in creating data structures which will be passed to xml_out. 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:

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 _XmlSimple.

You can use other punctuation characters in hash values (just not in hash keys) however XmlSimple does not support dumping binary data.

If you break these rules, the current implementation of xml_out will simply emit non-compliant XML which will be rejected if you try to read it back in. (A later version of XmlSimple might take a more proactive approach).

Note also that although you can nest hashes and arrays to arbitrary levels, recursive data structures are not supported and will cause xml_out to raise an exception.

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).

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 xml_in for later reuse.

When parsing from a named file, XmlSimple 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:

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:

will parse to:

instead of:

xml_out will also honour the value of this option when converting a hash to XML.

You can also prefix your selected key name with a '-' character to have xml_in try a little harder to eliminate unnecessary 'content' keys after array folding. For example:

will parse to:

rather than this (without the '-'):

This option should be set to true to force nested elements to be represented as arrays even when there is only one. For example, with 'ForceArray' enabled, this XML:

would parse to this:

instead of this (the default):

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.

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.

The option is true by default.

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.

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. For example,

When xml_in 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:

will parse to:

instead of:

You can use this option to eliminate extra levels of indirection in your Ruby data structure. For example this XML:

Would normally be read into a structure like this:

But when read in with the appropriate value for 'GroupTags':

It will return this simpler structure:

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.

xml_out 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.

By default, xml_out's pretty printing mode indents the output document using two blanks. 'Indent' allows you to use an arbitrary string for indentation.

If the 'NoIndent' option is set, 'Indent' will be ignored.

In its attempt to return a data structure free of superfluous detail and unnecessary levels of indirection, xml_in normally discards the root element name. Setting the 'KeepRoot' option to true will cause the root element name to be retained. So after executing this code:

you’ll be able to reference the tempdir as config['config']['tempdir'] instead of the default config['tempdir'].

Similarly, setting the 'KeepRoot' option to true will tell xml_out that the data structure already contains a root element name and it is not necessary to add another.

This option controls the 'array folding' feature which translates nested elements from an array to a hash. For example, this XML:

would, by default, parse to this:

If the option 'KeyAttr ⇒ "login"' were used to specify that the 'login' attribute is a key, the same XML would parse to:

The key attribute names should be supplied in an array if there is more than one. xml_in will attempt to match attribute names in the order supplied. xml_out will use the first attribute name supplied when 'unfolding' a hash into an array.

Note: 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.

The default value for 'KeyAttr' is [], that is, the array folding feature is disabled.

This alternative method of specifying the key attributes allows more fine grained control over which elements are folded and on which attributes. For example the option 'KeyAttr ⇒ { 'package' ⇒ '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.

Note: xml_in will generate a warning if this syntax is used and an element which does not have the specified key attribute is encountered (for example: a 'package' element without an 'id' attribute, to use the example above).

Two further variations are made possible by prefixing a '+' or a '-' character to the attribute name:

The option

will cause this XML:

to parse to this data structure:

The '+' indicates that the value of the key attribute should be copied rather than moved to the folded hash key.

A '-' prefix would produce this result:

As described earlier, xml_out will ignore hash keys starting with a '-'.

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 AttrPrefix option:

produces:

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, xml_out knows how to correctly transform hash keys prefixed by an @ character, too:

produces:

When used with xml_out, the generated XML will contain no attributes. All hash key/values will be represented as nested elements instead.

When used with xml_in, any attributes in the XML will be ignored.

This option controls how whitespace in text content is handled. Recognised values for the option are:

• 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).

• 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).

• 2 - Whitespace is normalised in all text content.

Note: you can spell this option with a 'z' if that is more natural for you.

By default, xml_out will translate the characters <, >, &, ', and " to '<', '>', '&amp', '&apos', and '&quot' respectively. Use this option to suppress escaping (presumably because you’ve already escaped the data in some more sophisticated manner).

Set this option to true to disable xml_out'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.

If set to true (default is false) all keys are turned into symbols, that is, the following snippet

produces:

If set to true (default is false) all keys are turned into symbols, that is, the following snippet

produces:

The default behavior of xml_out 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.

By default, when xml_out generates XML, the root element will be named 'opt'. This option allows you to specify an alternative name.

Specifying either nil 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 xml_in. Nevertheless, the option has been found to be useful in certain circumstances.

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.

If the first parameter to xml_in is undefined, the default searchpath will contain only the directory in which the script itself is located. Otherwise the default searchpath will be empty.

Note: the current directory ('.') is not searched unless it is the directory containing the script.

If set, xml_out will use self-closing tags for empty elements. For example:

instead of

This option controls what xml_in should do with empty elements (no attributes and no content). The default behaviour is to represent them as empty hashes. Setting this option to true will cause empty elements to be skipped altogether. Setting the option to nil or the empty string will cause empty elements to be represented as nil 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.

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 xml_out).

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.

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:

produces the following data structure:

If you want the output from xml_out to start with the optional XML declaration, simply set the option to true. The default XML declaration is:

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.

When importing XML documents it’s often necessary to filter or transform certain elements or attributes. The conversions 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.

Let’s say we have a file named status.xml containing the following document:

The following statement

produces the following output:

    xs = XmlSimple.new({ 'ForceArray' => false, 'KeepRoot' => true)

    ref = xs.xml_in(xml)
    xml = xs.xml_out(ref)

    <opt username="testuser" password="frodo"></opt>

    {
      'username' => 'testuser',
      'password' => 'frodo'
    }

    <opt username="testuser" password="frodo" />

    <opt>
      <username>testuser</username>
      <password>frodo</password>
    </opt>

    <opt>
      <person firstname="Joe" lastname="Smith">
        <email>joe@smith.com</email>
        <email>jsmith@yahoo.com</email>
      </person>
      <person firstname="Bob" lastname="Smith">
        <email>bob@smith.com</email>
      </person>
    </opt>

    {
      'person' => [
        {
          'email' => [
            'joe@smith.com',
            'jsmith@yahoo.com'
          ],
          'firstname' => 'Joe',
          'lastname' => 'Smith'
        },
        {
          'email' => ['bob@smith.com'],
          'firstname' => 'Bob',
          'lastname' => 'Smith'
        }
      ]
    }

    <opt>
      <person key="jsmith" firstname="Joe" lastname="Smith" />
      <person key="tsmith" firstname="Tom" lastname="Smith" />
      <person key="jbloggs" firstname="Joe" lastname="Bloggs" />
    </opt>

    {
      'person' => {
        'jbloggs' => {
          'firstname' => 'Joe',
          'lastname' => 'Bloggs'
        },
        'tsmith' => {
          'firstname' => 'Tom',
          'lastname' => 'Smith'
        },
        'jsmith' => {
          'firstname' => 'Joe',
          'lastname' => 'Smith'
        }
      }
    }

    <opt>
      <head><anon>Col 1</anon><anon>Col 2</anon><anon>Col 3</anon></head>
      <data><anon>R1C1</anon><anon>R1C2</anon><anon>R1C3</anon></data>
      <data><anon>R2C1</anon><anon>R2C2</anon><anon>R2C3</anon></data>
      <data><anon>R3C1</anon><anon>R3C2</anon><anon>R3C3</anon></data>
    </opt>

    {
      'head' => [
        [ 'Col 1', 'Col 2', 'Col 3' ]
      ],
      'data' => [
        [ 'R1C1', 'R1C2', 'R1C3' ],
        [ 'R2C1', 'R2C2', 'R2C3' ],
        [ 'R3C1', 'R3C2', 'R3C3' ]
      ]
    }

    <opt>
      <anon><anon>Col 1</anon><anon>Col 2</anon></anon>
      <anon><anon>R1C1</anon><anon>R1C2</anon></anon>
      <anon><anon>R2C1</anon><anon>R2C2</anon></anon>
    </opt>

    [
      [ 'Col 1', 'Col 2' ],
      [ 'R1C1', 'R1C2' ],
      [ 'R2C1', 'R2C2' ]
    ]

    <opt>
      <one>first</one>
      <two attr="value">second</two>
    </opt>

    {
      'one' => 'first',
      'two' => { 'attr' => 'value', 'content' => 'second' }
    }

  /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