Public Member Functions
public Bio::EnsEMBL::Utils::ConfParser	new ()

public Boolean	parse_options ()

protected	_common_options ()

public Boolean	confirm_params ()

public Scalar	param ()

public Boolean	is_true ()

public Arrayref	list_params ()

public String	list_param_values ()

public String	create_commandline_options ()

public Boolean	comma_to_list ()

public Boolean	list_or_file ()

public String	serverroot ()

public String	default_conf ()

Detailed Description

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.

Definition at line 41 of file ConfParser.pm.

Member Function Documentation

◆ _common_options()

protected Bio::EnsEMBL::Utils::ConfParser::_common_options ( )

Undocumented method

Code:

click to view

◆ comma_to_list()

public Boolean Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ confirm_params()

public Boolean Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ create_commandline_options()

public String Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ default_conf()

public String Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ is_true()

public Boolean Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ list_or_file()

public Boolean Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ list_param_values()

public String Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ list_params()

public Arrayref Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ new()

public Bio::EnsEMBL::Utils::ConfParser Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

◆ param()

public Scalar Bio::EnsEMBL::Utils::ConfParser::param ( )

  Arg[1]      : Parameter name
  Arg[2..n]   : (optional) List of values to set
  Example     :

 # getter
                my $dbname = $conf->param('dbname');
 
@section autotoc_md23 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

Code:

click to view

◆ parse_options()

public Boolean Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

sub parse_options {
  my ($self, @params) = @_;
 
  # add common options to user supplied list
  push @params, $self->_common_options;
 
  # read common commandline options
  my %h;
  my %params = @params;
 
  Getopt::Long::Configure('pass_through');
  &GetOptions(\%h, keys %params);
 
  # reads config file
  my $conffile = $h{'conffile'} || $self->default_conf;
  $conffile = abs_path($conffile);
 
  if (-e $conffile) {
    open(my $fh, '<', $conffile) or throw( 
        "Unable to open configuration file $conffile for reading: $!");
 
    my $serverroot = $self->serverroot;
    my $last;
 
    while (my $line = <$fh>) {
      chomp $line;
      
      # remove leading and trailing whitespace
      $line =~ s/^\s*//;
      $line =~ s/\s*$//;
 
      # join with next line if terminated with backslash (this is to allow
      # multiline configuration settings
      $line = $last . $line;
      if ($line =~ /\\$/) {
        $line =~ s/\\$//;
        $last = $line;
        next;
      } else {
        $last = undef;
      }
 
      # remove comments
      $line =~ s/^[#;].*//;
      $line =~ s/\s+[;].*$//;
 
      # read options into internal parameter datastructure
      next unless ($line =~ /(\w\S*)\s*=\s*(.*)/);
      my $name = $1;
      my $val = $2;
 
      # strip optional quotes from parameter values
      $val =~ s/^["'](.*)["']/$1/;
 
      # replace $SERVERROOT with value
      if ($val =~ /\$SERVERROOT/) {
        $val =~ s/\$SERVERROOT/$serverroot/g;
        $val = abs_path($val);
      }
      $self->param($name, $val);
    }
    close($fh);
 
    $self->param('conffile', $conffile);
  }
 
  # override configured parameter with commandline options
  map { $self->param($_, $h{$_}) } keys %h;
 
  # check for required params, convert comma to list, maintain an ordered
  # list of parameters and list of 'flag' type params
  my @missing = ();
  my $i = 0;
 
  foreach my $param (@params) {
    next if ($i++ % 2);
 
    my $required = $params{$param};
    my ($list, $flag);
    $list = 1 if ($param =~ /\@$/);
    $flag = 1 if ($param =~ /!$/);
    $param =~ s/(^\w+).*/$1/;
    
    $self->comma_to_list($param) if ($list);
 
    push @missing, $param if ($required and !$self->param($param));
    push @{ $self->{'_ordered_params'} }, $param;
    $self->{'_flag_params'}->{$param} = 1 if ($flag);
  }
  
  if (@missing) {
    throw("Missing parameters: @missing.\nYou must specify them on the commandline or in your conffile.\n");
  }
 
  # error handling and --help
  pod2usage(1) if ($self->param('help'));
 
  # ask user to confirm parameters to proceed
  $self->confirm_params;
 
  return(1);
}

◆ serverroot()

public String Bio::EnsEMBL::Utils::ConfParser::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

Code:

click to view

The documentation for this class was generated from the following file:

ensembl/modules/Bio/EnsEMBL/Utils/ConfParser.pm

Public Member Functions

Detailed Description

Synopsis

Description

Member Function Documentation

◆ _common_options()

◆ comma_to_list()

◆ confirm_params()

◆ create_commandline_options()

◆ default_conf()

◆ is_true()

◆ list_or_file()

◆ list_param_values()

◆ list_params()

◆ new()

◆ param()

◆ parse_options()

◆ serverroot()