Provided by: libcoy-perl_0.06-10_all bug

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)