Cow(3p)

NAME
Acme::Cow - Talking barnyard animals (or ASCII art in general)

SYNOPSIS
  use Acme::Cow;

  $cow = new Acme::Cow;
  $cow->say("Moo!");
  $cow->print();

  $sheep = new Acme::Cow::Sheep;        # Derived from Acme::Cow
  $sheep->wrap(20);
  $sheep->think();
  $sheep->text("Yeah, but you're taking the universe out of context.");
  $sheep->print(\*STDERR);

  $duck = new Acme::Cow(File => "duck.cow");
  $duck->fill(0);
  $duck->say(`figlet quack`);
  $duck->print($socket);

DESCRIPTION
Acme::Cow is the logical evolution of the old cowsay program. Cows are derived from a base class (Acme::Cow) or from external files.

Cows can be made to say or think many things, optionally filling and justifying their text out to a given margin,

Cows are nothing without the ability to print them, or sling them as strings, or what not.

METHODS

  new

Parameters
    A list of key-value pairs. If you plan to use an external file as the template, you probably want to say:

            $x = new Acme::Cow(File => 'file.cow');

Returns
    A blessed reference to an "Acme::Cow".

  over
Specify (or retrieve) how far to the right (in spaces) the text balloon should be shoved.

Parameters
    (optional) A number.

Returns
    The new value, if set; the existing value if not.

  wrap
Specify (or retrieve) the column at which text inside the balloon should be wrapped. This number is relative to the balloon, not absolute screen position.

Parameters
    (optional) A number.

Returns
    The new value, if set; the existing value if not.

Notes
    The number set here has no effect if you decline filling/adjusting of the balloon text.

  think
Tell the cow to think its text instead of saying it.

Parameters
    (optional) Text to think.

Returns
    None.

  SAY
Tell the cow to say its text instead of thinking it.

Parameters
    (optional) Text to say.

Returns
    None.

  text
Set (or retrieve) the text that the cow will say or think.

Parameters
    A list of lines of text (optionally terminated with newlines) to be displayed inside the balloon.

Returns
    The new text, if set; the current text, if not.

  print
Print a representation of the cow to the specified filehandle (STDOUT by default).

Parameters
    (optional) A filehandle.

Returns
    None.

  fill
Inform the cow to fill and adjust (or not) the text inside its balloon. By default, text inside the balloon is filled and adjusted.

Parameters
    (optional) A scalar; true if you want it to fill and adjust, false otherwise.

Returns
    The current fill/adjust state, or the new one after setting.

  as_string
Render the cow as a string.

Parameters
    (optional) A scalar that can be interpreted as a "STRING" type for "Text::Template".

Returns
    An ASCII rendering of your cow.

Notes
    If you're using an external file for a cow template, any difficulties in processing the file will occur in this method.

    Every time this method is called, the result is recalculated; there is no caching of results.

WRITING YOUR OWN COW FILES
First, get comfortable with "Text::Template" and its capabilities.

{$balloon} is the text balloon; it should be on a line by itself, flush-left. {$tl} and {$tr} are what goes to the text balloon from the thinking/speaking part of the picture; {$tl} is a backslash ("\") for speech, while {$tr} is a slash ("/"); both are a lowercase letter O ("o") for thought. {$el} is a left eye, and {$er} is a right eye; both are "o" by default. Finally {$U} is a tongue, because a capital U looks like a tongue. (Its default value is "U ".) Escape all other curly-braces within the ASCII art with backslashes.

There are two methods to make your own cow file: the standalone file and the Perl module.

For the standalone file, take your piece of ASCII art and modify it according to the "Text::Template" rules above. Note that the balloon must be flush-left in the template if you choose this method. If the balloon isn't meant to be flush-left in the final output, use its over() method.

For a Perl module, you should "use Text::Template;" and declare that your module "ISA" subclass of "Acme::Cow". You may do other modifications to the variables in the template, if you wish. You will most likely need to write appropriate new() and as_string() methods; many examples are provided with the "Acme::Cow" distribution.

Put your module somewhere in your @INC path under the "Acme::Cow::" tree, and use it like a normal "Acme::Cow". Remember that you only inherit methods, not data; any data you want to pull out of "Acme::Cow" should be accessed explicitly. Other than that, make the methods work as expected and you should have a fully functional cow.

HISTORY
They're called "cows" because the original piece of ASCII art was a cow. Since then, many have been contributed (i.e. the author has stolen some) but they're still all cows.

AUTHOR
Tony Monroe <tmonroe plus perl at nog dot net>

SEE ALSO
perl, cowsay, figlet, fortune, cowpm