SYNOPSIS
     #/usr/bin/perl -w

     use XML::Maker;

     my $root   = new XML::Maker("root");
     my $person = $root->subtag("person", name => 'Vadim',
                                          age => 22);
     my $info   = $person->subtag("info");
     $info->text("Perl programmer");

     print $root->make(0);

FEATURES
     * Easy and compact generation of XML
     * A function receiving an object can't change the parent.
     * It's impossible to make more than one root element
     * It's impossible to leave an element unclosed
     * Can print indented XML

DESCRIPTION
    This module has been written to provide easy and safe generation of XML.
    Unlike other modules, this one does not produce output as soon as it
    can, but only when calling the make() function. This is intentionally
    done to make sure that it will always output well formatted XML.

    One disadvantage of using this module is that everything is kept in
    memory until you destroy the object. If your program needs to generate a
    large amount of XML you should use another module, for example see
    XML::Writer.

    Another intended feature is safety. If you pass a XML::Maker object to a
    function it will be able to do whatever it wants with it, but will not
    have access to its parent. This should make it easier to find which part
    of the program is generating bad output, but again, may not suit your
    needs.

    For ease of use, XML closing tags are generated automatically. If the
    resulting XML element contains a CDATA area, then the output will
    contain opening and closing tags:

      <element key="value">text</element>

    However, if there is no text, then an empty tag will be generated:

      <element key="value"/>

    Due to the design of this module, child objects will not go out of scope
    as you might expect, see "remove()" for an explanation of this.

GET/SET METHODS
    All the methods in this package that modify values provide "get" and
    "set" functions at the same time. If passed a value other than undef
    they will set the value to the passed one.They will also return the old
    value of the parameter. For example:

      # Set separator to |, and save the old one
      my $old_separator = $obj->separator("|");

      # (code)

      # Restore old separator
      $obj->separator( $old_separator );

METHODS
  new($name, [%attributes])
    Create a new XML::Maker object. It is mandatory to pass a $name argument
    to indicate the name of this tag. "new" isnormally used to create the
    root element.

    Optionally, you can pass a hash containing the attribute names and
    values. The order in which they will be generated in the resulting XML
    is undefined.

  make([$tabs])
    Build a text representation of the object in the form of a XML tree.The
    process will start at the object this is called on, and extend to all of
    its children.

    If $tabs is defined, then the output will be indented, starting with the
    specified number of tabs. You probably want to use 0 here.

  subtag($name, [%attributes])
    Create a child XML::Maker object. It works exactly the same as new(),
    except that the new object will be linked to its parent, instead of
    being independent.

    Creating a new object with new, and then using attach() on it has the
    same effect.

  attach($tag)
    Attach a XML::Maker object to another. The object attached will become a
    child of the object being attached to. If the child was a child of a
    XML::Maker object, then it will stop being the child of that object.

  detach($tag)
    Detach a XML::Maker object. This only works if the object being detached
    is a child of the object this method is called on. The child object will
    then become independent from its parent.

  remove()
    Empties the XML::Maker object, and calls to the parent to remove its
    internal reference. This is done to completely destroy a child object.
    For example, suppose this code:

      my $root = new XML::Maker('root');
      add_info( $root );
      print $root->make();

      sub add_info {
            my $obj = shift;
            my $tag = $obj->subtag('info', 'foo' => 'bar');
      }

    Here, even though $tag goes out of scope, it *does not disappear*,
    because $root has an internal reference to it. In order to make it
    vanish you need to call "$tag->remove()", or "$obj->detach($tag )"
    inside the "add_info" function. In the second case, $tag will continue
    to exist until it goes out of scope.

  separator([$value])
    Gets/sets the separator. The separator is used by the "merge"method, and
    by default is ", ".

  name([$name])
    Gets/sets the name of the element.

  attribute($name, [$value])
    Gets/sets an attribute of the element. This can't be used to remove an
    attribute, use the "del_attribute()" method for that.

  del_attribute($name)
    Removes an attribute.

  merge($name, $value)
    Appends the separator, then string to an attribute. For example:

      $obj->attribute('meta', 'foo'); # Sets 'meta' to 'foo'
      $obj->merge('meta', 'bar');     # 'meta' is now 'foo, bar'

  text([$text])
    Gets/sets the text of the current element. If you want to remove the
    text simply pass an empty string ("")

  addtext($text)
    Adds a string to the text of the element.

  count_children()
    Returns the number of children this object has. Only counts how many
    children this specific object has, that is, it does not count
    recursively.

    A recursive count is not yet implemented.

NOTES
    This module is not yet complete. Many XML features are missing, for
    example:

     * Namespaces
     * DOCTYPE declarations
     * XML type declarations
     * Comments

    I'm interested in feedback about this module, and comments about new
    features,improvements or bug reports are welcome.

AUTHOR
    Vadim Trochinsky (vadim_t at teleline dot es)

SEE ALSO
    XML::Writer

COPYRIGHT
    XML::Maker - A Perl module for generating XML Copyright (C) 2003 Vadim
    Trochinsky

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or(at your
    option) any later version.