NAME

Term::Caca - perl interface for libcaca (Colour AsCii Art library)

VERSION

version 1.1.0

SYNOPSIS

use Term::Caca;

my $caca = Term::Caca->new;
$caca->text( [5, 5], "pwn3d");
$caca->refresh;
sleep 3;

DESCRIPTION

Term::Caca is an API for the ASCII drawing library libcaca.

This version of Term::Caca is compatible with the 1.x version of the libcaca library (development has been made against version 0.99.beta17 of the library).

# exports

EXPORTS

use Term::Caca qw/ :all /;          # import all 
# or
use Term::Caca qw/ :colors /;       # import specific group 
# or
use Term::Caca qw/ $LIGHTRED /;     # import specific constant

COLORS

use Term::Caca qw/ :colors /;           # import all colors
# or 
use Term::Caca qw/ $WHITE $LIGHTRED /;  # import specific colors
# or 
use Term::Caca qw/ %COLORS /;           # import colors as a hash
# or
print $Term::Caca::COLORS{WHITE}        # use original array directly

The color constants used by set_ansi_color(). The available colors are

BLACK       BLUE        GREEN       CYAN          RED                 
MAGENTA     BROWN       LIGHTGRAY   DARKGRAY      LIGHTBLUE           
LIGHTGREEN  LIGHTCYAN   LIGHTRED    LIGHTMAGENTA  YELLOW              
WHITE       DEFAULT     TRANSPARENT

EVENTS

use Term::Caca qw/ :events /;                 # import all events
# or 
use Term::Caca qw/ $NO_EVENT $KEY_RELEASE /;  # import specific events
# or 
use Term::Caca qw/ %EVENTS /;                 # import events as a hash
# or
print $Term::Caca::EVENTS{MOUSE_PRESS}        # use original array directly

The event constants used by the mask of wait_for_event(). The available events are

NO_EVENT    ANY_EVENT
KEY_PRESS   KEY_RELEASE
MOUSE_PRESS MOUSE_RELEASE   MOUSE_MOTION
RESIZE      QUIT

METHODS

Constructor

new

Instantiates a Term::Caca object.

Display and Canvas

set_title( $title )

Sets the window title to $title.

Returns the invocant Term::Caca object.

refresh

Refreshes the display.

Returns the invocant Term::Caca object.

set_refresh_delay( $seconds )

Sets the refresh delay in seconds. The refresh delay is used by refresh to achieve constant framerate.

If the time is zero, constant framerate is disabled. This is the default behaviour.

Returns the invocant Term::Caca object.

rendering_time()

Returns the average rendering time, which is measured as the time between two refresh() calls, in seconds. If constant framerate is enabled via set_refresh_delay(), the average rendering time will be close to the requested delay even if the real rendering time was shorter.

clear()

Clears the canvas using the current background color.

Returns the invocant object.

canvas_size

Returns the width and height of the canvas, as a list in an array context, as a array ref in a scalar context.

canvas_width

Returns the canvas width.

canvas_height

Returns the canvas height.

mouse_position

Returns the position of the mouse. In a list context, returns the x, y coordinates, in a scalar context returns them as an array ref.

This function is not reliable if the ncurses or S-Lang drivers are being used, because mouse position is only detected when the mouse is clicked. Other drivers such as X11 work well.

Import/Export

import( $drawing, :$format => 'auto' )

Imports the drawing. The supported formats are

"auto": try to guess the format.
"caca": native libcaca files.
"ansi": ANSI art (CP437 charset with ANSI colour codes).
"text": ASCII text file.
"utf8": UTF-8 text with ANSI color codes.

export( :$format = 'caca' )

Returns the canvas in the given format.

Supported formats are

"caca": native libcaca files.
"ansi": ANSI art (CP437 charset with ANSI colour codes).
"text": ASCII text file.
"html": an HTML page with CSS information.
"html3": an HTML table that should be compatible with most navigators, including textmode ones.
"irc": UTF-8 text with mIRC colour codes.
"ps": a PostScript document.
"svg": an SVG vector image.
"tga": a TGA image.

Colors

set_ansi_color( $foreground, $background )

Sets the foreground and background colors used by primitives, using colors as defined by %COLORS.

$t->set_ansi_color( $LIGHTRED, $WHITE );

Returns the invocant object.

set_color( $foreground, $background )

Sets the foreground and background colors used by primitives.

