options(3)
XMLTV::Options – Command-line parsing for XMLTV grabbers
Description
Utility library that implements command-line parsing and handles a lot of functionality that is common to all XMLTV grabbers.
Exported Functions
All these functions are exported on demand.
Usage
ParseOptions- ParseOptions shall be called by a grabber to parse the command-line options supplied by the user. It takes a single hashref as a parameter. The entries in the hash configure the behaviour of ParseOptions.
- •
- A hashref with the values for all command-line options in the format returned by Getopt::Long (See “Storing options in a hash” in Getopt::Long). This includes both options that the grabber must handle as well as options that ParseOptions handles for the grabber.
- •
- A hashref to the data loaded from the configuration file. See XMLTV::Configure for the format of $conf.
- ParseOptions handles the following options automatically without returning:
- –help
- –info (or –man)
- –capabilities
- –version
- –description
- –preferredmethod
- Handled automatically if the preferredmethod capability has been set and the preferredmethod option has been specified in the call to ParseOptions.
- ParseOptions also takes care of the following options without returning, by calling the stage_sub, listchannels_sub, list_lineups_sub and get_lineup_sub callbacks supplied by the grabber:
- –configure
- –configure-api
- –stage
- –list-channels
- –list-lineups
- –get-lineup
- ParseOptions will thus only return to the grabber when the grabber shall actually grab data.
- –days
- –offset
- –quiet
- –debug
- and any other options that are grabber specific. This can be done by reading $opt->{days} etc.
Changing the behaviour of ParseOptions- The behaviour of ParseOptions can be influenced by passing named arguments in the hashref. The following arguments are supported:
- grabber_name
- Required. The name of the grabber (e.g. tv_grab_se_swedb). This is used when printing the synopsis.
- description
- Required. The description for the grabber. This is returned in response to the –description option and shall say which region the grabber returns data for. Examples: “Sweden”, or “Sweden (tv.swedb.se)” if there are several grabbers for a region or country).
- version
- Required. This shall be a cvs Id field.
- capabilities
- Required. The capabilities that the grabber shall support. Only capabilities that XMLTV::Options knows how to handle can be specified. Example:
- stage_sub
- Required. A coderef that takes a stage-name and a configuration hashref as a parameter and returns an xml-string that describes the configuration necessary for that stage. The xml-string shall follow the xmltv-configuration.dtd.
- listchannels_sub
- Required. A coderef that takes a configuration hash as returned by XMLTV::Configure::LoadConfig as the first parameter and an option hash as returned by ParseOptions as the second parameter, and returns an xml-string containing a list of all the channels that the grabber can deliver data for using the supplied configuration. Note that the listsub shall not use any channel-configuration from the hashref.
- load_old_config_sub
- Optional. Default undef. A coderef that takes a filename as a parameter and returns a configuration hash in the same format as returned by XMLTV::Configure::LoadConfig. load_old_config_sub is called if XMLTV::Configure::LoadConfig fails to parse the configuration file. This allows the grabber to load configuration files created with an older version of the grabber.
- list_lineups_sub
- Optional. A coderef that takes an option hash as returned by ParseOptions as a parameter, and returns an xml-string containing a list of all the channel lineups for which the grabber can deliver data. The xml-string shall follow the xmltv-lineups.xsd schema.
- get_lineup_sub
- Optional. A coderef that returns an xml-string describing the configured lineup. The xml-string shall follow the xmltv-lineups.xsd schema.
- preferredmethod
- Optional. A value to return when the grabber is called with the –preferredmethod parameter. Example:
- defaults
- Optional. Default {}. A hashref that contains default values for the command-line options. It shall be in the same format as returned by Getopt::Long (See “Storing options in a hash” in Getopt::Long).
- extra_options
- Optional. Default []. An arrayref containing option definitions in the format accepted by Getopt::Long. This can be used to support grabber-specific options. The use of grabber-specific options is discouraged.
my( $opt, $conf ) = ParseOptions( {
grabber_name => 'tv_grab_test',
version => '$Id: Options.pm,v 1.28 2014/01/30 14:41:09 bilbo_uk Exp $',
description => 'Sweden (tv.swedb.se)',
capabilities => [qw/baseline manualconfig apiconfig lineups/],
stage_sub => \&config_stage,
listchannels_sub => \&list_channels,
list_lineups_sub => \&list_lineups,
get_lineup_sub => \&get_lineup,
} );ParseOptions returns two hashrefs:
If the –output option is specified, STDOUT will be redirected to the specified file.
The grabber must check the following options on its own:
capabilities => [qw/baseline manualconfig apiconfig/],
Note that XMLTV::Options guarantees that the grabber supports the manualconfig and apiconfig capabilities. The capabilities share and cache can be specified if the grabber supports them. XMLTV::Options will then automatically accept the command-line parameters –share and –cache respectively.
my( $opt, $conf ) = ParseOptions( {
grabber_name => 'tv_grab_test',
version => '$Id: Options.pm,v 1.28 2014/01/30 14:41:09 bilbo_uk Exp $',
description => 'Sweden (tv.swedb.se)',
capabilities => [qw/baseline manualconfig apiconfig preferredmethod/],
stage_sub => \&config_stage,
listchannels_sub => \&list_channels,
preferredmethod => 'allatonce',
list_lineups_sub => \&list_lineups,
get_lineup_sub => \&get_lineup,
} );Copyright
Copyright (C) 2005,2006 Mattias Holmlund.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.