|
|
| |
Options(3) |
User Contributed Perl Documentation |
Options(3) |
XMLTV::Options - Command-line parsing for XMLTV grabbers
Utility library that implements command-line parsing and handles a lot of
functionality that is common to all XMLTV grabbers.
All these functions are exported on demand.
- 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.29 2015/07/12 00:59:01 knowledgejunkie 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.29 2015/07/12 00:59:01 knowledgejunkie 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 (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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |