ensembl-hive  2.5
Public Member Functions | List of all members
Bio::EnsEMBL::Hive::Params Class Reference
+ Inheritance diagram for Bio::EnsEMBL::Hive::Params:

Public Member Functions

public new ()
 
public fuse_param_hashes ()
 
public param_init ()
 
protected _param_possibly_overridden ()
 
protected _param_silent ()
 
public Any param_required ()
 
public Boolean param_exists ()
 
public Boolean param_is_defined ()
 
public Any param ()
 
public param_substitute ()
 
public mysql_conn ()
 
public mysql_dbname ()
 
public csvq ()
 
protected _subst_one_hashpair ()
 

Detailed Description

Synopsis

By inheriting from this module you make your module able to deal with parameters:
1) parsing of parameters in the order of precedence, starting with the lowest:
#
## general usage:
# $self->param_init( $lowest_precedence_hashref, $middle_precedence_hashref, $highest_precedence_hashref );
#
## typical usage:
# $job->param_init(
# $runObj->param_defaults(), # module-wide built-in defaults have the lowest precedence (will always be the same for this module)
# $hive_pipeline->params_as_hash(), # then come the pipeline-wide parameters from the 'pipeline_wide_parameters' table (define things common to all analyses in this pipeline)
# $self->analysis->parameters(), # analysis-wide 'parameters' are even more specific (can be defined differently for several occurence of the same module)
# $job->input_id(), # job-specific 'input_id' parameters have the highest precedence
# $job->accu_hash(), # parameters accumulated and sent for this job by other preceding jobs
# );
2) reading a parameter's value
#
# my $source = $self->param('source'); )
3) dynamically setting a parameter's value
#
# $self->param('binpath', '/software/ensembl/compara');
#
Note: It proved to be a convenient mechanism to exchange params
between fetch_input(), run(), write_output() and other methods.

Description

    Most of Compara RunnableDB methods work under assumption
    that both analysis.parameters and job.input_id fields contain a Perl-style parameter hashref as a string.

    This module implements a generic param() method that allows to set parameters according to the following parameter precedence rules:

        (1) Job-Specific parameters defined in job.input_id hash, they have the highest priority and override everything else.

        (2) Analysis-Wide parameters defined in analysis.parameters hash. Can be overridden by (1).

        (3) Pipeline-Wide parameters defined in the 'meta' table. Can be overridden by (1) and (2).

        (4) Module_Defaults that are hard-coded into modules have the lowest precedence. Can be overridden by (1), (2) and (3).


    param_exists() returns 1 if the parameter is present and can be substituted,
                           undef if the substitution failed.
                           0 if the parameter is absent,
    param_is_defined() returns 1 if the parameter is present and can be substituted to a defined value,
                               undef if the substitution fails,
                               0 otherwise.
    param() returns the value if param_exists() returned true, undef otherwise.
    param_required() is like param() but dies instead of returning undef.

    In practice. given this hash of parameters:
    {
        'a' => 3,
        'b' => undef,
        'c' => '#other#',
    }
    the Params API would return:

                       |  a     b       c       d
    -------------------+----------------------------
    param_exists()     |  1     1     undef     0
    param_is_defined() |  1     0     undef     0
    param()            |  3   undef   undef   undef
    param_required()   |  3   (die)   (die)   (die)

Definition at line 80 of file Params.pm.

Member Function Documentation

◆ _param_possibly_overridden()

protected Bio::EnsEMBL::Hive::Params::_param_possibly_overridden ( )

Undocumented method

Code:
click to view

◆ _param_silent()

protected Bio::EnsEMBL::Hive::Params::_param_silent ( )

Undocumented method

Code:
click to view

◆ _subst_one_hashpair()

protected Bio::EnsEMBL::Hive::Params::_subst_one_hashpair ( ) 
    
    Description: this is a private method that performs one substitution. Called by param_substitute().
Code:
click to view

◆ csvq()

public Bio::EnsEMBL::Hive::Params::csvq ( )

Undocumented method

Code:
click to view

◆ fuse_param_hashes()

public Bio::EnsEMBL::Hive::Params::fuse_param_hashes ( ) 
    Description: Performs the actual task of evaluating and fusing/merging a preference list of parameter hashes into one parameter hash.
Code:
click to view

◆ mysql_conn()

public Bio::EnsEMBL::Hive::Params::mysql_conn ( )

Undocumented method

Code:
click to view

◆ mysql_dbname()

public Bio::EnsEMBL::Hive::Params::mysql_dbname ( )

Undocumented method

Code:
click to view

◆ new()

public Bio::EnsEMBL::Hive::Params::new ( ) 
    Description: a trivial constructor, mostly for testing a Params object
Code:
click to view

◆ param()

public Any Bio::EnsEMBL::Hive::Params::param ( ) 
    Arg [1]    : string $param_name
    Arg [2]    : (optional) $param_value
    Arg [3]    : (optional) $value_needs_substitution (in case you want to define a parameter with '#other_param#' and let the system compute its true value later)
    Description: A getter/setter method for a job's parameters that are initialized through multiple levels of precedence (see param_init() )
    Example 1  : my $source = $self->param('source'); # acting as a getter
    Example 2  : $self->param('binpath', '/software/ensembl/compara');  # acting as a setter
    Returntype : any Perl structure or object that you dared to store
Code:
click to view

◆ param_exists()

public Boolean Bio::EnsEMBL::Hive::Params::param_exists ( ) 
    Arg [1]    : string $param_name
    Description: A predicate tester for whether the parameter has been initialized (even to undef)
    Example    :
if( $self->param_exists('source') ) { print "'source' exists\n"; } else { print "never heard of 'source'\n"; }
    Returntype : boolean
Code:
click to view

◆ param_init()

public Bio::EnsEMBL::Hive::Params::param_init ( ) 
    Description: Sets up the unsubstituted parameters in the right precedence order (called by AnalysisJob::load_parameters)
Code:
click to view

◆ param_is_defined()

public Boolean Bio::EnsEMBL::Hive::Params::param_is_defined ( ) 
    Arg [1]    : string $param_name
    Description: A predicate tester for definedness of a parameter
    Example    :
if( $self->param_is_defined('source') ) { print "defined, possibly zero"; } else { print "undefined"; }
    Returntype : boolean
Code:
click to view

◆ param_required()

public Any Bio::EnsEMBL::Hive::Params::param_required ( ) 
    Arg [1]    : string $param_name
    Description: A strict getter method for a job's parameter; will die if the parameter was not set or is undefined
    Example    :
my $source = $self->param_required('source');
    Returntype : any Perl structure or object that you dared to store
Code:
click to view

◆ param_substitute()

public Bio::EnsEMBL::Hive::Params::param_substitute ( ) 
    Arg [1]    : Perl structure $string_with_templates
    Description: Performs parameter substitution on strings that contain templates like " #param_name# followed by #another_param_name# " .
    Returntype : *another* Perl structure with matching topology (may be more complex as a result of substituting a substructure for a term)
Code:
click to view
The documentation for this class was generated from the following file: