1Text::Aligner(3) User Contributed Perl Documentation Text::Aligner(3)
2
6 Text::Aligner
7
9 use Text::Aligner qw( align);
10 # Print the words "just a test!" right-justified each on a line:
12 my @lines = align( 'right', qw( just a test!);
14 print "$_\n" for @lines;
15
17 Text::Aligner exports a single function, align(), which is used to
18 justify strings to various alignment styles. The alignment
19 specification is the first argument, followed by any number of scalars
20 which are subject to alignment.
21 The operation depends on context. In list context, a list of the
23 justified scalars is returned. In scalar context, the justified
24 arguments are joined into a single string with newlines appended. The
25 original arguments remain unchanged. In void context, in-place
26 justification is attempted. In this case, all arguments must be
27 lvalues.
28 Align() also does one level of scalar dereferencing. That is, whenever
30 one of the arguments is a scalar reference, the scalar pointed to is
31 aligned instead. Other references are simply stringified. An
32 undefined argument is interpreted as an empty string without complaint.
33
35 The first argument of the align() function is an alignment style, a
36 single scalar.
37 It can be one of the strings "left", "right", "center", "num", "point",
39 or "auto", or a regular expression (qr/.../), or a coderef.
40 A default style of "left" is assumed for every other value, including
42 "" and undef.
43 "left", "right" and "center" have the obvious meanings. These can also
45 be given as numbers 0, 1, and 0.5 respectively. (Other numbers are also
46 possible, but probably not very useful).
47 "num", and its synonym "point", specify that the decimal points be
49 aligned (assumed on the right, unless present). Arbitrary (non-
50 numeric) strings are also aligned in this manner, so they end up one
51 column left of the (possibly assumed) decimal point, flush right with
52 any integers. For the occasional string like "inf", or "-" for missing
53 values, this may be the right place. A string-only column ends up
54 right-aligned (unless there are points present).
55 The "auto" style seperates numeric strings (that are composed of "-",
57 ".", and digits in the usual manner) and aligns them numerically.
58 Other strings are left aligned with the number that sticks out farthest
59 to the left. This gives left alignment for string-only columns and
60 numeric alignment for columns of numbers. In mixed columns, strings
61 are reasonably placed to serve as column headings or intermediate
62 titles.
63 With "num" (and "point") it is possible to specify another character
65 for the decimal point in the form "num(,)". In fact, you can specify
66 any string after a leading "(", and the closing ")" is optional.
67 "point(=>)" could be used to align certain pieces of Perl code. This
68 option is currently not available with "auto" alignment (because
69 recognition of numbers is Anglo-centric).
70 If a regular expression is specified, the points are aligned where the
72 first match of the regex starts. A match is assumed immediately after
73 the string if it doesn't match.
74 A regular expression is a powerful way of alignment specification. It
76 can replace most others easily, except center alignment and, of course,
77 the double action of "auto".
78
80 For entirely self-defined forms of alignment, a coderef, also known as
81 a positioner, can be given instead of an alignment style. This code
82 will be called once or more times with the string to be aligned as its
83 argument. It must return two numbers, a width and a position, that
84 describe how to align a string with other strings.
85 The width should normally be the length of the string. The position
87 defines a point relative to the beginning of the string, which is
88 aligned with the positions given for other strings.
89 A zero position for all strings results in left alignment, positioning
91 to the end of the string results in right alignment, and returning half
92 the length gives center alignment. "num" alignment is realized by
93 marking the position of the decimal point.
94 Note that the position you return is a relative measure. Adding a
96 constant value to all positions results in no change in alignment. It
97 doesn't have to point inside the string (as in right alignment, where
98 it points one character past the end of the string).
99 The first return value of a positioner should almost always be the
101 length of the given string. It may be useful to ly about the string
102 length if the string contains escape sequences that occupy no place on
103 screen.
104
106 use Text::Aligner qw( align);
107 align( $style, $str, ...);
109 $style must be given and must be an alignment specification.
111 Any number of scalars can follow. An argument that contains a
112 scalar reference is dereferenced before it is used. In scalar
113 and list context, the aligned strings are returned. In void
114 context, the values are aligned in place and must be lvalues.
115
117 None known as of realease, but...
118
120 Anno Siegel
121 CPAN ID: ANNO
122 siegel@zrz.tu-berlin.de
123 http://www.tu-berlin.de/~siegel
124
126 Copyright (c) 2002 Anno Siegel. All rights reserved. This program is
127 free software; you can redistribute it and/or modify it under the same
128 terms as Perl itself.
129 The full text of the license can be found in the LICENSE file included
131 with this module.
132
134 perl(1)
135 Text::Table
137perl v5.12.0 2004-05-04 Text::Aligner(3)