/ 
Bio-Phylo-0.23
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::NeXML::Writable

NAME

Bio::Phylo::NeXML::Writable - Superclass for objects that serialize to NeXML

SYNOPSIS

# no direct usage

DESCRIPTION

This is the superclass for all objects that can be serialized to NeXML (http://www.nexml.org).

METHODS

MUTATORS

set_namespaces()
Type    : Mutator
Title   : set_namespaces
Usage   : $obj->set_namespaces( 'dwc' => 'http://www.namespaceTBD.org/darwin2' );
Function: Adds one or more prefix/namespace pairs
Returns : $self
Args    : One or more prefix/namespace pairs, as even-sized list, 
          or as a hash reference, i.e.:
          $obj->set_namespaces( 'dwc' => 'http://www.namespaceTBD.org/darwin2' );
          or
          $obj->set_namespaces( { 'dwc' => 'http://www.namespaceTBD.org/darwin2' } );
Notes   : This is a global for the XMLWritable class, so that in a recursive
		   to_xml call the outermost element contains the namespace definitions.
		   This method can also be called as a static class method, i.e.
		   Bio::Phylo::NeXML::Writable->set_namespaces(
		   'dwc' => 'http://www.namespaceTBD.org/darwin2');
set_suppress_ns()
Type    : Mutator
Title   : set_suppress_ns
Usage   : $obj->set_suppress_ns();
Function: Tell this object not to write namespace attributes
Returns : 
Args    : none
clear_suppress_ns()
Type    : Mutator
Title   : clear_suppress_ns
Usage   : $obj->clear_suppress_ns();
Function: Tell this object to write namespace attributes
Returns : 
Args    : none
add_meta()
Type    : Mutator
Title   : add_meta
Usage   : $obj->add_meta($meta);
Function: Adds a metadata attachment to the object
Returns : $self
Args    : A Bio::Phylo::NeXML::Meta object
remove_meta()
Type    : Mutator
Title   : remove_meta
Usage   : $obj->remove_meta($meta);
Function: Removes a metadata attachment from the object
Returns : $self
Args    : Bio::Phylo::NeXML::Meta
set_identifiable()

By default, all XMLWritable objects are identifiable when serialized, i.e. they have a unique id attribute. However, in some cases a serialized object may not have an id attribute (governed by the nexml schema). For such objects, id generation can be explicitly disabled using this method. Typically, this is done internally - you will probably never use this method.

Type    : Mutator
Title   : set_identifiable
Usage   : $obj->set_identifiable(0);
Function: Enables/disables id generation
Returns : $self
Args    : BOOLEAN
set_tag()

This method is usually only used internally, to define or alter the name of the tag into which the object is serialized. For example, for a Bio::Phylo::Forest::Node object, this method would be called with the 'node' argument, so that the object is serialized into an xml element structure called <node/>

Type    : Mutator
Title   : set_tag
Usage   : $obj->set_tag('node');
Function: Sets the tag name
Returns : $self
Args    : A tag name (must be a valid xml element name)
set_attributes()

Assigns attributes for the element.

Type    : Mutator
Title   : set_attributes
Usage   : $obj->set_attributes( 'foo' => 'bar' )
Function: Sets the xml attributes for the object;
Returns : $self
Args    : key/value pairs or a hash ref
set_xml_id()

This method is usually only used internally, to store the xml id of an object as it is parsed out of a nexml file - this is for the purpose of round-tripping nexml info sets.

Type    : Mutator
Title   : set_xml_id
Usage   : $obj->set_xml_id('node345');
Function: Sets the xml id
Returns : $self
Args    : An xml id (must be a valid xml NCName)
unset_attribute()

Removes specified attribute

Type    : Mutator
Title   : unset_attribute
Usage   : $obj->unset_attribute( 'foo' )
Function: Removes the specified xml attribute for the object
Returns : $self
Args    : an attribute name

ACCESSORS

get_namespaces()
Type    : Accessor
Title   : get_namespaces
Usage   : my %ns = %{ $obj->get_namespaces };
Function: Retrieves the known namespaces
Returns : A hash of prefix/namespace key/value pairs, or
          a single namespace if a single, optional
          prefix was provided as argument
Args    : Optional - a namespace prefix
get_meta()

Retrieves the metadata for the element.

Type    : Accessor
Title   : get_meta
Usage   : my @meta = @{ $obj->get_meta };
Function: Retrieves the metadata for the element.
Returns : An array ref of Bio::Phylo::NeXML::Meta objects
Args    : None.
get_tag()

Retrieves tag name for the element.

Type    : Accessor
Title   : get_tag
Usage   : my $tag = $obj->get_tag;
Function: Gets the xml tag name for the object;
Returns : A tag name
Args    : None.
get_xml_tag()

Retrieves tag string

Type    : Accessor
Title   : get_xml_tag
Usage   : my $str = $obj->get_xml_tag;
Function: Gets the xml tag for the object;
Returns : A tag, i.e. pointy brackets
Args    : Optional: a true value, to close an empty tag
get_attributes()

Retrieves attributes for the element.

Type    : Accessor
Title   : get_attributes
Usage   : my %attrs = %{ $obj->get_attributes };
Function: Gets the xml attributes for the object;
Returns : A hash reference
Args    : None.
Comments: throws ObjectMismatch if no linked taxa object 
          can be found
get_xml_id()

Retrieves xml id for the element.

Type    : Accessor
Title   : get_xml_id
Usage   : my $id = $obj->get_xml_id;
Function: Gets the xml id for the object;
Returns : An xml id
Args    : None.
get_dom_elt()
Type    : Serializer
Title   : get_dom_elt
Usage   : $obj->get_dom_elt
Function: Generates a DOM element from the invocant
Returns : a DOM element object (default XML::Twig)
Args    : DOM factory object

TESTS

is_identifiable()

By default, all XMLWritable objects are identifiable when serialized, i.e. they have a unique id attribute. However, in some cases a serialized object may not have an id attribute (governed by the nexml schema). This method indicates whether that is the case.

Type    : Test
Title   : is_identifiable
Usage   : if ( $obj->is_identifiable ) { ... }
Function: Indicates whether IDs are generated
Returns : BOOLEAN
Args    : NONE
is_ns_suppressed()
Type    : Test
Title   : is_ns_suppressed
Usage   : if ( $obj->is_ns_suppressed ) { ... }
Function: Indicates whether namespace attributes should not
          be written on XML serialization
Returns : BOOLEAN
Args    : NONE

CLONER

clone()

Clones invocant.

Type    : Utility method
Title   : clone
Usage   : my $clone = $object->clone;
Function: Creates a copy of the invocant object.
Returns : A copy of the invocant.
Args    : NONE.
Comments: Cloning is currently experimental, use with caution.

SERIALIZERS

to_xml()

Serializes invocant to XML.

Type    : XML serializer
Title   : to_xml
Usage   : my $xml = $obj->to_xml;
Function: Serializes $obj to xml
Returns : An xml string
Args    : None
to_dom()
Type    : Serializer
Title   : to_dom
Usage   : $obj->to_dom
Function: Generates a DOM subtree from the invocant and
          its contained objects
Returns : a DOM element object (default: XML::Twig flavor)
Args    : DOM factory object
Note    : This is the generic function. It is redefined in the 
          classes below.

SEE ALSO

Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com.

REVISION

$Id: XMLWritable.pm 1242 2010-03-03 20:37:23Z rvos $