The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Genx-0.12
River stage zero No dependents
++
/ XML::Genx

NAME

XML::Genx - Simple, correct XML writer

SYNOPSIS

  use XML::Genx;
  my $w = XML::Genx->new;
  eval {
      # <foo>bar</foo>
      $w->StartDocFile( *STDOUT );
      $w->StartElementLiteral( 'foo' );
      $w->AddText( 'bar' );
      $w->EndElement;
      $w->EndDocument;
  };
  die "Writing XML failed: $@" if $@;

DESCRIPTION

This class is used for generating XML. The underlying library (genx) ensures that the output is well formed, canonical XML. That is, all characters are correctly encoded, namespaces are handled properly and so on.

The API is mostly a wrapper over the original C library. Consult the genx documentation for the fine detail. This code is based on genx beta5.

METHODS

All methods will die() when they encounter an error. Otherwise they return zero.

new ( )

Constructor. Returns a new XML::Genx object.

StartDocFile ( FILEHANDLE )

Starts writing output to FILEHANDLE.

StartDocSender ( CALLBACK )

Takes a coderef ( sub {} ), which gets called each time that genx needs to output something. CALLBACK will be called with two arguments: the text to output and the name of the function that called it (one of write, write_bounded, or flush).

  $w->StartDocSender( sub { print $_[0] } );

In the case of flush, the first argument will always be an empty string.

The string passed to CALLBACK will always be UTF-8.

NB: If you just want to append to a string, have a look at "StartDocString" in XML::Genx::Simple.

EndDocument ( )

Finishes writing to the output stream.

StartElementLiteral ( [NAMESPACE], LOCALNAME )

Starts an element LOCALNAME, in NAMESPACE. If NAMESPACE is not present or undef, or an empty string, no namespace is used.

AddAttributeLiteral ( [NAMESPACE], LOCALNAME, VALUE )

Adds an attribute LOCALNAME, with contents VALUE. If NAMESPACE is not present or undef, or an empty string, no namespace is used.

EndElement ( )

Output a closing tag for the currently open element.

LastErrorMessage ( )

Returns the string value of the last error.

LastErrorCode ( )

Returns the integer status code of the last error. This can be compared to one of the values in XML::Genx::Constants.

This will return zero if no error condition is present.

The same value will be returned by the object until the next exception is thrown (ie: it does not get cleared by further calls to genx methods).

GetErrorMessage ( CODE )

Given a genxStatus code, return the equivalent string.

ScrubText ( STRING )

Returns a new version of STRING with prohibited characters removed. Prohibited characters includes non UTF-8 byte sequences and characters which are not allowed in XML 1.0.

AddText ( STRING )

Output STRING. STRING must be valid UTF-8.

AddCharacter ( C )

Output the Unicode character with codepoint C (an integer). This is normally obtained by ord().

Comment ( STRING )

Output STRING as an XML comment. Genx will complain if STRING contains "--".

PI ( TARGET, STRING )

Output a processing instruction, with target TARGET and STRING as the body. Genx will complain if STRING contains "?>" or if TARGET is the string "xml" (in any case).

UnsetDefaultNamespace ( )

Insert an xmlns="" attribute. Has no effect if the default namespace is already in effect.

GetVersion ( )

Return the version number of the Genx library in use.

DeclareNamespace ( URI, PREFIX )

Returns a new namespace object. The resulting object has two methods defined on it.

GetNamespacePrefix ( )

Returns the current prefix in scope for this namespace.

AddNamespace ( [PREFIX] )

Adds the namespace into the document, optionally with PREFIX.

NB: This object is only valid as long as the original XML::Genx object that created it is still alive.

DeclareElement ( [NS], NAME )

Returns a new element object. NS must an object returned by DeclareNamespace(), or undef to indicate no namespace (or not present at all).

The resulting object has one method available to call.

StartElement ( )

Outputs a start tag.

NB: This object is only valid as long as the original XML::Genx object that created it is still alive.

DeclareAttribute ( [NS], NAME )

Returns a new attribute object. NS must an object returned by DeclareNamespace(), or undef to indicate no namespace (or not present at all).

There is one method defined for this object.

AddAttribute ( VALUE )

Adds an attribute to the current element with VALUE as the contents.

NB: This object is only valid as long as the original XML::Genx object that created it is still alive.

LIMITATIONS

According to the Genx manual, the things that Genx can't do include:

  • Generating output in anything but UTF8.

  • Writing namespace-oblivious XML. That is to say, you can't have an element or attribute named foo:bar unless foo is a prefix associated with some namespace.

  • Empty-element tags.

  • Writing XML or <!DOCTYPE> declarations. Of course, you could squeeze these into the output stream yourself before any Genx calls that generate output.

  • Pretty-printing. Of course, you can pretty-print yourself by putting the linebreaks in the right places and indenting appropriately, but Genx won't do it for you. Someone might want to write a pretty-printer that sits on top of Genx.

TODO

  • Write a SAX output filter using XML::Genx.

SEE ALSO

XML::Genx::Constants, XML::Genx::Simple.

http://www.tbray.org/ongoing/When/200x/2004/02/20/GenxStatus

AUTHOR

Dominic Mitchell, <cpan@happygiraffe.net>

The genx library was created by Tim Bray http://www.tbray.org/.

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Dominic Mitchell. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The genx library is:

Copyright (c) 2004 by Tim Bray and Sun Microsystems. For copying permission, see http://www.tbray.org/ongoing/genx/COPYING.

VERSION

@(#) $Id: Genx.pm 578 2005-03-01 23:09:21Z dom $