/ 
Data-OptList-Object-0.001003
/ Data::OptList::Object

NAME

Data::OptList::Object - Data::OptList, but object-oriented

SYNOPSIS

Data::OptList provides a compact list format for lists of options, where each option has a key/name which is a string and a value which must be either undef or a reference.

my $options = Data::OptList::mkopt([
    qw(key1 key2 key3 key4),
    key5 => { ... },
    key6 => [ ... ],
    key7 => sub { ... },
    key8 => { ... },
    key8 => [ ... ],
]);

Is a shorthand for:

my $options = [
    [ key1 => undef,        ],
    [ key2 => undef,        ],
    [ key3 => undef,        ],
    [ key4 => undef,        ],
    [ key5 => { ... },      ],
    [ key6 => [ ... ],      ],
    [ key7 => sub { ... },  ],
    [ key8 => { ... },      ],
    [ key8 => [ ... ],      ],
];

The resulting structure may be looped through easily:

for my $pair ( @$options ) {
    printf "%s=%s\n", $pair->[0], ref($pair->[1]) || 'undef';
}

Data::OptList::Object encapsulates the result in a blessed object, allowing convenient methods to be called on it.

my $options = Data::OptList::Object->new(
    qw(key1 key2 key3 key4),
    key5 => { ... },
    key6 => [ ... ],
    key7 => sub { ... },
    key8 => { ... },
    key8 => [ ... ],
);

for my $pair ( @$options ) {
    printf "%s=%s\n", $pair->key, $pair->kind;
}

if ( $options->key7 ) {
    my $coderef = $options->key7->value;
    $coderef->();
}

DESCRIPTION

Constructor

The constructor can be used to create a new OptList object. It may be called in any of these fashions:

new( @OPTLIST )
new( \@OPTLIST )
new( \%OPTHASH )
new( $OBJECT )

Where \@OPTLIST is a reference to any array conforming to the optlist format, \%OPTHASH is any hashref where the values are either undef or references, and $OBJECT is any blessed object where $OBJECT->DOES('Data::OptList::Object') returns True and provides a TO_LIST method.

Methods

All built-in methods are uppercase.

ALL()

Calling ALL() returns a list of pair objects.

for my $pair ( $options->ALL ) {
    printf "%s=%s\n", $pair->key, ref($pair->value) || 'undef';
}

The returned list is like the output of mkopt() from Data::OptList (except as a list instead of an arrayref).

In scalar context, it returns the length of that list.

COUNT()

Count is like ALL(), but forces scalar context, so always returns the number of pairs.

Data::OptList::Object overloads the 0+ operator to call this.

my $how_many_options = 0 + $options;
KEYS()

Calling KEYS() returns a list of just the keys.

for my $key ( $options->KEYS ) {
    printf "Found key: %s\n", $key;
}

This method's behaviour in scalar context is undefined.

VALUES()

Calling VALUES() returns a list of just the values.

for my $value ( $options->VALUES ) {
    printf "Found value of type %s\n", ref $value;
}

This method's behaviour in scalar context is undefined.

TO_LIST()

Returns the options in their original optlist format. This may not exactly match the format passed to the constructor as it will have been canonicalized.

The returned list is like the input to mkopt() from Data::OptList (except as a list instead of an arrayref).

This method's behaviour in scalar context is undefined.

TO_ARRAYREF()

Returns the same list as ALL(), but as an arrayref.

for my $pair ( @{ $options->TO_ARRAYREF } ) {
    printf "%s=%s\n", $pair->key, ref($pair->value) || 'undef';
}

Data::OptList::Object overloads the @{} operator to call this.

for my $pair ( @$options ) {
    printf "%s=%s\n", $pair->key, ref($pair->value) || 'undef';
}

The returned list is like the output of mkopt() from Data::OptList.

TO_JSON()

Returns the same list as TO_LIST(), but as an arrayref. This allows Data::OptList::Object to play nice with JSON serialization, assuming the values in your optlist are values that can be represented in JSON.

my $j = JSON->new->convert_blessed( 1 );
print $j->encode( $options );
TO_HASHREF()

