Aranea-modules-tutorial

CONTENTS


Purpose

This tutorial provides an overview on how to create Aranea modules.


Description

An Aranea module is a Perl module that provides one procedure, doModule, whose only argument is an Aranea XML object and returns an Aranea XML object. In addition, each Aranea module has the ability to run stand-alone from the command-line, in which case it expects the Aranea XML object from STDIN and prints the XML to STDOUT.

Here is the skeleton of an Aranea module:


 package Aranea::Modules::Template;
 
 use strict;
 use warnings;
 
 use lib qw(libraries/lib);
 use lib qw(pm);
 
 use Aranea::XML::Aranea;
 
 unless ( caller() ) {
     my $stdin = new_from_fd IO::Handle(fileno(STDIN),"r");
     my $Aranea = Aranea::XML::Aranea->new($stdin);
 
     $Aranea = doModule($Aranea);
 
     $Aranea->write_xml();
 }
 
 sub doModule {
     my $Aranea = shift;
 
     $Aranea->insert_pipeline_tag('$Id: Aranea-modules-tutorial.pod,v 1.1 2004/12/30 06:11:09 jimmylin Exp $ ');
     
     # here is the code to actually do something
 
     return $Aranea;
 }
 
 1;

The following fragment is responsible for handling the behavior of the module if it is called from the command line. After reading from STDIN, an Aranea XML object is created and then passed to doModule, which performs the work. After that procedure returns, the Aranea XML object is converted back into XML output on STDOUT.


 unless ( caller() ) {
     my $stdin = new_from_fd IO::Handle(fileno(STDIN),"r");
     my $Aranea = Aranea::XML::Aranea->new($stdin);
 
     $Aranea = doModule($Aranea);
 
     $Aranea->write_xml();
 }

The following fragment shows exactly what the doModule procedure should look like:


 sub doModule {
     my $Aranea = shift;
 
     $Aranea->insert_pipeline_tag('$Id: Aranea-modules-tutorial.pod,v 1.1 2004/12/30 06:11:09 jimmylin Exp $ ');
     
     # here is the code to actually do something
 
     return $Aranea;
 }

The only argument to the procedure is the Aranea XML object, which it returns at the end. Typically, each module also inserts an ID (the CVS keyword dollarsignIDdollarsign), so that the Aranea XML object can keep track of the sequence of modules that was executed.