Coy






Pair Networks
Coy

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)