NAME

Astro::STSDAS::Table::Base - Base class for STSDAS Tables

SYNOPSIS

  use Astro::STSDAS::Table::Base;

  @isa = qw( Astro::STSDAS::Table::Base );

  sub new
  { 
    my $this = shift;
    my $class = ref($this) || $this;

    my $self = $class->SUPER::new();

    ...

    bless $self, $class;
  }

DESCRIPTION

Astro::STSDAS::Table::Base is a base class and should be sub-classed to derive any functionality. Astro::STSDAS::Table::Binary is a fully derived class which reads binary STSDAS tables.

Astro::STSDAS::Table::Base provides several methods and requires that the derived class provide the rest.

The base class constructor (which must be called by the derived class) creates a hash object. The following keys are reserved, and shouldn't be changed unless explicitly allowed.

fh

An IO::File object attached to the file.

pars

An Astro::STSDAS::Table::HeaderPars object, which must be initialized by the derived class. It is created by the base class.

cols

An Astro::STSDAS::Table::Columns object, which must be initialized by the derived class. It is created by the base class.

nrows

The number of rows in the table, if determinable. This is filled in by the derived class.

file

The table's filename. This is filled in by the base class.

mode

The mode in which the table was opened. This is filled in by the base class.

METHODS

Methods provided by the base class

new

The new method is the class constructor, and must be called before any other methods are invoked. It is usually invoked from the derived class as

        @ISA = ( Astro::STSDAS::Table::Base );
        ...
        $self = $class->SUPER->new();

open

  $table->open( file or filehandle [, mode] );

open connects to a file (if it is passed a scalar) or to an existing file handle (if it is passed a reference to a glob). If mode is not specified, it is opened as read only, otherwise that specified. Modes are the standard Perl-ish ones (see the Perl open command). If the mode is read only or read/write, it calls the _read_hdr method to read in the table header. This method must be provided by the derived class.

It returns true upon success, false otherwise.

close

explicitly close the table. This usually need not be called, as the file will be closed when the object is destroyed.

Methods provided by the derived class

These methods are not provided by the base class.

_read_hdr

  $table->_read_hdr;

This method is called by the open method. It should read the table header from $table->{fh}, parse it, and initialize the $table->{cols} and $table->{pars} objects. It should leave the file pointer at the beginning of the data.

read_rows_hash

  $rows = $tbl->read_rows_hash;

This method should read the table data from $table->{fh} (which will be positioned so that the table data is the next data available from it), digest the whole enchilada and return a reference to an array of hashes, one per row. The hash keys are the (lower cased) column names. Vector elements are stored as references to arrays containing the data.

For example, to access the value of column time in row 3,

        $rows->[2]{time}

read_rows_array

  $rows = $tbl->read_rows_array;

This method should read the table data from $table->{fh} (which will be positioned so that the table data is the next data available from it), digest the whole enchilada and return a reference to an array of arrays, one per row. Vector elements are stored as references to arrays containing the data.

For example, to access the value of column 9 in row 3,

        $rows->[3][9]

read_cols_hash

  $cols = $tbl->read_cols;

This method should read the table data from $table->{fh} (which will be positioned so that the table data is the next data available from it), digest the whole enchilada and return a reference to a hash, each element of which is a reference to an array containing data for a column. The hash keys are the (lower cased) column names. Vector elements are stored as references to arrays containing the data.

For example, to access the value of column time in row 3,

        $cols->{time}[2]

read_cols_array

  $cols = $tbl->read_cols_array

This method should read the table data from $table->{fh} (which will be positioned so that the table data is the next data available from it), digest the whole enchilada and return a reference to an array, each element of which is a reference to an array containing data for a column. Vector elements are stored as references to arrays containing the data.

For example, to access the value of column 9 in row 3,

        $cols->[9][3]

LICENSE

This software is released under the GNU General Public License. You may find a copy at

   http://www.fsf.org/copyleft/gpl.html

AUTHOR

Diab Jerius (djerius@cpan.org)