NAME
DbCrossRefs.pm (0.04.1) - A Perl module to manage cross-reference database links
SYNOPSIS
use DbCrossRefs;
$db_object = new DbCrossRefs;
$db_object->open("database_file.db", "db");
$url_link = $db_object->get("SOME_DATABASE", "$ac", "$second_id")
if $db_object->check("SOME_DATABASE");
$db_object->add("NEW_DATABASE", "http://www.somewhere.org/displayer?ac={0}&sp={1}")
unless $db_object->exists("NEW_DATABASE");
$db_object->commit;
$db_object->export_file("database.txt", "txt");
%db_refs = $db_object->get_all();
$linkValidator = $db_object->check();
$db_object = undef;
DESCRIPTION
DbCrossRefs.pm provides methods to :
- create, manage and read files listing cross-reference database links in both text and DBM format
- check for the availability of the links
- export and import files
EXCEPTIONS
exceptions are confessed (for failed calls / invalid or missing arguments)
or warned (for data dependant conflicts)
METHODS
$db_object = new DbCrossRefs ([file_name] [, file_format = {"txt" | db"}])
Constructor:
Creates a new object and opens an already existing or a not existing yet file
for future operations if file_name is given.
The file_format determines which type of file to open and work with
(either "txt" for text files, or "db" for DBM database files).
If not given, file_format is "txt" by default.
Alternative:
By default, databases names are case sensitive.
In order to work with case insensitivity, create your new object with:
$db_object = new DbCrossRefs("case_insensitive")
Then use the "open" method to open your file.
Tip: use the "export_file" method rather than the "commit" method
to preserve case sensitivity in your original file.
$db_object->open ([file_name [, file_format = {"txt" | "db"}]])
Purpose:
Opens an already existing or a not existing yet file for future operations
if file_name is given. The file_format determines which type
of file to open and work with (either "txt" for text files, or "db" for
DBM database files). If no argument is given, a temporary file is
used instead. This method is required to execute any subsequent method,
and it always overrides its own previous value. If file_name exists,
all databases that it contains are loaded into the current databases list.
Returns:
- 1 if it succeeds
- confess exception if not
$db_object->add (database, url [, comment] [, check= 1])
Purpose:
Adds an new database with its corresponding url to the current databases
list. The database name should not include spaces.
It will be converted to lower case if the "case_insensitive" flag is activated.
The url should point to an approriate URL to display entries from this database.
To be able to pass GET arguments to this URL, include into the GET string incremental
values between braces. Start from '0' to as many parameters as you wish. e.g.
"http://www.somewhere/cgi-bin/some_displayer?accession_number={0}&species={1}"
Any parameter may be given a default value by following it's number with colons and an
existing identifier. Those identifiers will then be used to check if the URL is valid
(in conjunction with the 'cehck' method), e.g.
"http://www.somewhere/cgi-bin/some_displayer?accession_number={0:P12345}&species={1:9604}"
Comments are free text and will be automatically prefixed by a '#' sign
followed by the database name between brackets. In DBM format, all comments
will be grouped together and will share the same common key ( "_comment_").
If you define a fourth parameter (e.g check set to 1), the url
you provide will be checked first via a HTTP connection before it is allowed
to be added.
Returns:
- 1 if it succeeds to add database
- undef if it fails, if no file has been opened or if database already
exists
- confess exception for missing / wrong arguments
$db_object->alter (database, new_url [, comment] [, check = 1])
Purpose:
Changes the current URL of an already existing database to new_url
(see the 'add' method for a description of URL syntax).
Returns:
- 1 if it succeeds
- undef if it fails or if no file has been opened
- confess exception for missing / wrong arguments
$db_object->alter_name (old_database_name, new_database_name)
Purpose:
Chenges a database name (old_database_name) to new_database_name.
Returns:
- 1 if it succeeds
- undef if it fails or if no file has been opened
- confess exception for missing arguments
$db_object->delete (database)
Purpose:
Deletes a database from the current list.
Returns:
- 1 if it succeeds
- 0 if no database with this name could be found
- undef if no file has been opened
- confess exception for missing /wrong arguments
$db_object->exists (database_1 [, database_2] ... [, database_n])
Purpose:
Checks if one or several databases exist already in the current list
Returns:
- 1 if all the databases exist
- 0 if one or more databases do not exist
- undef if no file has been opened
- confess exception for missing / wrong arguments
$db_object->get (database [, identifier_1] [, identifier_2] ... [, identifier_n])
Purpose:
Gets the URL corresponding to an already existing database. Identifiers
will be inserted into the arguemnt string in replacement of the corresponding
'{n-1}' substring. e.g. (cf. the $db_object->add method)
$url = $db_object->get("SOME_DATABASE", "P12345", "12000");
print $url;
=>
http://www.somewhere/cgi-bin/some_displayer?accession_number=P12345&species=12000
Returns:
- a string if succeeds
- undef if it fails or if no file has been opened
- confess exception for wrong arguments
$db_object->get_all ([format = {"txt"}], [expression])
Purpose:
Gets a list of all databases in the current list. If no argument is
given, a hash is sent with databases names for keys and URLs for values.
If a "txt" format is requested, a string of several lines is sent,
each line beginning with a database name, followed by a space, and ending
with the corresponding URL.
You can limit your query to list databases that contain 'expression' in
their name by defining a second argument (search will be case insensitive).
Returns:
- a hash if no argument is given
- a string if "txt" is given as argument
- undef if no file has been opened
- confess exception for missing / wrong arguments
$db_object->get_comment ([expression_1] ... [, expression_n]))
Purpose:
Gets all comments (if no argument) or comments containing any of the
arguments (usually database names).
Returns:
- a string it succeeds
- undef if expressions are not alphanumerical or if no file has been
opened
$db_object->check ([database_1] ... [, database_n])
Purpose:
Checks for the vailidity of the URLs for all the databases included
in the current list (when no argument is specified). The checking is limited
to the specified databases if they are given as arguments.
Many URLs would require some existing identifiers in their GET string to be correctly
checked. Refer to the 'add' method on how to add default identifiers.
Returns:
- a void string if all databases URLs have been checked with success
- a non void string containig HTTP connection errors if one or more
databases failed to connect correctly
- undef if Perl is lower than 5.005 version or if no file has been opened
$db_object->import_file (file_name [, file_format = {"txt" | db"}])
Purpose:
Imports databases and their corresponding URLs an d comments from an
existing file to the current databases list. If file_format is not
given, the format is supposed to be "txt" (cf. the <open> method
for more details)
Returns:
- 1 if it succeeds
- undef if it fails or if no file has been opened
- confess exception for missing / wrong arguments
$db_object->export_file (file_name [, file_format = {"txt" | db"}])
Purpose:
Exports databases and their corresponding URLs and comments from the
current databases list to a new file. If file_format is not given,
the format is supposed to be "txt" (cf. the <open> method for
more details).
Returns:
- 1 if it succeeds
- undef if it fails or if no file has been opened
- confess exception for missing / wrong arguments
$db_object->reset ()
Purpose:
Resets the current lists to its initial state as it was just after
the last invoked <open> method. All modifications or additions applied
to this list will be definitively lost.
Returns:
- 1 if it succeeds
- undef for wrong arguments or if no file has been opened
$db_object->commit ([file_name [, file_format = {"txt"|"db"}]])
Purpose:
No changes are saved into the original file before invoking this method.
When called, this method saves physically the current databases list, with all the applied
modifications and additions, to the initial file given with the <open> method. If file_name
is specifeid, the list will be saved in this file instead of the initial
opened one. file_name is also required if the <open> method
has been invoked without a file name argument.
Returns:
- 1 if it succeeds
- undef if it fails or if no file has been opened
- confess exception for missing arguments
$db_object = undef
Purpose:
OVERRIDDEN METHODS (when using Expasy.pm on the ExPASy servers)
warn($message)
from : |
perlfunc |
action : |
Writes the error message and the stack trace into $GL_logs/cgi_log
and an e-mail message sent to http@hostname no more than every 30 minutes
(or 2 hours during the night and weekend GMT). |
overrides : |
warn() [which can still be called with CORE::warn()] |
NOTES
This module uses the mechanism of exceptions (confession), which are thrown
from the calling routine up the stack trace and cause a die() unless caught.
Therefore, methods which throw exceptions maybe be called within an eval{}
block. The special variable $@ can then be checked for an error message.
AUTHOR
Khaled Mostaguir (khaled.mostaguir@isb-sib.ch)
|