Coy(3pm)						User Contributed Perl Documentation						  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)

perl v5.8.8							    2007-07-30								  Coy(3pm)