1Text::Aligner(3)      User Contributed Perl Documentation     Text::Aligner(3)
2
3
4

NAME

6       Text::Aligner
7

VERSION

9       version 0.16
10

SYNOPSIS

12         use Text::Aligner qw( align );
13
14         # Print the words "just a test!" right-justified each on a line:
15
16         my @lines = align( 'right', qw( just a test!);
17         print "$_\n" for @lines;
18

DESCRIPTION

20       Text::Aligner exports a single function, align(), which is used to
21       justify strings to various alignment styles.  The alignment
22       specification is the first argument, followed by any number of scalars
23       which are subject to alignment.
24
25       The operation depends on context.  In list context, a list of the
26       justified scalars is returned.  In scalar context, the justified
27       arguments are joined into a single string with newlines appended.  The
28       original arguments remain unchanged.  In void context, in-place
29       justification is attempted.  In this case, all arguments must be
30       lvalues.
31
32       Align() also does one level of scalar dereferencing.  That is, whenever
33       one of the arguments is a scalar reference, the scalar pointed to is
34       aligned instead.  Other references are simply stringified.  An
35       undefined argument is interpreted as an empty string without complaint.
36
37       Alignment respects colorizing escape sequences a la Term::ANSIColor
38       which means it knows that these sequences don't take up space on the
39       screen.
40

NAME

42       Text::Aligner - module to align text.
43

ALIGNMENT

45       The first argument of the align() function is an alignment style, a
46       single scalar.
47
48       It can be one of the strings "left", "right", "center", "num", "point",
49       or "auto", or a regular expression (qr/.../), or a coderef.
50
51       A default style of "left" is assumed for every other value, including
52       "" and undef.
53
54       "left", "right" and "center" have the obvious meanings.  These can also
55       be given as numbers 0, 1, and 0.5 respectively. (Other numbers are also
56       possible, but probably not very useful).
57
58       "num", and its synonym "point", specify that the decimal points be
59       aligned (assumed on the right, unless present).  Arbitrary (non-
60       numeric) strings are also aligned in this manner, so they end up one
61       column left of the (possibly assumed) decimal point, flush right with
62       any integers.  For the occasional string like "inf", or "-" for missing
63       values, this may be the right place.  A string-only column ends up
64       right-aligned (unless there are points present).
65
66       The "auto" style separates numeric strings (that are composed of "-",
67       ".", and digits in the usual manner) and aligns them numerically.
68       Other strings are left aligned with the number that sticks out farthest
69       to the left.  This gives left alignment for string-only columns and
70       numeric alignment for columns of numbers.  In mixed columns, strings
71       are reasonably placed to serve as column headings or intermediate
72       titles.
73
74       With "num" (and "point") it is possible to specify another character
75       for the decimal point in the form "num(,)".  In fact, you can specify
76       any string after a leading "(", and the closing ")" is optional.
77       "point(=>)" could be used to align certain pieces of Perl code.  This
78       option is currently not available with "auto" alignment (because
79       recognition of numbers is Anglo-centric).
80
81       If a regular expression is specified, the points are aligned where the
82       first match of the regex starts.  A match is assumed immediately after
83       the string if it doesn't match.
84
85       A regular expression is a powerful way of alignment specification.  It
86       can replace most others easily, except center alignment and, of course,
87       the double action of "auto".
88

POSITIONERS

90       For entirely self-defined forms of alignment, a coderef, also known as
91       a positioner, can be given instead of an alignment style.  This code
92       will be called once or more times with the string to be aligned as its
93       argument.  It must return two numbers, a width and a position, that
94       describe how to align a string with other strings.
95
96       The width should normally be the length of the string.  The position
97       defines a point relative to the beginning of the string, which is
98       aligned with the positions given for other strings.
99
100       A zero position for all strings results in left alignment, positioning
101       to the end of the string results in right alignment, and returning half
102       the length gives center alignment.  "num" alignment is realized by
103       marking the position of the decimal point.
104
105       Note that the position you return is a relative measure.  Adding a
106       constant value to all positions results in no change in alignment.  It
107       doesn't have to point inside the string (as in right alignment, where
108       it points one character past the end of the string).
109
110       The first return value of a positioner should almost always be the
111       length of the given string.  However, it may be useful to lie about the
112       string length if the string contains escape sequences that occupy no
113       place on screen.
114

SUBROUTINES

116   align($style, $str)
117       See above.
118
119   new(...)
120       For internal use.
121

USAGE

123         use Text::Aligner qw( align );
124
125         align( $style, $str, ...);
126
127         $style must be given and must be an alignment specification.
128         Any number of scalars can follow.  An argument that contains a
129         scalar reference is dereferenced before it is used.  In scalar
130         and list context, the aligned strings are returned.  In void
131         context, the values are aligned in place and must be lvalues.
132

BUGS

134       None known as of release, but...
135

AUTHOR

137           Anno Siegel
138           CPAN ID: ANNO
139
141       Copyright (c) 2002 Anno Siegel. All rights reserved.  This program is
142       free software; you can redistribute it and/or modify it under the terms
143       of the ISC license.
144
145       (This program had been licensed under the same terms as Perl itself up
146       to version 1.118 released on 2011, and was relicensed by permission of
147       its originator).
148
149       The full text of the license can be found in the LICENSE file included
150       with this module.
151

SEE ALSO

153       perl(1)
154
155       Text::Table .
156

AUTHOR

158       Shlomi Fish <shlomif@cpan.org>
159
161       This software is Copyright (c) 2002 by Anno Siegel.
162
163       This is free software, licensed under:
164
165         The ISC License
166
167
168
169perl v5.34.0                      2021-07-23                  Text::Aligner(3)
Impressum