Coy(3pm)

💖 Coy — like Carp only prettier 💖

okay so bestie, we are in the User Contributed Perl Documentation corner of the manual, and today's entry is Coy(3pm). it is literally described as "like Carp only prettier" and it means that with its entire chest. 🎀 let's get into it.

---

✨ NAME ✨

Coy — like Carp only prettier 🦋

that's the whole name. no notes. iconic.

---

🌸 SYNOPSIS 🌸

okay first up, in your application:

# In your application:
# ====================

        use Coy;

        warn "There seems to be a problem";

        die "Looks like it might be fatal";

and then you can add vocab in the $HOME/.coyrc file, like:

# You can add vocab in the $HOME/.coyrc file:
# ===========================================

        noun RESET; # REMOVE EXISTING noun VOCAB
                    # WORKS FOR OTHER SPECIFIERS TOO

        noun {
                    wookie =>
                    {
                            category => [ Sentient ],
                            sound    => [ "roars", "grunts", "bellows" ],
                            act      =>
                            {
                                    sits   => { location => Arborial },

                                    fights => { minimum => 2,
                                                association => "argument",
                                              },
                            },
                    },

             };

        category {
                    Sentient =>
                    {
                            act =>
                            {
                                    quarrels =>
                                    {
                                            associations => "argument",
                                            location => Terrestrial,
                                            minimum => 2,
                                            synonyms => [qw(bickers argues)],
                                    },
                                    laughs =>
                                    {
                                            associations => "happy",
                                            location => Terrestrial,
                                            non_adjectival => 1,
                                    },
                            },
                    }
                 };

        personage "R2D2";
        personage "Darth Vader";

        place "Mos Eisley";
        place "the Death Star";

        tree "Alderaan mangrove";
        fruit_tree "Wookie-oak";

🫶 head's up: noun RESET; wipes the existing noun vocab — and yes, that same move works for the other specifiers too.

and you can also pick a whole different syllable counter via .coyrc:

# You can also select a different syllable counter via .coyrc
# ===========================================================

        use Lingua::EN::Syllables::syllable;
        syllable_counter  "Lingua::EN::Syllables::syllable";

# or

        use Lingua::EN::Syllables::syllable;
        syllable_counter  \&Lingua::EN::Syllables::syllable;

# or

        syllable_counter  sub { return 1 };  # FAST BUT INACCURATE

---

🌈 DESCRIPTION 🌈

Error messages just strewn all over my terminal. A vein starts to throb. 😭

their reproof is adding the injury of insult to the shame of failure. 💀

so when a program dies what you actually need is a moment of serenity. 🧘

and that's where Coy.pm comes in — it brings tranquillity to your debugging. ✨

here's the tea: the module alters the behaviour of die and warn (and also croak and carp, bestie, it's not leaving them out).

it also provides transcend and enlighten — two Zen alternatives, obsessed with them.

like Carp.pm, Coy reports errors from the caller's point-of-view — so you get the right perspective, no cap.

but here's the slay: it prefaces the bad news of failure with a soothing haiku. 🎐

and those haiku are not "canned" — they're generated freshly every time. no reheated leftovers in this house.

once the haiku is complete, it's prepended to the error message. then execution of the original call to die or warn resumes. periodt.

haiku and error message strew across my screen. a smile starts to form. 💖

---

🌱 EXTENDING THE VOCABULARY 🌱

okay so: any code placed in "$ENV{HOME}/.coyrc" runs at compile-time. that's the whole hook.

and you can use that file to extend Coy.pm's vocabulary — give it more words, more vibes, more range. 💅

the "SYNOPSIS" at the start of this POD shows how you might set it up, if you want a working example to copy.

🙈 (Eventually this section will detail the full mechanism.) so like… for now, bestie, the synopsis is your blueprint.

---

🎵 CHANGING THE SYLLABLE COUNTER 🎵

Real haiku often have imperfect syllable counts.

and honestly? the deficiencies of Coy's inbuilt counter are thus artistic virtues. 🦋

but some connoisseurs demand their syllable counts be always exact.

so if you don't like the syllable counter, Coy let's you replace it.

for that very purpose, Coy provides a sub called syllable_counter.

it is passed a sub reference, and that sub is then used to count syllables.

you can also pass the sub's name — that is, pass a symbolic reference.

the new counter sub should take a string and return its syllable count.

<pink>syllable_counter</pink> can be called from your code, or from .coyrc. either one, dealer's choice. 🫶

---

🐛 BUGS AND LIMITATIONS 🐛

in its current form, the module has four problems and limitations:

• Vocabulary: the list of nouns and verbs is too small at present. this limits the range of topics that the haiku produced can cover. that in turn leads to tell-tale repetition (which fails the Turing test). extending the range of words Coy.pm can use is no problem (though finding the time and the creativity required may be :-)). users of Coy are encouraged to add their own vocabulary. (See the "SYNOPSIS", and also "EXTENDING THE VOCABULARY".)
• Associations: the vocabulary has too few topic links. hence it's often not able to find relevant words for a message. this leads to haiku utterly unrelated to the error text. again, there is no technical difficulty in adding more links: defining enough associations isn't hard, just tedious. user-specified vocabularies can solve this problem as well.
• Limited grammar: the number of syntactic templates is too small. this leads to haiku that are (structurally, at least) monotonous. yet again, this needs no technical solution, just time and effort. of course, such enhanced templates might require richer vocabulary. for example, verb predicates would need extra database structure: each verb entry would have to be extended with links to object nouns.
• Syllable counting: this is perhaps the major problem at present. the algorithmic syllable counter is still being developed. it is currently around 96% accurate (per word). this means that correct syllable counts for haiku can't be guaranteed. syllable counts for single words are correct to plus-or-minus 1. in a multi-word haiku these errors cancel out in most cases. thus, the haiku tend to be correct within one or two syllables. as the syllable counter slowly improves, this problem will abate. alteratively, you can choose to use your own syllable counter. (See above in the section titled "CHANGING THE SYLLABLE COUNTER".)

---

👑 AUTHOR 👑

the Coy.pm module was developed by Damian Conway. living legend behaviour, fr fr.

---

📜 COPYRIGHT 📜

Copyright (c) 1998-2000, Damian Conway. All Rights Reserved.
      This module is free software. It may be used, redistributed
      and/or modified under the terms of the Perl Artistic License
           (see http://www.perl.com/perl/misc/Artistic.html)

---

and that's the whole page, bestie 💜 this one's living in perl v5.36.0, dated 2022-11-19, and it goes by Coy(3pm). go write some haiku errors, you're gonna ate. 🎀✨