Coy(3pm)

NAME
    Coy - like Carp only prettier

SYNOPSIS
    # 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

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

AUTHOR
        The Coy.pm
        module was developed by
        Damian Conway.

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)