NAME

GHCN::Options - create and manage option lists/objects used by GHCN modules and scripts

VERSION

version v0.22.258

SYNOPSIS

use GHCN::Options;

DESCRIPTION

The GHCN::Options module provides a class and methods that are used within GHCN modules or from application scripts that use GHCN modules to create and manage options that determine the behaviour of GHCN methods.

The module is primarily for use by module GHCN::StationTable.

METHODS

new

Create a new Options object.

FIELD ACCESSORS

Writeable (mutator) access is provided for some fields primarily so an Options object can be tested independantly from StationTable. In general, an Options object is set by the StationTable set_options method and should not be modified directly by the consuming application using these mutators.

opt_href

This writable field is set by StationTable->set_options and is a hashref of user options merged with default values.

For programmatic access to option values, use of opt_obj is preferred to prevent mispellings. (See opt_obj.)

opt_obj

This writable field is set by StationTable->set_options and is a Hash::Wrap object composed from the opt_href hashref field. It provides accessor field methods for user options (merged with default values).

Using this object, rather than opt_href, for access to option values is safer programming choice as any misspelling of an option name will result in a run time error. In contrast, mispelling a hash key will simply result in an undef being returned.

config_href

This writable field is set by StationTable->set_options and contains the configuration options it was given.

CLASS METHODS

The following class methods are supported. Class Options uses Object::Perl, so these class methods (specified using the :common method attribute) should be accessed using -> not :: because -> will shift off the $class argument and :: won't.

get_tk_options_table

Returns: @tk_opttable or \@tk_opttable

Provides access to the predefined TK::Getopt options list that define the Getopt::Long arguments supported by class StationTable for user options.

The table is a list of lists and strings. The strings define sections that Tk::Getopt renders as panels or tabs in the GUI it constructs. The lists contain option names and types (in Getopt::Long style) as well as default values, aliases, and labels to be displayed in the GUI, choices for multi-select options, and other extensions. See Tk::Getopt OPTTABLE ARGUMENTS for details.

get_getopt_list

Returns: @options or \@options

In scalar context, return a list reference to a translation of the TK::Getopt options list into the simpler list used by Getopt::Long. This gives application authors a choice between using Tk::Getopt and the non-GUI and more traditional Getopt::Long.

In list context, this method returns a Getopt::Long-style list options.

Typically, this method would be called prior to Getopt::Long in order to obtain an options list for using the StationTable class; e.g.

my %opt;
my @options = ( GHCN::Options->get_getopt_list() );
GetOptions( \%opt, @options);

get_option_choices ( $option )

Returns: \%choices

Find all the options which have a multiple choice response, and return a hash keyed on the option name and with a values consisting of a hash of the valid responses as value/label pairs.

get_option_defaults

Returns: \%defaults

Returns the option defaults, obtained from the same predefined list of lists/strings returned by get_tk_options_table.

INSTANCE METHODS

combine_options ($user_opt_href)

Returns: ($opt_href, $opt_obj)

This method takes a hash reference containing user options, merges it with the full set of supported options, and applies any necessary default values. The end result is a complete set of all the options supported by GHCN::StationTable with user-specified options taking precedence over all other.

This set of options is returned as both a hash reference and as a Hash::Wrap object. The latter is preferred for use by consuming applications, because it provides accessor methods for each option. In addition, an ->defined( "<option>" ) method is provided so that your code can determine whether an option value was set to undef.

The advantage to using an option object rather than an option hash is that a misspelled option name will cause a runtime error.

initialize

Returns: @errors

This method initialize various user and configuration options that can't simply be initialized by constants. Specifically:

Aliases

Alias entries defined in configuration options are matched against the -location option value. If a match is found to the alias name, the alias value is substituted for the location value.

Alias names must be lowercase letters only. An optional underscore prefix is permitted. Names not matching this rule will be silently ignored by initialize().

country

The country option value can be:

* a 2-character GEC (FIPS) country code

* a 3-character alpha ISO 3166 country code

* a 3-digit numeric ISO 3166 country number

* an internet domain country suffix (e.g. '.ca')

* a 3-character regex string

If a regex string is given, then it will be matched (unanchored and case insensitve) against country names. If multiple matches are found, then an error is returned and the user will need to provide a more specific pattern.

active

The active option filters stations according to the years that they were active. If the range option is specified, but the active option is not, then initialize will set the active option value to the range option value so that only stations that were active during the requested data range will be selected.

quality

The quality option determines whether a station's data will be included in the output when it has missing data. Quality is expressed as a number between 0 and 100, representing the percentage of data that cannot be missing; 90% is the default For example, if you have a range of 3 years (1095 days) when quality is 90, then you need 90% x 1095 = 985 days of data. Anything less and the station is rejected.

When filters fmonth and fday are used, the amount of data included will typically drop far below 90% thereby rejecting all stations. To avoid this nuisance, initialize will set quality to 0% if either the fmonth or fday options are present.

options_as_string

This option returns a string that contains all the options and their values, in a format similar to what they would look like when entered as command-line arguments. For boolean options only the option name is include (no value). Option values containing whitespace are enclosed in double quotes. Option/value pairs are separated by two spaces.

This method is primarily provided so the consuming application can print the options that were used during a run, perhaps to a log or in the output.

validate