Rutger Vos > Bio-Phylo > Bio::Phylo::NeXML::Writable

Download:
Bio-Phylo-0.58.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Source  

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

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

syntax highlighting: