methods.ringing.orgHome > For programmers > Perl

Ringing::XML::Method

NAME

Ringing::XML::Method - parse and access XML method data

SYNOPSIS

use Ringing::Methods;
use Ringing::Method;

$methods = new Ringing::Methods('my-collection.xml');
foreach($methods->methods) {
  print "Id: ", $_->id, "\n";
  if($_->has('name')) {
    if(defined($_->name)) {
      print "Name: ", $_->name, "\n";
    } else {
      print "Unnamed method\n";
    }
  }
}

$method = shift $methods->methods;
$stage = $method->stage;
$classes = $method->classes;
$title = $method->title;
$pn = $method->pn;
$lh = $method->lead_head;
$cc_class = $method->class;
$little = $method->little;
$differential = $method->differential;
$lhcode = $method->lhcode;
$rwref = $method->rwref;

DESCRIPTION

This module parses an XML structure containing a method, and gives access to the data in it.

XML SCHEMA

For information on the XML structures which this module understands, see the documentation at http://methods.ringing.org/xml.html.

In particular, all the elements discussed belong in the namespace associated to the URL

http://methods.ringing.org/NS/method

which is also the value of the string $Ringing::XML::Method::ns.

CONSTRUCTOR

$method = new Ringing::XML::Method ($node);

This object will usually be constructed by using one of the functions on a Ringing::XML::Methods object, but it may also be constructed independently. The constructor takes one argument, which should be an XML::LibXML::Element object containing a <method> element.

ACCESS FUNCTIONS

The object has several functions for accessing specific pieces of data about the method. They share certain features:

  • The XML structure describing a method is not guaranteed to contain all the data which might be wanted. For example, when the data has come from a remote database, some information might be omitted because it was not requested in the query. If any data is requested which is absent from the XML structure, the corresponding function will return undef. See also the has function below.

  • If the data comes from an XML element which has the xsi:nil attribute set, the function will return undef. On the other hand, if the element is simply empty, the function will return an empty string.

The following functions are defined:

  • name()
  • stage()
  • classes()
  • title()
  • lead_head()
  • class()
  • little()
  • differential()
  • lhcode()
  • rwref()
  • id()

For more information on exactly what data each of these functions returns, see the documentation on the XML structure at http://methods.ringing.org/xml.html.

Place notation

$pn = $method->pn;

The pn function returns the method's place notation as a Ringing::PlaceNotation object.

OTHER FUNCTIONS

has

if($method->has('name')) { }

This function tests whether a certain piece of information about the method is present in the XML.

context

$c = $method->context;

This function returns an XML::LibXML::XPathContext object, which may be used to evaluate XPath expressions on the method element. The prefix m: is bound to the method namespace (see above).

find

$result = $method->find('classification');

This function allows you to directly evaluate an XPath expression in the context of the <method> element.

node

$node = $method->node;

This function returns the underlying XML::LibXML::Element object.

SEE ALSO

Ringing::XML::Library, Ringing::XML::Methods

AUTHOR

Martin Bright <martin@boojum.org.uk>

COPYRIGHT AND LICENCE

Copyright (C) 2004 Martin Bright

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Valid HTML 4.01!Valid CSS!Powered by LibXSLT

Comments to the Webmaster. Last updated 17 November 2004. This site is generously hosted by Mythic Beasts.