NAME
Text::Banner - Create text resembling Unix banner command
VERSION
This document refers to Text::Banner version 2.01.
SYNOPSIS
use Text::Banner;
my $ban = Text::Banner->new();
$ban->set('MYTEXT');
$ban->size(3);
$ban->fill('*');
$ban->rotate('h');
print $ban->get();DESCRIPTION
The Text::Banner creates a large ASCII-representation of a defined string, like the 'banner' command available in Unix. A string is passed to the module, and the equivalent banner string is generated and returned for use. The string can be scaled (blown up) from 100 to 500% of the base size. The characters used to generate the banner image can be any character defined by the user (within a limited range) or they can be the made up from whatever the current character being generated happens to be. The banner can be created either vertically or horizontally.
METHODS
new
An object reference is created with the new method. The reference is then used to define the string to create and for manipulation of the object. No specific order is required for object manipulation, with the exception of the 'get' operation which will return the string based upon the current object definitions.
set
The 'set' operation allows the user to specify the string to be generated. There is no limit on the length of the string; however, generated strings that are longer than the display output will continue onto the next line and interlace with the first character that was generated - resulting in a messy, difficult-to-read output. Some experimentation may be required to find the ideal maximum length depending upon the environment you are using.
size
The 'size' operation provides functionality for blowing up the size of the generated string from 100 to 500 percent of normal size. '1' is 100%, '2' is 200% and so on. The larger the defined size, the grainier the output string becomes. When an object is first created, the size defaults to '1'. Calling the 'size' method without any parameters will return the current size definition.
rotate
The 'rotate' method allows switching between horizontal and vertical output. Objects are created by default in horizontal mode. Calling the method without any arguments will return the current output mode. Otherwise, specify either 'h' for horizontal or 'v' for vertical output.
fill
The 'fill' operation defines how the returned string should be created. By default, newly created objects will use the current ASCII character of the character being generated. For example, creating the string 'Hello' without changing the fill character will cause a string to be created where the 'H' is made up of the letter 'H', the 'e' from the letter 'e', 'l' from 'l' and so on. This can be changed if desired by calling the 'fill' operation with the ASCII character you wish all characters of the string to be created from. Once defined, the fill character remains constant until changed again. Calling the fill operation with no parameters will return the currently defined fill character. Calling the fill operation with the command 'reset' will remove the fill character, and default back to the original behaviour as outlined above.
get
The 'get' operation is what causes the string to be generated based upon the current object definitions. The object is generated and passed directly back from the method. Therefore, it can either be printed directly or saved to a variable for later use.
EXAMPLES
# Example 1:
use Text::Banner;
my $h = Text::Banner->new();
$h->set('MYTEXT');
$h->fill('*');
foreach my $num (1..5) {
$h->size($num);
$h->rotate('h');
print $h->get();
$h->rotate('v');
print $h->get();
}
# Example 2:
use Text::Banner;
my $h = Text::Banner->new();
$h->set('MYtext');
print $h->get();
$h->fill('/');
print $h->get();Example 2 would generate the following output:
M M Y Y
MM MM Y Y ttttt eeeeee x x ttttt
M M M M Y Y t e x x t
M M M Y t eeeee xx t
M M Y t e xx t
M M Y t e x x t
M M Y t eeeeee x x t
/ / / /
// // / / ///// ////// / / /////
/ / / / / / / / / / /
/ / / / / ///// // /
/ / / / / // /
/ / / / / / / /
/ / / / ////// / / / Consult the horizontal.txt and vertical.txt files that come with the module for examples of what different sizes look like.
NOTES
Multiple objects can of course be generated; however, it should be kept in mind that the object is not static and changing the defined string output could be used as an alternative to multiple object creation as each created object chews up about 4k of memory.
Generated ASCII characters are restricted to those between 32 (space) and 126 (~). Those outside of these values are removed, and the resulting generated string will not include them. The same restriction applies to the fill character used for defining character generation.
AUTHOR
The original author is Stuart Lory (CPAN ID: LORY).
Gene Sullivan (gsullivan@cpan.org) is a co-maintainer.
COPYRIGHT AND LICENSE
Copyright (c) 1999 Stuart Lory. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.