String...pyright(3pm)

💖 String::Copyright 💖

okay bestie, welcome to String::Copyright — it's a Perl module (a 3pm one, so you know it's the docs kind) that deals with text-based copyright statements. yes, the boring legal lines. except now they're our problem and we're gonna make them cute. ✨

---

🎀 NAME 🎀

String::Copyright — representation of text-based copyright statements. that's it, that's the whole vibe. 💅

---

🌸 VERSION 🌸

Version 0.003014 🦋

---

✨ SYNOPSIS ✨

here's how you actually use it, bestie:

use String::Copyright;

my $copyright = copyright(<<'END');
copr. © 1999,2000 Foo Barbaz <fb@acme.corp> and Acme Corp.
Copyright (c) 2001,2004 Foo (work address) <foo@zorg.corp>
Copyright 2003, Foo B. and friends
© 2000, 2002 Foo Barbaz <foo@bar.baz>
END

print $copyright;

# Copyright 1999-2000 Foo Barbaz <fb@acme.com> and Acme Corp.
# Copyright 2000, 2002 Foo Barbaz and Acme Corp.
# Copyright 2001, 2004 Foo (work address) <foo@zorg.org>
# Copyright 2003 Foo B. and friends

like… look at that glow-up. messy input in, normalized output out. it ate. 👑

---

💜 DESCRIPTION 💜

String::Copyright finds copyright statements hiding in a string and then serializes them into a normalized format. it's giving detective but for legal text. 🔍✨

---

🌈 OPTIONS 🌈

you can set these by passing them as an argument to the use statement. slay.

⭐ threshold, threshold_before, threshold_after

use String::Copyright { threshold_after => 5 };

okay so this one is about when to stop parsing. it stops after this many lines without copyright info — either before you've found any copyright info at all, or after you've already found some. threshold is the two-for-one deal: it sets both threshold_before and threshold_after at the same time. 🫶

by default it's unset, which means all lines get parsed. no cap. every single one.

⭐ format( &sub )

use String::Copyright { format => \&GNU_style } };

sub GNU_style {
    my ( $years, $owners ) = @_;

    return 'Copyright (C) ' . join '  ', $years || '', $owners || '';
}

you hand it a coderef and it lets you customize the output format. your sub gets the years and the owners, and you return whatever gorgeous string you want. main character formatting energy. 💅

---

🦋 FUNCTIONS 🦋

this module exports exactly one function: copyright. 🌸

it uses Exporter::Tiny to do the exporting, which means you get flexible import options — go read the Exporter::Tiny docs for the details, iykyk.

---

🫶 SEE ALSO 🫶

• Encode
• Exporter::Tiny

---

💀 BUGS/CAVEATS/etc 💀

okay this is the part where we get real. 🫠

• String::Copyright operates on strings, not bytes. data encoded as UTF-8, Latin1 or other formats needs to be decoded to strings before use. do not skip this step bestie i am begging.
• only ASCII characters and © (the copyright sign) are directly processed.
• if the copyright sign isn't detected, or accents / multi-byte characters display wrong, then most likely the data was not decoded into a string. that's the tea. 🍵
• if ranges or lists of years aren't tidied, then maybe it contained non-ASCII whitespace or digits. yeah. sneaky ones.

---

👑 AUTHOR 👑

Jonas Smedegaard <dr@jones.dk> 💖

---

🎀 COPYRIGHT AND LICENSE 🎀

this program is based on the script licensecheck from the KDE SDK, originally introduced by Stefan Westerfeld <stefan@space.twc.de>. iconic lineage fr fr.

Copyright © 2007, 2008 Adam D. Barratt

Copyright © 2005-2012, 2016, 2018, 2020-2021 Jonas Smedegaard

Copyright © 2018, 2020-2021 Purism SPC

this program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. 💜

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU Affero General Public License for more details.

you should have received a copy of the GNU Affero General Public License along with this program. if not, see <https://www.gnu.org/licenses/>. 🫶

---

and that's the whole page, bestie!! ✨ this lil doc drop came from perl v5.36.0, dated 2022-12-17, and lives under the manual name String...pyright(3pm). go forth and normalize those copyrights, you absolute legend. 💅🎀🦋