Ubuntu Manpage: Biblio::SICI - Provides methods for assembling, parsing, manipulating and serialising SICIs

Provided by: libbiblio-sici-perl_0.04-2_all

NAME

       Biblio::SICI - Provides methods for assembling, parsing, manipulating and serialising SICIs

VERSION

       version 0.04

SYNOPSIS

         use Biblio::SICI;

         my $sici = Biblio::SICI->new()->parse($someSICI);

         # or

         my $sici2 = Biblio::SICI->new();

         $sici2->item->issn('0361-526X');

         # ... setting more data attributes ...

         if ( $sici2->is_valid ) {
             say $sici->to_string;
         }

DESCRIPTION

       A "Serial Item and Contribution Identifier" (SICI) is a code (ANSI/NISO standard Z39.56) used to uniquely
       identify specific volumes, articles or other identifiable parts of a periodical.

       This module provides methods for assembling, parsing, manipulating and serialising SICIs.

       Both internal implementation and public API are currently considered BETA and may change without warning
       in a future release. For more information on this have a look at the TODO section below.

WARNING

       This software is currently considered BETA. Things should work as intended and documented but if you use
       it you should test your own software extensively after any update to a new release of Biblio::SICI since
       both API and behaviour might have changed.

CONFIGURATION

       You may specify the following option when instantiating a SICI object (i.e., when calling the "new()"
       constructor):

       "mode"
           Can be either "strict" or "lax".

           "strict"  mode  means that any operation that gets called with an invalid (according to the standard)
           value for an attribute will "die()".

           "lax"  mode  means  that  any  value  is  accepted  and  that  you  can  use  the  "is_valid()"   and
           "list_problems()" methods to analyze the object state.

ATTRIBUTES

       "item"
           An  instance  of  Biblio::SICI::ItemSegment;  this segment contains information about the serial item
           itself.

       "contribution"
           An  instance  of  Biblio::SICI::ContributionSegment;  this  segment  contains  information  about  an
           individual contribution to the whole item, e.g. an article in a journal issue.

       "control"
           An  instance  of  Biblio::SICI::ControlSegment; this segment contains some meta-information about the
           thing described by the SICI and about the SICI itself.

       "mode"
           Describes whether the object enforces strict conformance to the standard  or  not.   Can  be  set  to
           either  "strict" or "lax".  This attribute is the only one that can be specified directly in the call
           of the constructor.

           Please keep in mind that changing the value does not mean that the attributes already present are re-
           checked!

       "parsedString"
           Returns the original string that was passed to the "parse()" method or "undef"  if  "parse"  was  not
           called before.

METHODS

"parse"( STRING )
Tries to disassemble a string passed to it into the various components of a SICI.

If strict mode is enabled, it will "die()" if either the string cannot be parsed or if no valid SICI
can be derived from the string.

If lax mode is enabled, it returns a list of three values:

The first value is "undef" if parsing the string failed, or 0 if the string could be parsed but the
SICI is invalid, or 1 if a valid SICI was found.

The second value is also "undef" if parsing the string failed, or 0 if the string could be parsed but
serializing the SICI does not result in the exact same string or 1 if we get a full round-trip.

The third value is a (possibly empty) array ref with a list of problems the parser detected. Please
note: these problems are distinct from those reported by the "list_problems" method and can be
retrieved again later.

"to_string"
Serializes the object to a string using the separator characters specified in the standard and
returns it together with the check character appended.

Does not verify if the resulting SICI is valid!

STRING "checkchar"()
Stringifies the object first, then calculates (and returns) the checksum character. Does not check,
if the stringified SICI is valid!

"reset"()
Resets all attributes to their default values.

Does not modify the "mode" attribute.

BOOL "is_valid"()
Determines if all of the attribute values stored in the object are valid and returns either a true or
false value.

TODO check if any required information is missing!

HASHREF "list_problems"()
Returns either a hash of hashes of arrays containing the problems that were found when setting the
various attributes of the SICI segments or "undef" if there are no problems.

The first hash level is indexed by the three SICI segments: item, contribution, and/or control.

The level below is indexed by the attribute names (cf. the docs of the segment modules).

For every attribute the third level contains an array reference with descriptive messages.

{
'contribution' => {
'titleCode' => [
'contains more than 6 characters',
],
},
};

TODO check for meta problems (e.g. missing attributes).

TODO

       The parsing of SICI strings sort-of works but I need to find out more about how the code copes with  real
       world SICIs (i.e.  especially those that are slightly malformed or invalid).

       It  would  probably  make for a better programming style if I were using real type specifications for the
       attributes. On the other hand doing so would make the module employ overly  strict  checks  when  dealing
       with  imperfect SICIs.  Since type checks in Moo (or Moose) know nothing about the object, the only other
       solution I can think of would be using objects of type "Biblio::SICI" act as frontend  for  instances  of
       either  Biblio::SICI::Strict  or  Biblio::SICI::Lax.   This  would  require  two  separate  sets  of type
       definitions and make everything more complicated - and I am not sure if would provide us  with  a  better
       way to handle and report formal problems.

       That said, I´m also not particularly happy with how "list_problems()" works right now and I´d be grateful
       for any suggestions for improvements (or for positive feedback if it works for you).

       Also for now only problems with the available data are detected while missing or inconsistend data is not
       checked for.

       And of course we need a more comprehensive test suite.

AUTHOR

       Heiko Jansen <hjansen@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2014 by Heiko Jansen.

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

perl v5.36.0                                       2023-02-06                                  Biblio::SICI(3pm)