file: README		I. Henry and G. Moody	 August 2005
			Last revised:		10 March 2006

Name: wfdb-perl -- WFDB wrappers for Perl 5

Purpose:

The WFDB library (http://physionet.org/physiotools/wfdb.shtml) provides uniform
access to digitized signals and annotations in a wide variety of formats,
including those in PhysioBank (http://physionet.org/physiobank/).  The WFDB
library is written in C and includes bindings for C++ and wrappers for Fortran.

This package provides an interface that allows use of the WFDB library
functions from Perl 5 programs.

Authors:

Isaac Henry (ihenry@physionet.org), George Moody (george@physionet.org)

Background literature:

The SWIG web site (http://www.swig.org/)
The WFDB Programmer's Guide (http://www.physionet.org/physiotools/wpg/)

Platforms:

GNU/Linux (development) Mac OS X, MS Windows.  Other platforms supported by
SWIG should also work but have not been tested.

Code organization:

This is a subpackage of wfdb-swig (see ../README).  The file named Makefile
invokes 'perl Makefile.PL' to generate a customized 'make' description file
that manages the build and installation processes (see INSTALL).  The wrappers
themselves are generated by SWIG from ../wfdb.i.

URLs:
   code:
	http://physionet.org/wfdb-swig/wfdb-perl
	http://physionet.org/wfdb-swig/wfdb.i
   test scripts and data:
	http://physionet.org/wfdb-swig/examples/*.pl
   docs:
	The WFDB Programmer's Guide (http://physionet.org/physiotools/wpg/);
	also see the notes below

Installation and Testing:

See INSTALL, in this directory.

_______________________________________________________________________

A Trivial Example Program in Perl

This program is a translation to Perl of Example 2 from the WFDB Programmer's
Guide (http://physionet.org/physiotools/wpg/).  It translates the `atr'
annotations for the record named in its argument into an AHA-format annotation
file with the annotator name `aha'.

  package wfdb;
  use wfdb;

  $an = new wfdb::WFDB_AnninfoArray(2);
  $annot = new wfdb::WFDB_Annotation;
  if ( @ARGV < 1 ) {
      print STDERR "usage: ", $0, " record\n";
      exit(1);
  }
  $a = $an->getitem(0);
  $a->{name} = "atr"; $a->{stat} = $WFDB_READ;
  $an->setitem(0,$a);
  $a = $an->getitem(1);
  $a->{name} = "aha"; $a->{stat} = $WFDB_AHA_WRITE;
  $an->setitem(1,$a);
  exit(2) if (annopen($ARGV[0], $an->cast(), 2) < 0);
  L: goto L while (getann(0, $annot) == 0 && putann(0, $annot) == 0);
  wfdbquit();

First, note that all programs that use the WFDB wrappers for Perl must
include the statements:

  package wfdb;
  use wfdb;

which import the WFDB perl interface and make the WFDB functions available for
your use.

The functions used in this example are described in detail in the WFDB
Programmer's Guide. For now note that wfdb.annopen prepares a record to read by
wfdb.getann, which reads an annotation each time it is called. Also notice that
WFDB constants are special static variables.

The WFDB data types are described in the WFDB Programmer's Guide. In Perl, each
WFDB structure is paired with an accessor class that allows you to work with
pointers to the native C structures in memory.  These classes are often
refereed to as "shadow classes".

In addition, there are several 'Array' special classes, which are used in place
of pointer arrays in C.  Note that the 'cast' method must be used when passing
an 'Array' object to a method, as in

  annopen(ARGV[0], $an->cast(), 2)

The items in the 'Array' object can be accessed using the 'getitem' and
'setitem' methods.  Special care must be taken when manipulating the members of
an array. As shown in the example, you must first obtain a shadow class object
for an item using 'getitem',

  $a = $an->getitem(0);

which can then be used to get or set structure members. 

  $a->{name} = "atr"; $a->{stat} = $WFDB_READ;

Take special note that you must use 'setitem' to copy your changes back to the
array.

  $an->setitem(0,$a);

This may seem unintuitive, but remember that the Array classes only manipulate
underlying C structures.

A ready-to-run copy of this program is available as ../examples/example2.pl.
To run it, type
	perl ../examples/example2.pl
or (if perl is installed as /usr/bin/perl):
	../examples/example2.pl
The ../examples directory also contains translations into Perl 5 of the other
examples from the WFDB Programmer's Guide.