Options (3) - Linux Manuals
Options: Command-line parsing for XMLTV grabbers
NAME
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.
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:
-
- •
- 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.
If the --output option is specified, STDOUT will be redirected to the specified file.
The grabber must check the following options on its own:
- --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:
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.
- 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:
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, } );
- 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.
-
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.