Biblio::SICI(3pm)

💖 Biblio::SICI — the perl one, from the User Contributed Perl Documentation besties 💖

okay so bestie, welcome to Biblio::SICI(3pm), and yes we're about to have a whole moment about serial identifiers. buckle up. 🎀

---

✨ NAME ✨

Biblio::SICI — it literally gives you methods for assembling, parsing, manipulating and serialising SICIs. that's the whole vibe. 💅

---

🌸 VERSION 🌸

version 0.04 — she's young, she's growing, be nice to her 🦋

---

🌈 SYNOPSIS 🌈

look at her go:

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;
}

two ways in, bestie: either you parse a string you already have, or you build one from scratch by setting attributes one at a time. pick your fighter. 🔥

---

🫶 DESCRIPTION 🫶

so a "Serial Item and Contribution Identifier" (SICI for short) is a code — ANSI/NISO standard Z39.56, no cap — that uniquely identifies specific volumes, articles, or other identifiable parts of a periodical. it's giving "this exact article, in this exact issue, of this exact journal" energy. 👑

this module provides methods for assembling, parsing, manipulating and serialising SICIs. that's the job. that's what she does. 💖

and listen — both the internal implementation and the public API are currently considered BETA and may change without warning in a future release. if you wanna know more about that, go peek at the TODO section down below. it's honest in there, we love that. 🙈

---

💀 WARNING 💀

okay this one matters so read it twice:

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.

like. test your stuff after you upgrade. seriously. she said what she said. 😭

---

✨ CONFIGURATION ✨

when you instantiate a SICI object (i.e., when you call the new() constructor), you may specify this one option:

• "mode" — can be either "strict" or "lax". choose your destiny.
  • "strict" mode means that any operation that gets called with an invalid (according to the standard) value for an attribute will die(). she will end you, respectfully.
  • "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. soft girl mode, she accepts you as you are.

---

🎀 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. like the main character article among all the other articles. 👑
• "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. meta af. 🪞
• "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! bestie she is NOT re-validating your past, only your future. 💅

• "parsedString" — returns the original string that was passed to the parse() method or undef if parse was not called before. the receipts, basically. 🧾

---

💜 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:
    1. 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.
    2. 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. 🔁
    3. 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! she's just producing, she's not judging. 🙈

• STRING "checkchar"() — stringifies the object first, then calculates (and returns) the checksum character.

Does not check, if the stringified SICI is valid! again, not judging. 💅

• "reset"() — resets all attributes to their default values.

Does not modify the "mode" attribute. she keeps the vibe, she just clears the data. ✨

• 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.

here's what that looks like, fr fr:

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

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

---

🔥 TODO 🔥

the author is keeping it real in here and honestly? growth. 🌱

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

it would probably make for a better programming style if real type specifications were used 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 that comes to mind would be using objects of type "Biblio::SICI" acting 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 it's not clear if it would provide a better way to handle and report formal problems. 💭

that said, they're also not particularly happy with how list_problems() works right now and would be grateful for any suggestions for improvements (or for positive feedback if it works for you). besties, send feedback, it's free and it's kind. 🫶

also for now only problems with the available data are detected while missing or inconsistent data is not checked for. 👀

and of course a more comprehensive test suite is needed. tests are self care. ✨

---

🌈 SEE ALSO 🌈

• <https://en.wikipedia.org/wiki/Serial_Item_and_Contribution_Identifier>

go read the wiki bestie, it's giving context. 📖

---

👑 AUTHOR 👑

Heiko Jansen <hjansen@cpan.org> — thank you for your service 🫡💖

---

💖 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. free as in freedom, slay. 🕊️

---

and that's the whole page, bestie!! 🎉 this was perl v5.36.0, dated 2023-02-06, and the manual name is Biblio::SICI(3pm) — go forth and identify some serials, you've got this 💅✨🦋