git.rot13.org Git - webpac/blob - openisis/perl/OpenIsis.pm

   1 #
   2 #/*
   3 #       openisis - an open implementation of the CDS/ISIS database
   4 #       Version 0.8.x (patchlevel see file Version)
   5 #       Copyright (C) 2001-2003 by Erik Grziwotz, erik@openisis.org
   6 #
   7 #       This library is free software; you can redistribute it and/or
   8 #       modify it under the terms of the GNU Lesser General Public
   9 #       License as published by the Free Software Foundation; either
  10 #       version 2.1 of the License, or (at your option) any later version.
  11 #
  12 #       This library is distributed in the hope that it will be useful,
  13 #       but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 #       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 #       Lesser General Public License for more details.
  16 #
  17 #       You should have received a copy of the GNU Lesser General Public
  18 #       License along with this library; if not, write to the Free Software
  19 #       Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20 #
  21 #       see README for more information
  22 #EOH */
  23 #
  24 #       $Id: OpenIsis.pm,v 1.3 2003/04/08 00:20:53 kripke Exp $
  25 #       perl module wrapper for openisis perl XSUB
  26 #
  27 package OpenIsis;
  28
  29 use strict;
  30 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  31
  32 require Exporter;
  33 require DynaLoader;
  34 # require AutoLoader;
  35
  36 @ISA = qw(Exporter DynaLoader);
  37 # Items to export into callers namespace by default. Note: do not export
  38 # names by default without a very good reason. Use EXPORT_OK instead.
  39 # Do not simply export all your public functions/methods/constants.
  40 @EXPORT = qw(
  41
  42 );
  43 $VERSION = '0.874';
  44
  45 bootstrap OpenIsis $VERSION;
  46
  47 # query mode constants
  48 *QRY_KEYEQ = \0;
  49 *QRY_KEYPF = \1;
  50 *QRY_KEYAT = \2;
  51 *QRY_SCANE = \64;
  52 *QRY_SCANC = \65;
  53 *QRY_SIMPLE = \128;
  54 *QRY_PROPER = \129;
  55
  56 #       error constants
  57 *ERR_EOF   = \-1;
  58 *ERR_FAULT = \-2;
  59 *ERR_INVAL = \-3;
  60 *ERR_BADF  = \-4;
  61 *ERR_IO    = \-5;
  62 *ERR_NOMEM = \-6;
  63 *ERR_BUSY  = \-7;
  64 *ERR_TRASH = \-8;
  65 *ERR_IDIOT = \-9;
  66
  67 #       loglevel constants
  68 *LOG_OFF     = \0;
  69 *LOG_FATAL   = \1;
  70 *LOG_SYSERR  = \2;
  71 *LOG_IOERR   = \3;
  72 *LOG_ERROR   = \4;
  73 *LOG_WARN    = \5;
  74 *LOG_INFO    = \6;
  75 *LOG_VERBOSE = \7;
  76 *LOG_TRACE   = \8;
  77 *LOG_DEBUG   = \9;
  78 *LOG_ALL     = \10;
  79
  80 # Preloaded methods go here.
  81
  82 sub MHL {
  83         for ( @_ ) {
  84                 s/(<[^=>]*)=[^>]+>/$1>/g; # dump <a=b> substitutions
  85                 s/></; /g; # replace >< pairs
  86                 s/[><]//g; # nuke other ><
  87                 s/^\^.//; # kill initial subfield spec
  88                 s/\^a/; /; # ^a -> ;
  89                 s/\^[b-i]/, /g; # ^[b-i] -> ,
  90                 s/\^./. /g; # others -> .
  91         }
  92 }
  93
  94 # Autoload methods go after =cut, and are processed by the autosplit program.
  95
  96 1;
  97 __END__
  98 # Below is the stub of documentation for the OpenIsis module.
  99
 100 =head1 NAME
 101
 102 OpenIsis - Perl extension for accessing ISIS databases
 103
 104 =head1 SYNOPSIS
 105
 106   use OpenIsis;
 107   $db = OpenIsis::open( 'basename', '-dbpath', '/home/me/mydb' );
 108         $maxmfn = OpenIsis::maxRowid( $db );
 109         for (OpenIsis::query( $db, 'plant * water' )) {
 110                 my $row = OpenIsis::read( $db, $_ ); # get hashref
 111                 $row = OpenIsis::read( $db, $_, 'MHL V24,V26,V71' ); # read formatted
 112                 my $v24 = $row->{'24'}; # field tags map to arrayrefs
 113                 OpenIsis::MHL( @$v24 ); # apply heading mode to array
 114                 print $row->{'mfn'}, "TITLE :", join("\n   ", @$v24 ), "\n";
 115                 my $v30 = $row->{'30'}->[0]; # contents is like ^ap. 233-238 ^billus.
 116                 my $subfields = OpenIsis::subfields( $v30 ); # get subfield values
 117                 print "a = ", $subfields->{'a'}, " b = ", $subfields->{'b'}, "\n";
 118         }
 119         # print terms starting with A
 120         print join('; ',OpenIsis::terms( $db, 'a$' )), "\n";
 121
 122 =head1 DESCRIPTION
 123
 124 The OpenIsis perl extension provides access to ISIS databases
 125 based on the openisis C library.
 126
 127
 128 =over 4
 129
 130 =item OpenIsis::open( name [, args ...] )
 131
 132 Open a CDS/Isis data base.
 133
 134 name: basename of a CDS/Isis database.
 135 If given, will be prepended, and the Isis file extensions appended
 136 to build the actual filename. Depending on the value of dbname and
 137 location of files, this may need to include a path. Dbname may be NULL,
 138 if argv includes a dbname argument.
 139
 140 args: array of names and values; may be empty.
 141 Contains parameters names, which may be prefixed by a dash
 142 ('-'). Depending on the actual parameter, the next string may or must
 143 contain a corresponding parameter value. An optional parameter value
 144 may be omitted, if at end of argv or the next name is prefixed with a
 145 dash. To avoid ambiguity, values never start with a dash.
 146 Unrecognized parameter names are ignored.
 147
 148 Possible values:
 149
 150         -db: basename of database; same as param name;
 151         -dbpath: path to database;
 152         usefull when opening secondary indexes or other files
 153         whose names are not based on the db basename;
 154         -v: set verbosity level.
 155
 156 return value:
 157
 158         non-negative number (dbid)Success
 159         OpenIsis::ERR_NOENT
 160         OpenIsis::ERR_BADF
 161
 162 examples:
 163
 164         $db = OpenIsis::open( 'cds', '-dbpath', '/var/db/cds/' );
 165         $db = OpenIsis::open( '/var/db/cds/cds' );
 166         $db = OpenIsis::open( '/var/db/cds/cds', '-v', -1 );
 167         if ( 0 <= $db ) {
 168                 print "ok";
 169         } elsif ( OpenIsis::ERR_BADF == $db ) {
 170                 print STDERR "/var/db/cds/cds does not exist\n";
 171         } elsif ( OpenIsis::ERR_IO == $db ) {
 172                 print STDERR "/var/db/cds/cds is not accessible\n";
 173         } else {
 174                 print STDERR "/var/db/cds/cds had strange error $db\n";
 175         }
 176
 177 see also:Query; Terms; Maxrowid
 178 type:Database
 179
 180
 181 =item OpenIsis::maxRowid( $db )
 182
 183 Get highest rowid (a.k.a. MFN) in data base.
 184
 185 dbid: Data base identifier returned by open
 186
 187 return value:
 188
 189         positive number correspondent highest rowid
 190         ZERO  unknown value
 191         negative number Error
 192
 193 examples:
 194
 195         $db = OpenIsis::open( $base );
 196         $maxmfn = OpenIsis::maxRowid( $db );
 197
 198 see also:Open
 199 type:Database
 200
 201 =item OpenIsis::query( $db, $qry )
 202
 203 =item OpenIsis::terms( $db, $key )
 204
 205 =item OpenIsis::read( $db, $rowid [, pft] )
 206
 207 =item OpenIsis::2html( $str )
 208
 209 =item OpenIsis::subfields( $str )
 210
 211 =item OpenIsis::log( $level, $filename )
 212
 213 set logging level to a number between 0 (no logging) and 10 (lots of log).
 214 A filename for logging output is currently ignored.
 215
 216 =item OpenIsis::MHL( ... )
 217
 218 =back
 219
 220 =head1 AUTHOR
 221
 222 Erik Grziwotz, erik@openisis.org
 223
 224 Documentation added by Paulo Cattelan, cattelan@control.com.br
 225
 226 =head1 SEE ALSO
 227
 228 L<perl(1)>.
 229
 230 =cut