Options(3) User Contributed Perl Documentation Options(3)NAME
XMLTV::Options
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.15 2008/06/01 01:48:00 knowledgejunkie Exp $',
description => 'Sweden (tv.swedb.se)',
capabilities => [qw/baseline manualconfig apiconfig/],
stage_sub => \&config_stage,
listchannels_sub => \&list_channels,
} );
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 listchannels_sub and stage_sub callbacks
supplied by the grabber:
--configure
--configure-api
--list-channels
--stage
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.
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.15 2008/06/01 01:48:00 knowledgejunkie Exp $',
description => 'Sweden (tv.swedb.se)',
capabilities => [qw/baseline manualconfig apiconfig preferredmethod/],
stage_sub => \&config_stage,
listchannels_sub => \&list_channels,
preferredmethod => 'allatonce',
} );
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.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 113:
You forgot a '=back' before '=head1'
Around line 115:
'=item' outside of any '=over'
Around line 544:
You forgot a '=back' before '=head1'
perl v5.10.1 2008-06-01 Options(3)
