NAME

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

VERSION

version v0.0.011

SYNOPSIS

use Weather::GHCN::Options;

DESCRIPTION

The Weather::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 Weather::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.

profile_href

This writable field is set by StationTable->set_options and contains the profile 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 = ( Weather::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.

get_profile_filespec ($filespec='')

Returns the filespec for the user profile file. If the optional $filespec argument is null or an empty string, then the default profile is returned. If a $filespec argument is provided, it can contain '~' (to represent the user HOME directory) and that will be converted to an absolute path.

get_profile_options ($profile='')

Return a hashref containing the options and aliases defined in the the user profile file. If called with undef, returns a ref to an empty hash. If called with an empty string, it reads from the default profile file '~/.ghcn_fetch.yaml'.

valid_report_type ($rt, \@opttable)

This function is used to validate the report type. Valid values are defined in the built-in Tk options table, which can be obtained by calling:

my @opttable = ( Weather::GHCN::Options->get_tk_options_table() );

deabbrev_report_type ($rt)

The report types supported by the -report option can be abbrevated, so long as the abbrevation is unambiquous. For example, 'daily' can be abbreviated to 'dail', 'dai', or 'da', but not 'd' because 'detail' is also a valid report type and 'd' would not disambiguate the two.

This function takes a (possibly abbreviated) report type and returns an unabbreviated report type.

valid_refresh_option ($refresh, \@opttable)

This function is used to validate the refresh option. Valid values are defined in the built-in Tk options table, which can be obtained by calling:

my @opttable = ( Weather::GHCN::Options->get_tk_options_table() );

deabbrev_refresh_option ($refresh)

The refresh option values can be abbrevated, so long as the abbrevation is unambiquous. For example, 'yearly' can be abbreviated to 'y', 'ye', 'yea', etc.

This function takes a (possibly abbreviated) refresh option and returns an unabbreviated refresh option.

INSTANCE METHODS

combine_options ( $user_opt_href, $profile_href={} )

Returns: ($opt_href, $opt_obj)

This method takes a hash reference containing user options, and optionally a hash reference of profile options, and combines them with default values. The end result is a complete set of all the options supported by Weather::GHCN::StationTable with user-specified options taking precedence over profile options, and profile options taking precedence over defaults.

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 initializes options that can't simply be initialized by constants. Specifically:

Aliases

Alias entries defined in the user profile 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