Provided by: libxmltv-perl_0.5.61-1_all bug

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.21 2010/10/01 17:49:30 dekarl 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
           --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 and listlineups_sub  callbacks supplied by the
           grabber:

           --configure
           --configure-api
           --stage
           --list-channels
           --list-lineups
           --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 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 channel lineups that the grabber can deliver data for using the
               supplied configuration.  Note that the listsub shall not use any channel-
               configuration from the hashref.

           get_lineup_sub
               Optional. A coderef that takes a lineup ID as a parameter and returns an xml-
               string that describes the given lineup. The xml-string shall follow the
               xmltv-lineup.dtd.

           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.21 2010/10/01 17:49:30 dekarl 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.