The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XML-Genx-0.01
River stage zero No dependents
/ XML::Genx

NAME

XML::Genx - Simple, correct XML writer

SYNOPSIS

  use XML::Genx;
  my $w = XML::Genx->new;
  $w->StartDocFile( *STDOUT );
  $w->StartElementLiteral( 'urn:foo', 'foo' ):
  $w->AddText( 'bar' );
  $w->EndElement;
  $w->EndDocument;

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

Unless otherwise stated, all methods return a genxStatus code. This will be zero for success, or nonzero otherwise. A textual explanation of the error can be extracted.

new ( )

Constructor. Returns a new XML::Genx object.

startDocFile ( FILEHANDLE )

Starts writing output to FILEHANDLE.

EndDocument ( )

Finishes writing to the output stream.

StartElementLiteral ( NAMESPACE, LOCALNAME )

Starts an element LOCALNAME, in NAMESPACE. If NAMESPACE is undef, no namespace is used.

EndElement ( )

Output a closing tag for the currently open element.

LastErrorMessage ( )

Returns the string value of the last error.

GetErrorMessage ( CODE )

Given a genxStatus code, return the equivalent string.

AddText ( STRING )

Output STRING.

AddCharacter ( C )

Output the Unicode character with codepoint C (an integer).

Comment ( STRING )

Output STRING as an XML comment.

PI ( TARGET, STRING )

Output a processing instruction, with target TARGET and STRING as the body.

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.

DeclareElement ( NS, NAME )

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

DeclareAttribute ( NS, NAME )

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

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

  • Provide an ability to use genxStartDocSender() so that you can pass in code refs that get given strings. This should be the underpinnings of a slightly easier interface than filehandles.

  • Clean up warnings from the C compiler under FreeBSD. They appear to be related to 64 bit integers, but I need to investigate further.

      lib/XML/Genx.c: In function `XS_XML__Genx_DESTROY':
  lib/XML/Genx.c:98: warning: cast to pointer from integer of different size

  • Make the constants available in Perl.

  • Make the interface more Perlish where possible. I really like the way that the Ruby interface uses blocks, but I don't think it'd be as practical in Perl...

  • Clean up the XS a little; there's a lot of cut'n'paste in there.

SEE ALSO

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

AUTHOR

Dominic Mitchell, <dom@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 860 2004-11-27 00:18:08Z dom $