Weather::GHCN::Options - create and manage option lists/objects used by GHCN modules and scripts
version v0.0.011
use Weather::GHCN::Options;
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.
Create a new Options object.
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.
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.)
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.
This writable field is set by StationTable->set_options and contains the profile options it was given.
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.
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.
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);
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.
Returns: \%defaults
Returns the option defaults, obtained from the same predefined list of lists/strings returned by get_tk_options_table.
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.
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'.
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() );
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.
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:
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.
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.
Returns: @errors
This method initializes options that can't simply be initialized by constants. Specifically:
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().
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.
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.
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.
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.
This method is called by StationTable->set_options to make sure all the options that were provided to set_options are valid. It also handles abbreviations for options color and report. Any errors arising from invalid value or from problems detected during intialize (which is called at the end of validate) are returned in a list.
Defined by Object::Pad. Included for POD::Coverage.
To install Weather::GHCN::Fetch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Weather::GHCN::Fetch
CPAN shell
perl -MCPAN -e shell install Weather::GHCN::Fetch
For more information on module installation, please visit the detailed CPAN module installation guide.