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