NAME¶
Text::Aligner
SYNOPSIS¶
use Text::Aligner qw( align);
# Print the words "just a test!" right-justified each on a line:
my @lines = align( 'right', qw( just a test!);
print "$_\n" for @lines;
DESCRIPTION¶
Text::Aligner exports a single function,
align(), which is used to
justify strings to various alignment styles. The alignment specification is
the first argument, followed by any number of scalars which are subject to
alignment.
The operation depends on context. In list context, a list of the justified
scalars is returned. In scalar context, the justified arguments are joined
into a single string with newlines appended. The original arguments remain
unchanged. In void context, in-place justification is attempted. In this case,
all arguments must be lvalues.
Align() also does one level of scalar dereferencing. That is, whenever
one of the arguments is a scalar reference, the scalar pointed to is aligned
instead. Other references are simply stringified. An undefined argument is
interpreted as an empty string without complaint.
Alignment respects colorizing escape sequences a la Term::ANSICOLOR, which means
it knows that thses sequences don't take up space on the screen.
ALIGNMENT¶
The first argument of the
align() function is an alignment style, a
single scalar.
It can be one of the strings "left", "right",
"center", "num", "point", or "auto",
or a regular expression (qr/.../), or a coderef.
A default style of "left" is assumed for every other value, including
"" and undef.
"left", "right" and "center" have the obvious
meanings. These can also be given as numbers 0, 1, and 0.5 respectively.
(Other numbers are also possible, but probably not very useful).
"num", and its synonym "point", specify that the decimal
points be aligned (assumed on the right, unless present). Arbitrary
(non-numeric) strings are also aligned in this manner, so they end up one
column left of the (possibly assumed) decimal point, flush right with any
integers. For the occasional string like "inf", or "-" for
missing values, this may be the right place. A string-only column ends up
right-aligned (unless there are points present).
The "auto" style separates numeric strings (that are composed of
"-", ".", and digits in the usual manner) and aligns them
numerically. Other strings are left aligned with the number that sticks out
farthest to the left. This gives left alignment for string-only columns and
numeric alignment for columns of numbers. In mixed columns, strings are
reasonably placed to serve as column headings or intermediate titles.
With "num" (and "point") it is possible to specify another
character for the decimal point in the form "num(,)". In fact, you
can specify any string after a leading "(", and the closing
")" is optional. "point(=>)" could be used to align
certain pieces of Perl code. This option is currently not available with
"auto" alignment (because recognition of numbers is Anglo-centric).
If a regular expression is specified, the points are aligned where the first
match of the regex starts. A match is assumed immediately after the string if
it doesn't match.
A regular expression is a powerful way of alignment specification. It can
replace most others easily, except center alignment and, of course, the double
action of "auto".
POSITIONERS¶
For entirely self-defined forms of alignment, a coderef, also known as a
positioner, can be given instead of an alignment style. This code will be
called once or more times with the string to be aligned as its argument. It
must return two numbers, a width and a position, that describe how to align a
string with other strings.
The width should normally be the length of the string. The position defines a
point relative to the beginning of the string, which is aligned with the
positions given for other strings.
A zero position for all strings results in left alignment, positioning to the
end of the string results in right alignment, and returning half the length
gives center alignment. "num" alignment is realized by marking the
position of the decimal point.
Note that the position you return is a relative measure. Adding a constant value
to all positions results in no change in alignment. It doesn't have to point
inside the string (as in right alignment, where it points one character past
the end of the string).
The first return value of a positioner should almost always be the length of the
given string. It may be useful to ly about the string length if the string
contains escape sequences that occupy no place on screen.
USAGE¶
use Text::Aligner qw( align);
align( $style, $str, ...);
$style must be given and must be an alignment specification.
Any number of scalars can follow. An argument that contains a
scalar reference is dereferenced before it is used. In scalar
and list context, the aligned strings are returned. In void
context, the values are aligned in place and must be lvalues.
BUGS¶
None known as of realease, but...
AUTHOR¶
Anno Siegel
CPAN ID: ANNO
COPYRIGHT¶
Copyright (c) 2002 Anno Siegel. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms as
Perl itself.
The full text of the license can be found in the LICENSE file included with this
module.
SEE ALSO¶
perl(1)
Text::Table