Section: User Contributed Perl Documentation (3)
Updated: 2019-02-21


XMLTV::Options - Command-line parsing for XMLTV grabbers 


Utility library that implements command-line parsing and handles a lotof functionality that is common to all XMLTV grabbers. 


All these functions are exported on demand. 


ParseOptions shall be called by a grabber to parse the command-lineoptions 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 => '1.2',    description => 'Sweden (',    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 theformat returned by Getopt::Long (See ``Storing options in a hash'' inGetopt::Long). This includes both options that the grabbermust 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:

--info (or --man)
Handled automatically if the preferredmethod capability has been set andthe 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_subcallbacks supplied by the grabber:


ParseOptions will thus only return to the grabber when the grabber shallactually grab data.

If the --output option is specified, STDOUT will be redirected tothe specified file.

The grabber must check the following options on its own:


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 argumentsin the hashref. The following arguments are supported:
Required. The name of the grabber (e.g. tv_grab_se_swedb). This is usedwhen printing the synopsis.
Required. The description for the grabber. This is returned in response tothe --description option and shall say which region the grabber returns datafor. Examples: ``Sweden'', or ``Sweden ('' if there are several grabbersfor a region or country).
Required. The version number of the grabber to be displayed. Supported versionstring formats include ``x'', ``x.y'', and ``x.y.z''.
Required. The capabilities that the grabber shall support. Only capabilitiesthat 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 manualconfigand apiconfig capabilities. The capabilities share and cache can bespecified if the grabber supports them. XMLTV::Options will then automaticallyaccept the command-line parameters --share and --cache respectively.

Required. A coderef that takes a stage-nameand a configuration hashref as a parameter and returns anxml-string that describes the configuration necessary for that stage.The xml-string shall follow the xmltv-configuration.dtd.
Required. A coderef that takes a configurationhash as returned by XMLTV::Configure::LoadConfig as the first parameterand an option hash as returned byParseOptions as the second parameter, and returns an xml-stringcontaining a list of all the channels that the grabber can deliverdata for using the supplied configuration. Note that the listsubshall not use any channel-configuration from the hashref.
Optional. Default undef. A coderef that takes a filename as a parameterand returns a configuration hash in the same format as returned byXMLTV::Configure::LoadConfig. load_old_config_sub is called ifXMLTV::Configure::LoadConfig fails to parse the configuration file. Thisallows the grabber to load configuration files created with an olderversion of the grabber.
Optional. A coderef that takes an option hash as returned by ParseOptionsas a parameter, and returns an xml-string containing a list of all thechannel lineups for which the grabber can deliver data.The xml-string shall follow the xmltv-lineups.xsd schema.
Optional. A coderef that returns an xml-string describing the configuredlineup. The xml-string shall follow the xmltv-lineups.xsd schema.
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 => '1.2',    description => 'Sweden (',    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,  } );
Optional. Default {}. A hashref that contains default values for thecommand-line options. It shall be in the same format as returned byGetopt::Long (See ``Storing options in a hash'' in Getopt::Long).
Optional. Default []. An arrayref containing option definitions in theformat accepted by Getopt::Long. This can be used to support grabber-specificoptions. The use of grabber-specific options is discouraged.


Copyright (C) 2005,2006 Mattias Holmlund.

This program is free software; you can redistribute it and/ormodify it under the terms of the GNU General Public Licenseas published by the Free Software Foundation; either version 2of 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 ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with this program; if not, write to the Free SoftwareFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.




This document was created byman2html,using the manual pages.