Coy3

Usage

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

            use Coy;

            warn "There seems to be a problem";

            die "Looks like it might be fatal";

    # 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";

    # 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

Overview

        Error messages 
        strewn across my terminal. 
        A vein starts to throb.

        Their reproof adds the 
        injury of insult to 
        the shame of failure.

        When a program dies 
        what you need is a moment 
        of serenity.

        The Coy.pm 
        module brings tranquillity 
        to your debugging.

        The module alters 
        the behaviour of C<die> and 
        C<warn> (and C<croak> and C<carp>).

        It also provides 
        C<transcend> and C<enlighten> -- two 
        Zen alternatives.

        Like Carp.pm, 
        Coy reports errors from the 
        caller's point-of-view.

        But it prefaces 
        the bad news of failure with 
        a soothing haiku.

        The haiku are not 
        "canned", but are generated 
        freshly every time.

        Once the haiku is 
        complete, it's prepended to 
        the error message.

        Execution of 
        the original call to
        C<die> or C<warn> resumes.

        Haiku and error
        message strew across my screen. 
        A smile starts to form.

Extending the vocabulary

        Any code placed in
        "$ENV{HOME}/.coyrc"
        runs at compile-time.

        You can use that file
        to extend Coy.pm's
        vocabulary.

        The "SYNOPSIS" at
        the start of this POD shows how
        you might set it up.

        (Eventually
         this section will detail the
         full mechanism.)

Changing the syllable counter

        Real haiku often <BR>
        have imperfect syllable<BR>
        counts.

        The deficiencies of<BR>
        Coy's inbuilt counter are thus<BR>
        artistic virtues.

        But some connoisseurs<BR>
        demand their syllable counts<BR>
        be always exact.

        So if you don't like<BR>
        the syllable counter, Coy<BR>
        let's you replace it.

        Coy provides a sub
        called C<syllable_counter> for
        that very purpose.

        It is passed a sub
        reference. That sub is then used
        to count syllables.

        You can also pass
        the sub's I<name> (that is, pass a
        symbolic reference).

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

        C<syllable_counter>
        can be called from your code, or
        from .coyrc.

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".)