/ 
SeeAlso-Server-0.52
River stage one • 2 direct dependents • 2 total dependents
/ SeeAlso::Identifier

NAME

SeeAlso::Identifier - an identifier passed to a SeeAlso-Server

DESCRIPTION

The query to a SeeAlso (and other unAPI) server is just an identifier. By default an identifier is just a string but identifiers may also have special properties like checksums and normalized forms.

SeeAlso::Identifier models identifiers that are passed to and processed by a SeeAlso::Server and a SeeAlso::Source. To model more complex identifiers you can either derive a subclass or provide additional methods to the constructor. These are a method to check whether the identifier is valid or not, a method to create a normalized form of an identifier, and a method to create an index entry of an identifier.

The concept is best explained with an example: The International Standard Serial Number (ISSN) is used to identify periodical publications. The format of the ISSN is an eight digit number, divided by a hyphen into two four-digit numbers. The last digit is a check digit which may be 0-9 or an X. In practise the hyphen may be missing and the check digit may also be provided lowercase.

When used as an identifier, the different forms of an ISSN as used in the model of SeeAlso::Identifier are:

value

The string value as provided, for instance 'ISSN 0002-936X', '0002-936x', '0002936x' (which all refer to the same ISSN in this example)

normalized

The canonical form whith hyphem and uppercase X: '0002-936X'

indexed

The form that is used for indexing. This could be '0002936X' or '0002936' because hyphen and check digit do not contain information. You could also store the ISSN in the 32 bit integer number '2996' instead of a string.

valid

The ISSN is checked by testing for invalid or missing characters and the check digit is computed.

The constructor new contains an example.

If you provide a normalizing method n then this method should behave like a normalizing is expected. That is for every possible input s the condition n(s) == n(n(s)) must be true.

METHODS

new ( [ $value | %params ] )

Creates a new identifier. You can either pass either identifier's value or a hash of methods with the following parameter names:

valid

A method to check whether the identifier is valid.

normalized

A method that returns a normalized representation of the identifier.

indexed

A method that returns an indexed representation of the identifier.

The methods valid, normalized, and indexed get the identifier's value as parameter when called.

For instance the following code fragment creates an identifier that contains of letters only and is normalized to lowercase:

sub lcalpha {
  my $v = shift;
  $v =~ s/[^a-zA-Z]//g;
  return lc($v);
}
$id = SeeAlso::Identifier->new(
  'valid' => sub {
    my $v = shift;
    return $v =~ /^[a-zA-Z]+$/;
  },
  'normalized' => \&lcalpha
);
$id->value("AbC");

value ( [ $value ] )

Get and/or set the value of this identifier.

normalized

Return a normalized representation of this identifier. By default this is what the value method returns.

indexed

Return the index value of this identifier. By default this is the normalized form but you may extend the identifier to use some kind of hash value.

valid

Returns whether this identifier is valid. By default all non empty identifiers (everything but '' and undef) are valid.