Bio::Phylo::NeXML::Writable(3)

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_all_meta()
     Type    : Mutator
     Title   : remove_all_meta
     Usage   : $obj->remove_all_meta();
     Function: Removes all metadata attachments from the object
     Returns : $self
     Args    : None

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_meta_object()
     Type    : Mutator
     Title   : set_meta_object
     Usage   : $obj->set_meta_object($predicate => $object);
     Function: Attaches a $predicate => $object pair to the invocant
     Returns : $self
     Args    : $predicate => (a valid curie of a known namespace)
                   $object => (an object value)

set_meta()
     Type    : Mutator
     Title   : set_meta
     Usage   : $obj->set_meta([ $m1, $m2, $m3 ]);
     Function: Assigns all metadata objects
     Returns : $self
     Args    : An array ref of metadata objects

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_name()
    Sets invocant name.

     Type    : Mutator
     Title   : set_name
     Usage   : $obj->set_name($name);
     Function: Assigns an object's name.
     Returns : Modified object.
     Args    : Argument must be a string. Ensure that this string is safe to use for
               whatever output format you want to use (this differs between xml and
               nexus, for example).

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)

set_base_uri()
    This utility method can be used to set the xml:base attribute, i.e. to specify a location for the object's XML serialization that potentially differs from the physical location of the containing document.

     Type    : Mutator
     Title   : set_base_uri
     Usage   : $obj->set_base_uri('http://example.org');
     Function: Sets the xml:base attribute
     Returns : $self
     Args    : A URI string

set_link()
    This sets a clickable link, i.e. a url, for the object. This has no relation to the xml:base attribute, it is solely intended for serializations that allow clickable links, such as SVG or RSS.

     Type    : Mutator
     Title   : set_link
     Usage   : $node->set_link($url);
     Function: Sets clickable link
     Returns : $self
     Args    : url

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_prefix_for_namespace()
     Type    : Accessor
     Title   : get_prefix_for_namespace
     Usage   : my $prefix = $obj->get_prefix_for_namespace('http://example.org/')
     Function: Retrieves the prefix for the argument namespace
     Returns : A prefix string
     Args    : A namespace URI

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    : Optional: a list of CURIE predicates, in which case
               the returned objects will be those matching these
               predicates

get_meta_object()
    Retrieves the metadata annotation object for the provided predicate

     Type    : Accessor
     Title   : get_meta_object
     Usage   : my $title = $obj->get_meta_object('dc:title');
     Function: Retrieves the metadata annotation value for the object.
     Returns : An annotation value, i.e. the object of a triple
     Args    : Required: a CURIE predicate for which the annotation
               value is returned
     Note    : This method returns the object for the first annotation
               with the provided predicate. Keep this in mind when dealing
               with an object that has multiple annotations with the same
               predicate.

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_name()
    Gets invocant's name.

     Type    : Accessor
     Title   : get_name
     Usage   : my $name = $obj->get_name;
     Function: Returns the object's name.
     Returns : A string
     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_base_uri()
    This utility method can be used to get the xml:base attribute, which specifies a location for the object's XML serialization that potentially differs from the physical location of the containing document.

    If no xml:base attribute has been defined on the focal object, this method moves on, recursively, to containing objects (e.g. from node to tree to forest) until such time that a base URI has been found.

     Type    : Mutator
     Title   : get_base_uri
     Usage   : my $base = $obj->get_base_uri;
     Function: Gets the xml:base attribute
     Returns : A URI string
     Args    : None

get_link()
    This returns a clickable link for the object. This has no relation to the xml:base attribute, it is solely intended for serializations that allow clickable links, such as SVG or RSS.

     Type    : Accessor
     Title   : get_link
     Usage   : my $link = $obj->get_link();
     Function: Returns a clickable link
     Returns : url
     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

is_equal()
    Tests whether the invocant and the argument are the same. Normally this is done by comparing object identifiers, but if the argument is not an object but a string then the string is taken to be a name with which to compare, e.g. $taxon->is_equal('Homo sapiens')

     Type    : Test
     Title   : is_equal
     Usage   : if ( $obj->is_equal($other) ) { ... }
     Function: Tests whether the invocant and the argument are the same
     Returns : BOOLEAN
     Args    : Object to compare with, or a string representing a
               name to compare with the invocant's name

  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.

to_json()
     Serializes object to JSON string

     Type    : Serializer
     Title   : to_json()
     Usage   : print $obj->to_json();
     Function: Serializes object to JSON string
     Returns : String
     Args    : None
     Comments:

to_cdao()
    Serializes object to CDAO RDF/XML string

     Type    : Serializer
     Title   : to_cdao()
     Usage   : print $obj->to_cdao();
     Function: Serializes object to CDAO RDF/XML string
     Returns : String
     Args    : None
     Comments:

SEE ALSO
There is a mailing list at <https://groups.google.com/forum/#!forum/bio-phylo> for any user or developer questions and discussions.

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

CITATION
If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. <http://dx.doi.org/10.1186/1471-2105-12-63>