view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    By default, high-bit data will be passed through unmodified, so that
    UTF-8 data can be generated with pre-Unicode perls. If you know that
    your data is ASCII, use the value 'high-bit' for the escape option and
    bytes with the high bit set will be turned into numeric entities. You
    can combine this functionality with the other escape options by
    comma-separating the values:

      my $a = XML::Generator->new(escape => 'always,high-bit');
      print $a->foo("<\242>");

    yields

      <foo>&lt;&#162;&gt;</foo>

    Because XML::Generator always uses double quotes ("") around attribute
    values, it does not escape single quotes. If you want single quotes
    inside attribute values to be escaped, use the value 'apos' along with
    'always' or 'unescaped' for the escape option. For example:

        my $gen = XML::Generator->new(escape => 'always,apos');
        print $gen->foo({'bar' => "It's all good"});

        <foo bar="It&apos;s all good" />

    If you actually want & to be converted to &amp; even if it looks like it
    could be part of a valid entity, use the value 'even-entities' along
    with 'always'. Supplying 'even-entities' to the 'unescaped' option is
    meaningless as entities are already escaped with that option.

  pretty
    To have nice pretty printing of the output XML (great for config files
    that you might also want to edit by hand), supply an integer for the
    number of spaces per level of indenting, eg.

       my $gen = XML::Generator->new(pretty => 2);
       print $gen->foo($gen->bar('baz'),
                       $gen->qux({ tricky => 'no'}, 'quux'));

    would yield

       <foo>
         <bar>baz</bar>
         <qux tricky="no">quux</qux>
       </foo>

    You may also supply a non-numeric string as the argument to 'pretty', in
    which case the indents will consist of repetitions of that string. So if
    you want tabbed indents, you would use:

         my $gen = XML::Generator->new(pretty => "\t");

    Pretty printing does not apply to CDATA sections or Processing
    Instructions.

  conformance
    If the value of this option is 'strict', a number of syntactic checks
    are performed to ensure that generated XML conforms to the formal XML
    specification. In addition, since entity names beginning with 'xml' are
    reserved by the W3C, inclusion of this option enables several special
    tag names: xmlpi, xmlcmnt, xmldecl, xmldtd, xmlcdata, and xml to allow
    generation of processing instructions, comments, XML declarations,
    DTD's, character data sections and "final" XML documents, respectively.

    Invalid characters (http://www.w3.org/TR/xml11/#charsets) will be
    filtered out. To disable this behavior, supply the
    'filter_invalid_chars' option with the value 0.

    See "XML CONFORMANCE" and "SPECIAL TAGS" for more information.

  filterInvalidChars, filter_invalid_chars
    Set this to a 1 to enable filtering of invalid characters, or to 0 to
    disable the filtering. See http://www.w3.org/TR/xml11/#charsets for the
    set of valid characters.

  allowedXMLTags, allowed_xml_tags
    If you have specified 'conformance' => 'strict' but need to use tags
    that start with 'xml', you can supply a reference to an array containing
    those tags and they will be accepted without error. It is not an error
    to supply this option if 'conformance' => 'strict' is not supplied, but
    it will have no effect.

  empty
    There are 5 possible values for this option:

       self    -  create empty tags as <tag />  (default)
       compact -  create empty tags as <tag/>
       close   -  close empty tags as <tag></tag>
       ignore  -  don't do anything (non-compliant!)
       args    -  use count of arguments to decide between <x /> and <x></x>

    Many web browsers like the 'self' form, but any one of the forms besides
    'ignore' is acceptable under the XML standard.

    'ignore' is intended for subclasses that deal with HTML and other SGML
    subsets which allow atomic tags. It is an error to specify both
    'conformance' => 'strict' and 'empty' => 'ignore'.

    'args' will produce <x /> if there are no arguments at all, or if there
    is just a single undef argument, and <x></x> otherwise.

  version
    Sets the default XML version for use in XML declarations. See "xmldecl"
    below.

  encoding
    Sets the default encoding for use in XML declarations.

  dtd
    Specify the dtd. The value should be an array reference with three
    values; the type, the name and the uri.

  xml
    This is an hash ref value that should contain the version, encoding and
    dtd values (same as above). This is used in case "conformance" is set to
    "loose", but you still want to use the xml declaration or prolog.

IMPORT ARGUMENTS
    use XML::Generator ':option';

    use XML::Generator option => 'value';

README  view on Meta::CPAN

    number of special tags beginning with 'xml' are allowed (see "SPECIAL
    TAGS"). Note that you can also supply an explicit list of allowed tags
    with the 'allowed_xml_tags' option.

    Also, the filter_invalid_chars option is automatically set to 1 unless
    it is explicitly set to 0.

SPECIAL TAGS
    The following special tags are available when running under strict
    conformance (otherwise they don't act special):

  xmlpi
    Processing instruction; first argument is target, remaining arguments
    are attribute, value pairs. Attribute names are syntax checked, values
    are escaped.

  xmlcmnt
    Comment. Arguments are concatenated and placed inside <!-- ... -->
    comment delimiters. Any occurences of '--' in the concatenated arguments
    are converted to '&#45;&#45;'

  xmldecl (@args)
    Declaration. This can be used to specify the version, encoding, and
    other XML-related declarations (i.e., anything inside the <?xml?> tag).
    @args can be used to control what is output, as keyword-value pairs.

    By default, the version is set to the value specified in the
    constructor, or to 1.0 if it was not specified. This can be overridden
    by providing a 'version' key in @args. If you do not want the version at
    all, explicitly provide undef as the value in @args.

    By default, the encoding is set to the value specified in the
    constructor; if no value was specified, the encoding will be left out
    altogether. Provide an 'encoding' key in @args to override this.

    If a dtd was set in the constructor, the standalone attribute of the
    declaration will be set to 'no' and the doctype declaration will be
    appended to the XML declartion, otherwise the standalone attribute will
    be set to 'yes'. This can be overridden by providing a 'standalone' key
    in @args. If you do not want the standalone attribute to show up,
    explicitly provide undef as the value.

  xmldtd
    DTD <!DOCTYPE> tag creation. The format of this method is different from
    others. Since DTD's are global and cannot contain namespace information,
    the first argument should be a reference to an array; the elements are
    concatenated together to form the DTD:

       print $xml->xmldtd([ 'html', 'PUBLIC', $xhtml_w3c, $xhtml_dtd ])

    This would produce the following declaration:

       <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
            "DTD/xhtml1-transitional.dtd">

    Assuming that $xhtml_w3c and $xhtml_dtd had the correct values.

    Note that you can also specify a DTD on creation using the new()
    method's dtd option.

  xmlcdata
    Character data section; arguments are concatenated and placed inside
    <![CDATA[ ... ]]> character data section delimiters. Any occurences of
    ']]>' in the concatenated arguments are converted to ']]&gt;'.

  xml
    "Final" XML document. Must be called with one and exactly one
    XML::Generator-produced XML document. Any combination of
    XML::Generator-produced XML comments or processing instructions may also
    be supplied as arguments. Prepends an XML declaration, and re-blesses
    the argument into a "final" class that can't be embedded.

CREATING A SUBCLASS
    For a simpler way to implement subclass-like behavior, see "STACKABLE
    AUTOLOADs".

    At times, you may find it desireable to subclass XML::Generator. For
    example, you might want to provide a more application-specific interface
    to the XML generation routines provided. Perhaps you have a custom
    database application and would really like to say:

       my $dbxml = new XML::Generator::MyDatabaseApp;
       print $dbxml->xml($dbxml->custom_tag_handler(@data));

    Here, custom_tag_handler() may be a method that builds a recursive XML
    structure based on the contents of @data. In fact, it may even be named
    for a tag you want generated, such as authors(), whose behavior changes
    based on the contents (perhaps creating recursive definitions in the
    case of multiple elements).

    Creating a subclass of XML::Generator is actually relatively
    straightforward, there are just three things you have to remember:

       1. All of the useful utilities are in XML::Generator::util.

       2. To construct a tag you simply have to call SUPER::tagname,
          where "tagname" is the name of your tag.

       3. You must fully-qualify the methods in XML::Generator::util.

    So, let's assume that we want to provide a custom HTML table() method:

       package XML::Generator::CustomHTML;
       use base 'XML::Generator';

       sub table {
           my $self = shift;

           # parse our args to get namespace and attribute info
           my($namespace, $attr, @content) =
              $self->XML::Generator::util::parse_args(@_)

           # check for strict conformance
           if ( $self->XML::Generator::util::config('conformance') eq 'strict' ) {
              # ... special checks ...
           }

           # ... special formatting magic happens ...

           # construct our custom tags
           return $self->SUPER::table($attr, $self->tr($self->td(@content)));