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 {
			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

If you don't like the
syllable counter you can
always 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.

And Michael G Schwern
Carried it back from the dead
And maintains it now.

BUGS

Please report all bugs,
suggestions as well as trouble
to this URL:

http://rt.cpan.org/Public/Dist/Display.html?Name=Coy

The latest version
Can be found for all to see
Posted on github

http://github.com/schwern/coy/tree/master

COPYRIGHT

  Copyright (c) 1998, 2009 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)