Each color is an array ref to a ARGB (transparency + RGB) set of values, all between 0 and 15. Alternatively, they can be given as a string of the direct hexadecimal value.

# red on white
$t->set_color( [ 15, 15, 0, 0 ], 'ffff' );

Returns the invocant object.

Text

text( \@coord, $text )

Prints $text at the given coordinates.

Returns the invocant Term::Caca object.

char( \@coord, $char )

Prints the character $char at the given coordinates. If $char is a string of more than one character, only the first character is printed.

Returns the invocant Term::Caca object.

Primitives Drawing

line( \@point_a, \@point_b, :$char = undef )

Draws a line from @point_a to @point_b using the character $char or, if undefined, ascii art.

Returns the invocant object.

polyline( \@points, :$char = undef , :$close = 0 )

Draws the polyline defined by @points, where each point is an array ref of the coordinates. E.g.

$t->polyline( [ [ 0,0 ], [ 10,15 ], [ 20, 15 ] ] );

The lines are drawn using $char or, if not specified, using ascii art.

If $close is true, the end point of the polyline will be connected to the first point.

Returns the invocant Term::Caca object.

circle( \@center, $radius, :$char = '*', :$fill = undef )

Draws a circle centered at @center with a radius of $radius using the character $char or, if not defined, ascii art. if $fill is set to true, the circle is filled with $char as well.

If $fill is defined but $char is not, $fill will be taken as the filling character. I.e.,

$c->circle( [10,10], 5, char => 'x', fill => 1 );
# equivalent to 
$c->circle( [10,10], 5, fill => 'x' );

Returns the invocant object.

ellipse( \@center, $radius_x, $radius_y, :$char = undef, :$fill = undef)

Draws an ellipse centered at @center with an x-axis radius of $radius_x and a y-radius of $radius_y using the character $char or, if not defined, ascii art.

If $fill is defined but $char is not, $fill will be taken as the filling character.

Returns the invocant object.

box( \@top_corner, $width, $height, :$char => undef, :$fill => undef )

Draws a rectangle of dimensions $width and $height with its upper-left corner at @top_corner, using the character $char or, if not defined, ascii art.

If $fill is defined but $char is not, $fill will be taken as the filling character.

Returns the invocant object.

triangle( \@point_a, \@point_b, \@point_c, :$char => undef, :$fill => undef )

Draws a triangle defined by the three given points using the character $char or, if not defined, ascii art.

If $fill is defined but $char is not, $fill will be taken as the filling character.

Returns the invocant object.

Event Handling

wait_for_event( :$mask = $ANY_EVENT, :$timeout = 0 )

Waits and returns a Term::Caca::Event object matching the mask.

$timeout is in seconds. If set to 0, the method returns immediatly and, if no event was found, returns nothing. If $timeout is negative, the method waits forever for an event matching the mask.

# wait for 5 seconds for a key press or the closing of the window
my $event = $t->wait_for_event( 
    mask => $KEY_PRESS | $QUIT, 
    timeout => 5 
);

say "user is idle" unless defined $event;

exit if $event->isa( 'Term::Caca::Event::Quit' );

say "user typed ", $event->char;

AUTHORS

John Beppu <beppu@cpan.org>
Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE, Version 2, December 2004

To install Term::Caca, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Term::Caca

CPAN shell

perl -MCPAN -e shell
install Term::Caca

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

EXPORTS

COLORS

EVENTS

METHODS

Constructor

new

Display and Canvas

set_title( $title )

refresh

set_refresh_delay( $seconds )

rendering_time()

clear()

canvas_size

canvas_width

canvas_height

mouse_position

Import/Export

import( $drawing, :$format => 'auto' )

export( :$format = 'caca' )

Colors

set_ansi_color( $foreground, $background )

set_color( $foreground, $background )

Text

text( \@coord, $text )

char( \@coord, $char )

Primitives Drawing

line( \@point_a, \@point_b, :$char = undef )

polyline( \@points, :$char = undef , :$close = 0 )

circle( \@center, $radius, :$char = '*', :$fill = undef )

ellipse( \@center, $radius_x, $radius_y, :$char = undef, :$fill = undef)

box( \@top_corner, $width, $height, :$char => undef, :$fill => undef )

triangle( \@point_a, \@point_b, \@point_c, :$char => undef, :$fill => undef )

Event Handling

wait_for_event( :$mask = $ANY_EVENT, :$timeout = 0 )

SEE ALSO

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions