Alasdair Allan

NAME

Astro::VO::VOEvent - Object interface to parse and create VOEvent messages

SYNOPSIS

To parse a VOEvent file,

   $object = new Astro::VO::VOEvent( File => $file_name );
  

or

   $object = new Astro::VO::VOEvent( XML => $scalar );
   

Or to build a VOEVENT file,

   $xml = $object->build( %hash );
 

DESCRIPTION

The module can parse VOEvent messages, and serves as a limited convenience layer for building new messages. Functionality is currently very limited.

REVISION

$Id: VOEvent.pm,v 1.29 2006/11/17 16:54:40 voevent Exp $

METHODS

Constructor

new

Create a new instance from a hash of options

  $object = new Astro::VO::VOEvent( );

returns a reference to an VOEvent object.

Accessor Methods

build

Build a VOEvent document

  $xml = $object->build( Type       => $string,
                         Role       => $string,
                         ID         => $url,
                         Reference => { URL => $url, Type => $string } );

or

  $xml = $object->build( Type        => $string,
                         Role        => $string,
                         ID          => $url,
                         Description => $string,
                         Citations   => [ { ID   => $strig,
                                            Cite => $string },
                                              .
                                              .
                                              .
                                          { ID   => $string,
                                            Cite => $string }],
                         Who        => { Publisher => $url,
                                          Contact => { Name      => $string,
                                                       Institution => $string,
                                                       Address   => $string,
                                                       Telephone => $string,
                                                       Email     => $string, },
                                          Date    => $string },
                         WhereWhen   => { RA    => $ra,
                                          Dec   => $dec,
                                          Error => $error,
                                          Time  => $time },
                         How         => { Name     => $string,
                                          Location => $string,
                                          RTML     => $url,
                                          Reference => { URL => $url, 
                                                         Type => $string,
                                                         Name => $string } }, 
                         What        => [ { Name  => $strig,
                                            UCD   => $string,
                                            Value => $string },
                                              .
                                              .
                                              .
                                          { Name  => $string,
                                            UCD   => $string,
                                            Value => $string } ],
                         Why  => [ {Inference => { 
                                                   Probability  => $string,
                                                   Relation     => $string,
                                                   Name         => string
                                                   Concept      => string }},
                                                       .
                                                       .
                                                       . 
                                   {Inference => { 
                                                   Probability  => $string,
                                                   Relation     => $string,
                                                   Name         => string
                                                   Concept      => string }},
                                                      .
                                                      .
                                                      . 
                                   {Name => $string},
                                   {Concept => $string }  }
                       );
                         
  

this will create a document from the options passed to the method, most of the hash keys are optional and if missed out the relevant keywords will be blank or missing entirely from the built document. Type, Role, ID and either Reference or WhereWhen (and their sub-tags) are mandatory.

The <Group> tag can be utilised from within the <What> tag as follows

                         What => [ { Group => [ { Name  => $string,
                                                UCD   => $string,
                                                Value => $string,
                                                Units => $string }, 
                                                  .
                                                  .
                                                  .
                                              { Name  => $string,
                                                UCD   => $string,
                                                Value => $string,
                                                Units => $string } ], },
                                  { Group => [ { Name  => $string,
                                                UCD   => $string,
                                                Value => $string,
                                                Units => $string },
                                                  .
                                                  .
                                                  .
                                              { Name  => $string,
                                                UCD   => $string,
                                                Value => $string,
                                                Units => $string } ], },
                                  { Name  => $string,
                                    UCD   => $string,
                                    Value => $string,
                                    Units => $string },
                                      .
                                      .
                                      .
                                  { Name  => $string,
                                    UCD   => $string,
                                    Value => $string,
                                    Units => $string } ],

this will probably NOT be the final API for the build() method, as it is overly complex. It is probably one or more convenience methods will be put ontop of this routine to make it easier to use. See the t/2_simple.t file in the test suite for an example which makes use of the complex form of the What tag above.

NB: This is the low level interface to build a message, this is subject to change without notice as higher level "easier to use" accessor methods are added to the module. It may eventually be reclassified as a PRIVATE method.

id

Return the id of the VOEvent document

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $id = $object->id();
  
role

Return the role of the VOEvent document

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $id = $object->role();
  
version

Return the version of the VOEvent document

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $version = $object->version();
  
description

Return the human readable description from the VOEvent document

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $string = $object->description();
  
B{ra}

Return the RA of the object as given in the <WhereWhen> tag

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $ra = $object->ra();
B{dec}

Return the Dec of the object as given in the <WhereWhen> tag

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $dec = $object->dec();
B{epoch}

Return the Dec of the object as given in the <WhereWhen> tag

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $epoch = $object->epoch();
B{equinox}

Return the Dec of the object as given in the <WhereWhen> tag

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $equinox = $object->equinox();
B{time}

Return the Time of the object as given in the <WhereWhen> tag

  $object = new Astro::VO::VOEvent( XML => $scalar );
  $time = $object->time();
B{what}

Return the <Param> and <Group>'s of <Param>s in the <What> tag,

  $object = new Astro::VO::VOEvent( XML => $scalar );
  %what = $object->what();

General Methods

configure

Configures the object, takes an options hash as an argument

  $rtml->configure( %options );

does nothing if the hash is not supplied.

COPYRIGHT

Copyright (C) 2002 University of Exeter. All Rights Reserved.

This program was written as part of the eSTAR project and is free software; you can redistribute it and/or modify it under the terms of the GNU Public License.

AUTHORS

Alasdair Allan <aa@astro.ex.ac.uk>,