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:

_param_silent()

protected Bio::EnsEMBL::Hive::Params::_param_silent

(

)

Undocumented method

Code:

_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:

csvq()

public Bio::EnsEMBL::Hive::Params::csvq

(

)

Undocumented method

Code:

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:

mysql_conn()

public Bio::EnsEMBL::Hive::Params::mysql_conn

(

)

Undocumented method

Code:

mysql_dbname()

public Bio::EnsEMBL::Hive::Params::mysql_dbname

(

)

Undocumented method

Code:

new()

public Bio::EnsEMBL::Hive::Params::new

(

)

    Description: a trivial constructor, mostly for testing a Params object

Code:

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:

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:

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:

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:

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:

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:

---

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

• modules/Bio/EnsEMBL/Hive/Params.pm