/ 
Data-Identifier-v0.06
River stage zero No dependents
/ Data::Identifier::Interface::Known

NAME

Data::Identifier::Interface::Known - format independent identifier object

VERSION

version v0.06

SYNOPSIS

use parent 'Data::Identifier::Interface::Known';

Interface for modules implementing known().

Note: This is an experimental interface. It may be changed, renamed, or removed without notice.

METHODS

known

my @list = Some::Package->known($class [, %opts ] );
# or:
my @list = $obj->known($class [, %opts ] );

Returns a list of known tags (subjects, keys, ...) for the given $class. If the $class is unknown or unsupported this method dies.

$class is a string with the name of the class to return known items for.

Strings that do not contain colons (:) have a meaning defined by the module. Classes that include a colon are defined by this interface. The only such class currently defined is :all which should return known entries for all classes known by the module.

Future version of this module might allow for non-string values. If they are encountered but not supported the implementation should die as with other unknown classes.

The implementation should avoid returning the same entry multiple times. However the caller must not assume:

  • Entries to be unique within the returned list.

  • Entries to be in any specific order.

  • The returned entries to be the same for any two calls.

The following (all optional) options are supported:

as

The type to be used for returned items. It must be one of raw (the return type is defined by the module and the class), uuid, or oid, or uri (returning the tag's identifier as UUID, OID, or URI), ise (returning the tag's identifier as ISE), URI (the same as uri but the value is returned as an instance of URI rather than as string), Data::Identifier (as an instance of Data::Identifier), or any other package name (containing two :: or starting with a upper case letter).

If a value is given that is not supported for all items to be returned the method must die.

default

The default value to be returned if the class is unknown or unsupported. This must be an array reference. It is common to set this to [] to return an empty list when this method would otherwise die.

no_defaults

See "as" in Data::Identifier for the use of no_defaults.

skip_invalid

If set true, entries that cannot satisfy the given requirements (most likely as) are skipped from the output without dieing.

The default implementation fits the above requirements. It calls "_known_provider". Return values are automatically converted as needed. The returned list is protected against mutation.

_known_provider

my ($list, %extra) = $pkg->_known_provider($class, %opts);

This method is used by the default implementation of "known" to get the required list. If you override "known" this method can stay unimplemented.

This method should return a list of known objects matching $class as it's first return value. (Automatic type conversion is performed by "known", but see also extra values below.) It may also return extra information as a hash (not a hash reference).

If $class is unknown or unsupported the method should die.

The default implementation returns an empty list for the class :all and dies otherwise.

Optionally options are passed. If an option is passed that is not supported this method should die. Currently no options are defined. An implementation can therefore use:

die 'Unsupported options passed' if scalar(keys %opts);

The folling extra values are supported:

rawtype

The type assumed when "known" is passed as => 'raw'

not_identifiers

If true the returned list contains non-identifier values. A non-identifier value is defined as any value that cannot be passed to "new" in Data::Identifier via from.

AUTHOR

Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023-2024 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)