• NAME
• SYNOPSIS
• DESCRIPTION
• METHODS
• ATTRIBUTE METHODS
• NAME
• SYNOPSIS
• DESCRIPTION
• ATTRIBUTE METHODS
• INSTANCE METHODS

NAME

Bio::MAGE::XMLWriter - a module for exporting MAGE-ML

SYNOPSIS

  use Bio::MAGE::XMLUtils;

  my $writer = Bio::MAGE::XMLWriter->new(@args);
  $writer->write($mage);

  #
  # attributes to modify where the output is written
  #

  # set the output filehandle
  my $fh = \*STDOUT;
  $writer->fh($fh);

  # whether to write data cubes externally (default == FALSE)
  $writer->external_data($bool);

  # which directory to write external data cubes (default == /tmp)
  $writer->external_data_dir($path);

  # whether the to interpret the C<cube> as data or a file
  # path (default == FALSE)
  $writer->cube_holds_path($bool);

  #
  # attributes to modify the output format
  #

  # to change the level of indent for each new tag (defaul == 2)
  $writer->indent_increment($num);

  # to change the beginning indent level (defaul == 0)
  $writer->indent_level($num);

  # set to true to not format attributes (default == FALSE)
  $writer->attrs_on_one_line($bool);

  # how many extra spaces attributes should be indented past start
  # tag end (default == 1)
  $writer->attr_indent($num);

  # whether to write all sub-tags on the same line (default == undef)
  $writer->collapse_tag($bool);

  #
  # attributes to modify the the document
  #

  # to change the encoding (default == ISO-8859-1)
  $writer->encoding($format);

  # to set the public id (default == undef)
  $writer->public_id($id);

  # to change the system id (default == MAGE-ML.dtd)
  $writer->system_id($id);

  # check to see that objects set more than just identifier (default == TRUE)
  $writer->empty_identifiable_check();

  #
  # attributes to handle identifiers
  #

  # whether to create identifiers if not specified (default == FALSE)
  $writer->generate_new_identifiers();

  # code reference to be invoked for creating new identifiers
  $writer->generate_identifier();

DESCRIPTION

Methods for transforming information from a MAGE-OM objects into MAGE-ML.

METHODS

write($MAGE_object);

write() prints the objects contained in $MAGE_object as MAGE-ML to the file handle used by the writer.

ATTRIBUTE METHODS

  The following methods must all be invoked using an instance of Bio::MAGE::XMLWriter;

indent_level($num)

This attribute controls the current level of indentation while writing a document. It should not be manipulated by users, unless for some reason you wanted to set the starting indent level to something other than zero.

Default Value: 0 (zero)

indent_increment($num)

This attribute controls the the number of spaces that added to the indent for every new level of elements.

Default Value: 2

attrs_on_one_line($bool)

This attribute controls whether attribute values should be pretty-printed. If true, attributes will not pretty-printed, but will instead be written out all on one line.

Default Value: false

attr_indent($bool)

Controls how many spaces past the end start tag that attributes should be indented. This example shows an attr_inden of 1:

      <Reporter identifier="Reporter:X Units Per Pixel"
                name="X Units Per Pixel">

The following illustrates and attr_indent of -2:

      <Person firstName="John"
           identifier="Person:John Smith"
           name="John Smith"
           lastName="Smith">

Default Value: 1

collapse_tag($bool)

This attribute is not very useful at the moment. In the future it may be used to specify tags that should have their contents all on a single line.

Currently it controls whether or not to write a newline after each elements start tag, with no method to decide to write or not to write based on the name of the tag.

Default Value: false

encoding($string)

This is the value that value be written out as the encoding attribute for the XML Declaration of the output MAGE-ML document:

  <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

Default Value: ISO-8859-1

public)_id($string)

If defined, this value will be written out as the value of the PUBLIC attribute of the DOCTYPE tag in the output MAGE-ML document.

Default Value: undef

system_id($string)

If defined, this value will be written out as the value of the SYSTEM attribute of the DOCTYPE tag in the output MAGE-ML document:

  <!DOCTYPE MAGE-ML  SYSTEM "MAGE-ML.dtd">

Default Value: MAGE-ML.dtd

