Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Options(3)	      User Contributed Perl Documentation	    Options(3)

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.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:

	   o   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.

	   o   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
       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.

perl v5.32.0			  2020-08-27			    Options(3)

NAME | DESCRIPTION | EXPORTED FUNCTIONS | USAGE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XMLTV::Options&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help