AnonymousFox

//usr/local/share/man/man3/Text::Aligner.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Text::Aligner 3"
.TH Text::Aligner 3 "2010-09-11" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Aligner
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Text::Aligner qw( align);
\&
\&  # Print the words "just a test!" right\-justified each on a line:
\&
\&  my @lines = align( \*(Aqright\*(Aq, qw( just a test!);
\&  print "$_\en" for @lines;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Text::Aligner exports a single function, \fIalign()\fR, 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.
.PP
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.
.PP
\&\fIAlign()\fR 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.
.PP
Alignment respects colorizing escape sequences a la Term::ANSICOLOR,
which means it knows that thses sequences don't take up space on
the screen.
.SH "ALIGNMENT"
.IX Header "ALIGNMENT"
The first argument of the \fIalign()\fR function is an alignment style, a
single scalar.
.PP
It can be one of the strings \*(L"left\*(R", \*(L"right\*(R", \*(L"center\*(R", \*(L"num\*(R", \*(L"point\*(R",
or \*(L"auto\*(R", or a regular expression (qr/.../), or a coderef.
.PP
A default style of \*(L"left\*(R" is assumed for every other value, including
"" and undef.
.PP
\&\*(L"left\*(R", \*(L"right\*(R" and \*(L"center\*(R" 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).
.PP
\&\*(L"num\*(R", and its synonym \*(L"point\*(R", 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 \*(L"inf\*(R", or \*(L"\-\*(R" for missing values, this
may be the right place.  A string-only column ends up right-aligned
(unless there are points present).
.PP
The \*(L"auto\*(R" style separates numeric strings (that are composed of
\&\*(L"\-\*(R", \*(L".\*(R", 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.
.PP
With \*(L"num\*(R" (and \*(L"point\*(R") it is possible to specify another character
for the decimal point in the form \*(L"num(,)\*(R".  In fact, you can specify
any string after a leading \*(L"(\*(R", and the closing \*(L")\*(R" is optional.
\&\*(L"point(=>)\*(R" could be used to align certain pieces of Perl code.  This
option is currently not available with \*(L"auto\*(R" alignment (because
recognition of numbers is Anglo-centric).
.PP
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.
.PP
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 \*(L"auto\*(R".
.SH "POSITIONERS"
.IX Header "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.
.PP
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.
.PP
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.  \*(L"num\*(R" alignment is realized
by marking the position of the decimal point.
.PP
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).
.PP
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.
.SH "USAGE"
.IX Header "USAGE"
.Vb 1
\&  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.
.Ve
.SH "BUGS"
.IX Header "BUGS"
.Vb 1
\&  None known as of realease, but...
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\&    Anno Siegel
\&    CPAN ID: ANNO
.Ve
.SH "COPYRIGHT"
.IX Header "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.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1)
.PP
Text::Table