generate_identifier($code_ref)

This attribute stores a code reference that will be invoked to create a new identifier for any object that does not already have one defined. This will happen only if the generate_new_identifiers attribute is set to true.

Default Value: \&identifier_generation

generate_new_identifier($bool)

If this attribute is set to true, the code reference store in the generate_identifier attribute will be invoked to create a new identifier for any object that does not already have one defined.

Default Value: false

fh($file_handle)

This is the file handle to which the MAGE-ML document will be written.

Default Value: undef

external_data($bool)

If defined, this will cause all BioAssayData objects to write themselves out using the DataExternal format.

Default Value: false

external_data_dir($path)

The fh attribute only controls where the main MAGE-ML document is written. If the external_data attribute is set, the writer will also create a seperate external data file for each data cube.

The external_data_dir controls what director those files are written to.

Default Value: /tmp

cube_holds_path($path)

Sometimes, you already have your data written to an external file, and you simply want to reuse the file without any extra overhead. The cube_holds_path attribute controls indicates that you are storing the path to the external file in the cube attribute of the BioDataCube objects.

Default Value: false

empty_identifiable_check($bool)

If true, all objects that define an identifier attribute and no other attributes will only be included as <*_ref> elements.

NOTE: Currently no checking of association values is made, only attributes. So if you want to ensure that an Identifiable object is written, make sure that you set the name attribute as well as the identifier attribute.

Default Value: true

NAME

Bio::MAGE::XMLReader - a module for exporting MAGE-ML

SYNOPSIS

  use Bio::MAGE::XMLReader;

  my $reader = Bio::MAGE::XMLReader->new(handler=>$handler,
                                         sax1=>$sax1,
                                         verbose=>$verbose,
                                         log_file=>\*STDERR,
                                        );

  # set the sax1 attribute
  $reader->sax1($bool);

  # get the current value
  $value = $reader->sax1();

  # set the content/document handler - this method is provided for completeness
  # the value should be set in the call to the constructor to be effective
  $reader->handler($HANDLER);

  # get the current handler
  $handler = $reader->handler();

  # set the attribute
  $reader->verbose($integer);

  # get the current value
  $value = $reader->verbose();

  # set the attribute
  $reader->log_file($filename);

  # get the current value
  $value = $reader->log_file();

  my $fh = \*STDOUT;
  my $mage = $reader->read($file_name);

DESCRIPTION

Methods for transforming information from a MAGE-OM objects into MAGE-ML.

ATTRIBUTE METHODS

These methods have a polymorphic setter/getter method that sets an attribute which affects the parsing of MAGE-ML. If given a value, the method will save the value to the attribute, if invoked with no argument it will return the current value of the attribute.

These attributes can all be set in the call to the constructor using the named parameter style.

sax1

This attribute determines whether a SAX1 parser and DocumentHandler or a SAX2XMLReader and a ContentHandler will be used for parsing. The default is to use a SAX2 parser.

handler

If an application needs a custom handler it can set this attribute in the call to the constructor. It is advised that the object use inherit either from Bio::MAGE::ContentHandler (if using SAX2) or Bio::MAGE::DocumentHandler if using SAX1. In particular, whatever class is used, it needs to implement the following methods:

• verbose
  called with the integer parameter that specifies the desired level of output

• log_file
  called with the file handle to which ouput should be sent

• init
  called during the constructor for any needed work

verbose

This attribute determines the desired level of output during the parse. The default is no output. A positive value increases the amount of information.

log_file

This attribute specifies a file handle to which parse output will be directed. It is only needed if verbose is positive.

resolve_identifiers

This attribute specifies whether the reader should attempt to track unhandled identifiers in the document, and then resolve them when parsing is over. This can be a huge performance hit if you know that all identifiers wil not resolve.

Default Value: false

INSTANCE METHODS

$self->read($file_name)

This method will open the MAGE-ML file specified by $file_name and if the handler attribute is not set, it will create either a SAX2 parser or a SAX1 parser (depending on the value of the C <sax1> attribute) and parse the file.

read() can read from STDIN by specifying '-' as the filename. This enables you to handle compressed XML files:

  gzip -dc file.xml.gz | read.pl [options]