MAGE::...:Reader(3pm)

💖 NAME 💖

Bestie, meet Bio::MAGE::XML::Reader — a module for exporting MAGE-ML. Yes, the name says "Reader" and the one-liner says "exporting," and honestly? It contains multitudes. We don't question it. 🌈

This page lives in the perl manual, section 3pm — you know, the User Contributed Perl Documentation corner of the world. Pull up a chair. 🫶

---

✨ SYNOPSIS ✨

Okay so here's the whole vibe, verbatim, no notes:

use Bio::MAGE::XML::Reader;

my $reader = Bio::MAGE::XML::Reader->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();

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

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

Look at her go. That's the whole tour right there. 👑

---

🌸 DESCRIPTION 🌸

Methods for transforming information from a MAGE-OM objects into MAGE-ML. That's the job. That's the assignment. And she ate. 💅

🎀 ATTRIBUTE METHODS 🎀

These methods have a polymorphic setter/getter thing going on — one method, two moods. It sets an attribute that affects the parsing of MAGE-ML. Give it a value and it saves that value to the attribute; call it with no argument and it hands you back the current value of that attribute. Iconic behaviour, honestly.

All of these attributes can be set right in the call to the constructor using the named parameter style. So you can just... tell her everything up front. Main character energy.

sax1

This attribute decides whether a SAX1 parser and DocumentHandler gets used, or a SAX2XMLReader and a ContentHandler. The default is to use a SAX2 parser. Periodt.

handler

If your app needs a custom handler, you can set this attribute in the call to the constructor. Now listen — it is advised that the object use inherit either from Bio::MAGE::XML::Handler::ContentHandler (if you're on SAX2) or Bio::MAGE::DocumentHandler if using SAX1. And whatever class you end up using? It needs to implement these methods:

• verbose — called with the integer parameter that specifies the desired level of output
• log_file — called with the file handle to which output should be sent
• init — called during the constructor for any needed work

parser

Here's the little pod block for it, exactly as she comes:

 Title   : parser
 Usage   : $obj->parser($newval)
 Function:
 Example :
 Returns : value of parser (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

Note the Function: and Example : lines are just... empty. She's mysterious like that. 🙈

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. More numbers, more yapping. 📢

log_file

This attribute specifies a file handle to which parse output will be directed. It's only needed if verbose is positive — no output, no destination, bestie. 🤷

external_data($bool)

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

Default Value: false

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. Heads up though: this can be a huge performance hit if you know that all identifiers wil not resolve. (Yes, "wil." Typo's not mine, it's hers. We love her anyway. 💀)

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.

And get this — read() can read from STDIN by specifying - as the filename. Which means you can absolutely handle compressed XML files:

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

Piping gzipped XML straight into the parser? Obsessed. Genuinely. 🧚

---

😭 POD ERRORS 😭

Hey! The above document had some coding errors, which are explained below:

• Around line 172: You forgot a '=back' before '=head2'
• Around line 190: '=item' outside of any '=over'

Not her getting caught slipping in her own docs. 💀 The =back and =over are fighting for their lives. It's giving "I'll fix it later." She will not fix it later. 🙈

---

And that's the whole page, bestie. Written under perl v5.32.0, dated 2020-12-01. Go parse something cute. 🌸💖✨