Provides a simple key-value hashref for the optlist. This is appropriate if you do not expect your keys to appear more than once.

The hashref is read-only. A quirk of read-only hashes in Perl is that trying to read from a key that does not exist will cause an error.

my $hashref = $options->TO_HASHREF;
if ( $hashref->{key7} ) {  # might die
    my $coderef = $hashref->{key7};
    $coderef->();
}

Make sure to use the exists keyword when checking if an option was given.

my $hashref = $options->TO_HASHREF;
if ( exists $hashref->{key7} ) {
    my $coderef = $hashref->{key7};
    $coderef->();
}

As options default to having the value undef, it is sensible to use exists to check for their presence anyway.

Data::OptList::Object overloads the %{} operator to call this.

if ( exists $options->{key7} ) {
    my $coderef = $options->{key7};
    $coderef->();
}
TO_REGEXP()

Returns a regular expression which matches all the keys in the optlist.

my $re = $options->TO_REGEXP;
if ( 'key7' =~ $re ) {
    my $coderef = $options->{key7};
    $coderef->();
}

Data::OptList::Object overloads the qr operator to call this.

if ( 'key7' =~ $options ) {
    my $coderef = $options->{key7};
    $coderef->();
}
GET( $key )

In list context, returns a list of pairs where the key is $key.

my @eights = $options->GET( 'key8' );
for my $pair ( @eights ) {
    printf "%s=%s\n", $pair->key, ref($pair->value) || 'undef';
}

You can alternatively provide a regexp or coderef for $key.

my @eights = $options->GET( qr/^key8$/i );
my @eights = $options->GET( sub { $_->key eq 'key8' } );

In scalar context, will return the first such pair if there are any.

my $first_key8_value = $options->GET( 'key8' )->value;

If called in scalar context and there are no pairs with the given key, GET will return a special object which overloads boolification to be false, but provides key and value methods.

if ( $options->GET( 'does_not_exist' ) ) {
    # The above condition is false, so this block will
    # not execute.
}

# Yet this doesn't die.
my $value = $options->GET( 'does_not_exist' )->value;
HAS( $key )

Like GET( $key ) but returns a simple true or false to indicate if the key was found.

Also accepts a regexp or coderef.

MATCH( $key )

An alias for HAS( $key ). This alias exists to play nicely with match::simple.

use match::simple 'match';

if ( match 'key7', $options ) {
    ...;
}

It also works with Syntax::Keyword::Matches:

use Syntax::Keyword::Matches;

if ( 'key7' matches $options ) {
    my $coderef = $options->key7->value;
    $coderef->();
}

AUTOLOAD

The AUTOLOAD method will call GET($key).

my $first_key8_value = $options->key8->value;

This is useful for when your option keys are all valid unqualified bareword identifiers. This is the reason Data::OptList::Object avoids having any method names with lowercase characters. (Except new.)

Overloading

The following operators are overloaded:

bool

Data::OptList::Options objects are always True.

""

Data::OptList::Options have a cute stringification which shows their keys (but not values).

0+

Calls COUNT.

%{}

Calls TO_HASHREF.

@{}

Calls TO_ARRAYREF.

qr

Calls TO_REGEXP.

Pair Objects

A number of methods return pair objects, representing a key-value pair. Pair objects are read-only and have the following methods:

key()

Returns the key as a string.

value()

Returns the value, which will normally be either undef or a reference.

kind()

The kind of value this pair has. Either the string returned by Perl's builtin ref() function, or the string "undef" if the value is undef.

exists()

Returns True to indicate that the pair exists. Data::OptList::Object's GET() method in scalar context will return a special pair object where exists() returns False to indicate that no pair has been found.

TO_JSON()

Returns a two item arrayref consisting of the key followed by the value.

Pair objects are blessed arrayrefs, and you may access the key using $pair->[0] or the value using $pair->[1].

Pair objects overload "" to return the key, and override bool to return the result of exists().

BUGS

Please report any bugs to https://github.com/tobyink/p5-data-optlist-object/issues.

SEE ALSO

Data::OptList.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2025 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.