Options(3pm)

💖 XMLTV::Options 💖

okay so this is the manual page for Options from the User Contributed Perl Documentation section — the whole vibe of this library is "command-line parsing for XMLTV grabbers", and honestly? it's giving backstage-pass energy for every grabber out there. 🎀

✨ NAME ✨

XMLTV::Options — command-line parsing for XMLTV grabbers 🦋

🌸 DESCRIPTION 🌸

bestie, this is a utility library that implements command-line parsing, and it also handles so much functionality that's common to literally every XMLTV grabber. like, it's the shared glue holding the whole grabber squad together. no cap. 💅

🌈 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 => '1.2',
  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:

1. 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. 🫶
2. 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. 🎬 (main character moment fr fr)

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. The version number of the grabber to be displayed. Supported version string formats include "x", "x.y", and "x.y.z".
• 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. (throwback config, iconic honestly 🕰️)
• 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 => '1.2',
  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.

⚠️ heads up bestie: the use of grabber-specific options is discouraged. just so you know. 🙈

---

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

---

and that's the whole page, bestie!! 🌈✨ this one came from perl v5.40.1, dated 2025-04-19 — mwah, slay, periodt, go parse some options 💅🫶💖