MAGE::...:Writer(3pm)

💖 MAGE::...:Writer 💖

okay bestie, welcome to the User Contributed Perl Documentation page for MAGE::...:Writer(3pm) — aka Bio::MAGE::XML::Writer 🦋. it's the little Perl module that takes your MAGE-OM objects and serves them as MAGE-ML. it's giving exporter energy, it's giving XML realness, and we are obsessed. ✨

---

🌸 NAME 🌸

Bio::MAGE::XML::Writer — a module for exporting MAGE-ML 💅

---

✨ SYNOPSIS ✨

so here's the whole vibe, copy-paste ready, no notes:

use Bio::MAGE::XMLUtils;

my $writer = Bio::MAGE::XML::Writer->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
#

# which format is the external data file
$writer->data_format($dataformat);

# 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();

ngl, that's a lot of little attribute-setting moments, but that's the whole API right there in one block. 🫶

---

🎀 DESCRIPTION 🎀

Methods for transforming information from a MAGE-OM objects into MAGE-ML. literally that's it, that's the job: MAGE-OM objects go in, MAGE-ML comes out. ✨

---

💅 METHODS 💅

write($MAGE_object)

write() prints the objects contained in $MAGE_object as MAGE-ML to the file handle used by the writer. that's the main character of this whole module fr fr. 👑

---

👑 ATTRIBUTE METHODS 👑

The following methods must all be invoked using an instance of Bio::MAGE::XML::Writer; (yes, an instance, you can't just yell them at the package, bestie 😭)

• 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) — controls the number of spaces that get added to the indent for every new level of elements.
  • Default Value: 2
• attrs_on_one_line($bool) — controls whether attribute values should be pretty-printed. if true, attributes will not be pretty-printed, and 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_indent of 1:

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

and the following illustrates an 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 will 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. (and yes bestie, the doc literally spells it public)_id with that little ) in there — we are not fixing it, we report what we see 💀)
  • 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 stored 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
• data_format($format) — $format is either 'tab delimited' or 'space delimited'
  • Default Value: 'tab delimited'
• 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 separate external data file for each data cube.

the external_data_dir controls what director those files are written to. (yes, "director" — that's the doc's word, we're leaving it 💀)

• 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 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

---

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below: (not us being messy, we're just the messenger 🙈)

• Around line 147:
  • '=item' outside of any '=over'
• Around line 656:
  • You forgot a '=back' before '=head1'
• Around line 660:
  • =over without closing =back

---

and that's the whole page, bestie 🫶 go forth and export your MAGE-ML with your indent levels exactly where you want them. this little love letter came to you courtesy of perl v5.32.0, dated 2020-12-01 💖✨🎀🦋