/ 
Bio-EnsEMBL-112.0.0_58
River stage zero No dependents
/ Bio::EnsEMBL::Utils::ConfParser

LICENSE

Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

NAME

Bio::EnsEMBL::Utils::ConfParser - configuration parser for perl scripts

SYNOPSIS

my $conf = new Bio::EnsEMBL::Utils::ConfParser(
  -SERVERROOT   => "/path/to/ensembl",
  -DEFAULT_CONF => "my.default.conf"
);

# parse options from configuration file and commandline
$conf->parse_options(
  'mandatory_string_opt=s' => 1,
  'optional_numeric_opt=n' => 0,
);

# get a paramter value
my $val = $conf->param('manadatory_string_op');

DESCRIPTION

This module parses a configuration file and the commandline options passed to a script (the latter superseed the former). Configuration files contain ini-file style name-value pairs, and the commandline options are passed to Getopt::Long for parsing.

The parameter values are consequently accessible via the param() method. You can also create a commandline string of all current parameters and their values to pass to another script.

new

Arg [SERVERROOT] :
              String $serverroot - root directory of your ensembl code
Arg [DEFAULT_CONF] :
              String $default_conf - default configuration file
Example     : my $conf = new Bio::EnsEMBL::Utils::ConfParser(
                -SERVERROOT => '/path/to/ensembl',
                -DEFAULT_CONF => 'my.default.conf'
              );
Description : object constructor
Return type : Bio::EnsEMBL::Utils::ConfParser object
Exceptions  : thrown if no serverroot is provided
Caller      : general
Status      : At Risk
            : under development

parse_options

Arg[1..n]   : pairs of option definitions and mandatory flag (see below for
              details)
Example     : $conf->parse_options(
                'mandatory_string_opt=s' => 1,
                'optional_numeric_opt=n' => 0,
              );
Description : This method reads options from an (optional) configuration file
              and parses the commandline options supplied by the user.
              Commandline options will superseed config file settings. The
              string "$SERVERROOT" in the configuration entries will be
              replaced by  the appropriate value.

              The arguments passed to this method are pairs of a Getopt::Long
              style option definition (in fact it will be passed to
              GetOptions() directly) and a flag indicating whether this
              option is mandatory (1) or optional (0).

              In addition to these user-defined options, a set of common
              options is always parsed. See _common_options() for details.
              
              If you run your script with --interactive the user will be
              asked to confirm the parameters after parsing.
              
              All parameters will then be accessible via $self->param('name').
Return type : true on success 
Exceptions  : thrown if configuration file can't be opened
              thrown on missing mandatory parameters
Caller      : general
Status      : At Risk
            : under development

confirm_params

Example     : $conf->confirm_params;
Description : If the script is run with the --interactive switch, this method
              prints a table of all parameters and their values and asks user
              to confirm if he wants to proceed.
Return type : true on success
Exceptions  : none
Caller      : parse_options()
Status      : At Risk
            : under development

param

Arg[1]      : Parameter name
Arg[2..n]   : (optional) List of values to set
Example     : # getter
              my $dbname = $conf->param('dbname');

              # setter
              $conf->param('port', 3306);
              $conf->param('chromosomes', 1, 6, 'X');
Description : Getter/setter for parameters. Accepts single-value params and
              list params.
Return type : Scalar value for single-value parameters, array of values for
              list parameters
Exceptions  : thrown if no parameter name is supplied
Caller      : general
Status      : At Risk
            : under development

is_true

Arg[1]      : Parameter name
Example     : unless ($conf->is_true('upload')) {
                print "Won't upload data.\n";
                next;
              }
Description : Checks whether a param value is set to 'true', which is defined
              here as TRUE (in the Perl sense) but not the string 'no'.
Return type : Boolean
Exceptions  : thrown if no parameter name is supplied
Caller      : general
Status      : At Risk
            : under development

list_params

Example     : print "Current parameter names:\n";
              foreach my $param (@{ $conf->list_params }) {
                print "  $param\n";
              }
Description : Returns a list of the currently available parameter names. The
              list will be in the same order as option definitions were
              passed to the new() method.
Return type : Arrayref of parameter names
Exceptions  : none
Caller      : list_param_values(), create_commandline_options()
Status      : At Risk
            : under development

list_param_values

Example     : print LOG $conf->list_param_values;
Description : prints a table of the parameters used in the script
Return type : String - the table to print
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

create_commandline_options

Arg[1..n]   : param/value pairs which should be added to or override the
              currently defined parameters
Example     : $conf->create_commandline_options(
                  'dbname' => 'homo_sapiens_vega_33_35e',
                  'interactive' => 0
              );
Description : Creates a commandline options string of all current paramters
              that can be passed to another script.
Return type : String - commandline options string
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

comma_to_list

Arg[1..n]   : list of parameter names to parse
Example     : $conf->comma_to_list('chromosomes');
Description : Transparently converts comma-separated lists into arrays (to
              allow different styles of commandline options, see perldoc
              Getopt::Long for details). Parameters are converted in place
              (accessible through $self->param('name')).
Return type : true on success
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

list_or_file

Arg[1]      : Name of parameter to parse
Example     : $conf->list_or_file('gene');
Description : Determines whether a parameter holds a list or it is a filename
              to read the list entries from.
Return type : true on success
Exceptions  : thrown if list file can't be opened
Caller      : general
Status      : At Risk
            : under development

serverroot

Arg[1]      : (optional) String - root directory of your ensembl checkout
Example     : my $serverroot = $conf->serverroot;
Description : Getter/setter for the root directory of your ensembl checkout.
Return type : String
Exceptions  : none
Caller      : new(), general
Status      : At Risk
            : under development

default_conf

Arg[1]      : (optional) String - default configuration file
Example     : $conf->default_conf('my.default.conf');
Description : Getter/setter for the default configuration file.
Return type : String
Exceptions  : none
Caller      : new(), general
Status      : At Risk
            : under development