NAME

Bio::ToolBox::db_helper::config

DESCRIPTION

This module accesses the biotoolbox configuration file. This file stores multiple database connection settings. It also stores the paths to various helper applications.

The default location for the file is in the user's home directory. Alternatively, the location of the file may be referenced through an Environment setting under the key BIOTOOLBOX.

Versions prior to 1.54 automatically wrote a config file in every user's home directory, whether it was needed or wanted or not. With version 1.54, a config file is only written when necessary by adding a program path or database entry.

The file is intended to be edited by the user for their custom installation. The file is a simple INI style text file. The format is detailed below.

FORMAT

The BioToolBox configuration file .biotoolbox.cfg is a simple INI-style text file. Blocks of settings begin with a [header] line, followed by lines of key = value. The value may be single text or comma delimited lists. Examples of settings include the following.

default_db

These are default settings that are shared by all databases.

  [default_db]
  user                     = nobody
  pass                     = hello
  adaptor                  = DBI::mysql
  dsn_prefix               = dbi:mysql:

The user and password keys are for authenticating to a relational database. WARNING! For sanity and security sake, please, PLEASE, generate a read-only user for relational database access. Do NOT use a privileged account. Any password written here is for all to see and is merely a convenience.

The adaptor key specifies the module driver for connecting to the relational database containing the Bio::DB::SeqFeature::Store database. Acceptable values include DBI::mysql, DBI::Pg, or DBI::SQLite.

The dsn key defines the string for connecting to the database. For example, to connect to a mysql database 'genome' on localhost through a socket

        dbi:mysql:genome

to connect to a remote mysql database

        dbi:mysql:host=127.0.0.1;port=3306;database=genome

The dsn_prefix key simply drops the database name, allowing it to be used with any database name.

See the documentation for Bio::DB::SeqFeature::Store for syntax of adaptor and dsn_prefix keys.

Multiple database sections may be included. Simply name the section after the name of the database. Database specific keys may be included, and missing keys will default to the default_db values.

Applications

Some BioToolBox scripts require helper programs. Enter the name of the helper program and the full path of its location. Executable programs may also be automatically found in the system path.

  [applications]
  wigToBigWig      = /usr/local/bin/wigToBigWig
  bedToBigBed      = /usr/local/bin/bedToBigBed

USAGE

The module exports a single Config::Simple object ($BTB_CONFIG) representing the biotoolbox settings in the configuration file. Please refer to the documentation for Config::Simple for usage.

If an existing configuration file is not present, then it will write a new default file in the user's home directory. I make the assumption that the user has write privileges in their own home directory. It will fail otherwise.

Two subroutines may be optionally exported for assistance in manipulating the configuration file.

add_database

Easily add a new database configuration block to the file. Pass an array of key => values to be added as a new configuration block. You must include a name => short name to label the block. This should be unique in the file, if you are adding a new database. Otherwise, it will probably clobber the pre-existing configuration block (which may be what you want it to do). Follow the FORMAT examples for details on what to provide.

It will attempt to rewrite the configuration file, if the user has write privileges. If not, then it will attempt to write a new file in the user's home root directory. It will return true upon success.

   my $success = add_database(
      'name'    => 'hg19',
      'adaptor' => 'DBI::SQLite',
      'dsn'     => '/path/to/hg19.sqlite',
   );
add_program

Easily add the path to a binary executable for future reference. This is a little bit faster to find in here than searching for it through the system PATH.

It will attempt to rewrite the configuration file, if the user has write privileges. If not, then it will attempt to write a new file in the user's home root directory. It will return true upon success.

   my $success = add_program('/path/to/wigToBigWig');

SEE ALSO

Bio::ToolBox::Data, Bio::ToolBox::db_helper

AUTHOR

 Timothy J. Parnell, PhD
 Howard Hughes Medical Institute
 Dept of Oncological Sciences
 Huntsman Cancer Institute
 University of Utah
 Salt Lake City, UT, 84112

This package is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.