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-xmlapi-0.07
/ XML::xmlapi

NAME

XML::xmlapi - The xmlapi was an expat wrapper library I wrote in 2000 in ANSI C; this is its Perl port.

VERSION

Version 0.07

SYNOPSIS

The xmlapi loads an XML file or string into a hash structure, and provides a lot of very C-like functions to access it.

    use XML::xmlapi;

    my $foo = XML::xmlapi->new();
    ...

BUILDING AND LOADING XML

Before manipulating XML, you have to have the structure. These functions let you build that.

new($tag), create($tag)

These are synonomous. At the moment, they just take the XML tag to be created. I had started some convenience code in C to set attributes directly in the creation call, but Perl's sane string handling obviates a lot of the convenience stuff I needed in C just to get by. So this may be the final form of these calls.

createtext($content)

A text element is used for non-tag content. In <tag>This stuff</tag>, "This stuff" is the non-tag content.

createinto ($tag)

Takes an existing xmlapi object and makes it a completely new XML tag. You probably don't need this (it comes in handy in the parser, though).

read($string), parse($string)

Synonomous functions that, given a string containing some XML, build an xmlapi object from it.

parse_from_file ($file)

Given a filename, loads its contents into an xmlapi structure.

WRITING XML

Once you've got XML structures built, you'll eventually want to write them out somewhere (that's basically the point). Here are some methods to do that.

string(), rawstring()

Returns a string representation of the XML structure. The string quotes all characters appropriately for XML serialization, while rawstring does not.

stringcontent(), content()

Same as string and rawstring, except they don't include the enclosing tags; just give you the content.

stringcontenthtml()

This might be a fossil. The point is to write HTML-ish output given the XML input, but that isn't what's implemented in this module.

write($file)

Given a stream or a filename, writes the XML to said stream or file.

write_UCS2LE ($filename)

Given a filename, opens it with :raw:encoding(UCS-2LE):crlf:utf8 and writes an 0xFEFF byte order marker at the outset. This is used by TRADOS TTX files, which is why it's here; it might be useful for other things, but if so, I have yet to discover them.

ATTRIBUTES

In XML, as I'm sure you know, each tag may have any number of attributes. These functions allow you to set them and get their values. XML::xmlapi remembers the order of attributes you write, in an attempt to be able to write files in the same way it found them.

set($attr, $value), set_or_get ($attr, $value)

Both set a value for an attribute. The set function only sets the value; the set_or_get can be called with an undefined value and won't set anything, but in any case will return the current value (after setting it, if necessary). These semantics are really useful for tied values and the like.

attrdef($attr)

Returns true if the attribute has been defined, false otherwise. Maybe not too useful on its own, but used in the following functions.

get($attr, $default), attrval($attr, $default)

Synonomous functions to retrieve an attribute value. If the attribute is not defined, will return the default value supplied, if any. If no default is supplied, returns a blank, not an undefined value. You might hate that.

getnum($attr, $default)

Guaranteed to return a numeric value. In other words, if the attribute is undefined or has a text value, returns $default or 0.

getcontext($attr, $default), getnumcontext($attr, $default)

Get an attribute value by text or by number, but if it's not found, try the tag's parent, recursively. Allows the tree to act like a set of nested value contexts.

STRUCTURE

In addition to attributes, any XML tag may contain an arbitrary list of other tags and non-tag text content. These methods expose that stuff.

elements($name)

Returns a list of the elements (i.e. tags, not content) under the XML tag you give it. If you give a name, it will only return those that match that name.

first($name)

Returns the first element under the tag you give it; again, if given a name it will return that name.

children()

Returns the list of all children in order, i.e. tags and non-tag text.

parent(), ancestor('tag')

The parent function returns the parent of the current tag, if there is one. This allows you to walk around in trees. The ancestor function calls parent repeatedly until it finds a parent with the tag you supply, or runs out of parents. If it's not given a parent tag name, it will return the root of the tree, not an undefined.

copy()

Makes a copy of a tag that is an independent tree, that is, has no parent.

append ($child), append_pretty ($child)

Adds a newly created tag at the end of the current tag's content list. Don't do this with a tag that's already in another tree, or the pointers will no longer match up (the other tree will still think it owns the appended child).

The append method just slaps the tag into the parent; the append_pretty method inserts newlines as needed to ensure that the resulting XML structure is readable.

replace($child)

Given a new child, finds the first existing child with the same name (tag) and replaces that one with the new one.

replacecontent($child)

Given a new child, removes all existing children from the current tag and replaces them all with the new child. In Perl, should probably take a list, but it doesn't, yet.

is($name)

Returns true if the tag is named $name.

is_element()

Returns true if the tag is an element, false if it's content.

name()

Returns the current tag's tag.

SEARCHING XML TREES

search ($element, $attribute, $value)

Does a (depth-first) search of the XML structure for an element named $element (if undef, the tag of the element is ignored in the search) with an attribute $attribute with value $value (those two can also be undef if you don't care about attributes).

Returns a list of all matches.

search_first ($element, $attribute, $value)

Does the same as search but returns after finding the first match.

xmlobj_is_field, xmlobj_field, xmlobj_set, xmlobj_get, xmlobj_getkey

These are fossils right now, left over from extensive C code that I used between 2000 and about 2004. If I see a need to reimplement them in Perl, I will document them then. These implementations work, but I frankly don't remember how well.

escape($string), unescape($string)

XML-escape and unescape the string you give them. Can also be called as class methods.

AUTHOR

Michael Roberts, <michael at vivtek.com>

BUGS

Please report any bugs or feature requests to bug-xml-xmlapi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-xmlapi. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc XML::xmlapi

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2010 Michael Roberts.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.