PDL::Options(3pm)

📦

version 2.106 · 9 versions

💖 PDL::Options 💖

okay so this is the PDL::Options(3pm) page from the User Contributed Perl Documentation collection, bestie — and it's literally all about making option-passing by hash in PerlDL not a whole nightmare. let's get into it 🫶

✨ NAME ✨

PDL::Options — simplifies option passing by hash in PerlDL. periodt. 💅

🦋 SYNOPSIS 🦋

use PDL::Options;

%hash = parse( \%defaults, \%user_options);

use PDL::Options ();

$opt = PDL::Options->new;
$opt = PDL::Options->new( \%defaults );

$opt->defaults ( \%defaults );
$opt->synonyms ( { 'COLOR' => 'COLOUR' } );

$hashref = $opt->defaults;

$opt->options ( \%user_options );

$hashref = $opt->options;

$opt->incremental(1);
$opt->full_options(0);

look at her go, she's doing so much 🎀

🌸 DESCRIPTION 🌸

It's an object, right, and its whole job is simplifying option passing for PerlDL subroutines. Basically it lets you merge a user defined options with defaults. And because not everyone wants to do the OO thing, there's also a simplified (non-OO) interface provided. versatile queen 👑

✨ Utility functions ✨

🎀 ifhref 🎀

parse({Ext => 'TIF', ifhref($opt)});

okay so this one is so simple it's iconic: it just returns the argument if it's a hashref, otherwise it returns an empty hashref. that's it. that's the function. 🙈

It's lowkey useful in conjunction with parse — it lets you return just the default values if the argument isn't a hash ref. chef's kiss 🍓

💅 NON-OO INTERFACE 💅

A simplified non-object oriented interface is provided. These routines are exported into the callers namespace by default. no -> required, we're keeping it casual ✨

parse( \%defaults, \%user_options ) — this will parse user options by using the defaults. The following settings are used for parsing: the options are case-sensitive, a default synonym table is consulted (see "Default Synonyms"), minimum-matching is turned on, and translation of values is not performed.

A hash (not hash reference!!) containing the processed options is returned, bestie, don't forget that part 😭

%options = parse( { LINE => 1, COLOUR => 'red'}, { COLOR => 'blue'});

iparse( \%defaults, \%user_options ) — same as parse but matching is case insensitive 🦋

🌈 Default Synonyms 🌈

The following default synonyms are available in the non-OO interface:

COLOR  => COLOUR
COLOUR => COLOR
CENTER => CENTRE
CENTRE => CENTER

they're matching each other, it's giving mutual support 🫶

👑 METHODS 👑

The following methods are available to PDL::Options objects. okay there's a lot of them, hydrate, we got this 💜

new() — constructor. Creates the object. With an optional argument it can also set the default options. glow-up from nothing to something ✨
extend (\%options) — this will copy the existing options object and extend it with the requested extra options. like getting a little sibling but for options 🎀
defaults( \%defaults ) — method to set or return the current defaults. The argument should be a reference to a hash. The hash reference is returned if no arguments are supplied.

⚠️ heads up: the current values are reset whenever the defaults are changed. no cap.

add_synonym (\%synonyms) — method to add another synonym to an option set. The argument should be a reference to a hash.
add_translation (\%translation) — method to add another translation rule to an option set. The argument should be a reference to a hash.
synonyms( \%synonyms ) — method to set or return the current synonyms. The argument should be a reference to a hash. The hash reference is returned if no arguments are supplied.

This lets you provide alternate keywords — such as allowing 'COLOR' as an option when your defaults uses 'COLOUR'. so inclusive of everyone's spelling 💖

current — returns the current state of the options. This comes back as a hash reference (although it is not a reference to the actual hash stored in the object — got it? it's a copy situation, not a share situation). If full_options() is true, the full options hash is returned; if full_options() is false, only the modified options are returned (as set by the last call to options()).
clear_current — this routine clears the 'state' of the PDL::Options object so that the next call to current will return an empty list. factory reset but cute 🧚
translation — provide translation of options to more specific values that are recognised by the program. This allows, for example, the automatic translation of the string 'red' to '#ff0000'. yes bestie, it speaks hex 🎨

This method can be used to setup the dictionary and is a hash reference with the following structure:

OPTIONA => {
            'string1' => decode1,
            'string2' => decode2
            },
OPTIONB => {
            's4' => decodeb1,
           }
etc....

Where OPTION? corresponds to the top level option name as stored in the defaults array (eg LINECOLOR) and the anonymous hashes provide the translation from string1 ('red') to decode1 ('#ff0000').

An options string will be translated automatically during the main options() processing if autotrans() is set to true. Else translation can be initiated by the user using the translate() method. iykyk 💅

incremental — specifies whether the user defined options will be treated as additions to the current state of the object (1) or modifications to the default values only (0).

Can be used to set or return this value. Default is false.

full_options — governs whether a complete set of options is returned (ie defaults + expanded user options), true, or if just the expanded user options are returned, false (ie the values specified by the user).

This can be useful when you're only interested in the changes to the options rather than knowing the full state. (For example, if defaults contains keys for COLOUR and LINESTYLE and the user supplied a key of COL, you may simply be interested in the modification to COLOUR rather than the state of LINESTYLE and COLOUR.) yes, main character energy — only caring about what changed ✨

Default is true.

casesens — specifies whether the user defined options will be processed independent of case (0) or not (1). Default is to be case insensitive.