Perl Pretty Print Table Assignments

If you’re a programmer, you know the difference between a beginner and a master is the ability to write succinct code that does a great deal with very little work. If you can do this, you can easily raise your productivity and the quality of your work by an order of magnitude. Much more importantly, you can have a lot more fun writing code. Read on to learn how.

Imagine writing a program with a tenth the code you currently use, ending up with ten times the features, getting fewer bugs, improving performance, and lowering maintenance costs. And imagine taking the tedious, repetitive work out, leaving you more time for inspiration and insight. I’ve spent my career doing that in many languages, more and more effectively with each new language I learn.

I’m going to use Perl to demonstrate some techniques to accomplish these goals. Perl is both my first language, and the language in which I’ve most recently gained some proficiency. It lends itself well to these types of discussions.

Trick 1: and

The built-in function is one of the most useful tools in your toolkit. takes a list and applies a code block to every element, returning the list. You can think of it as stream processing: you push the list in one side and get it back on the other side with some transformation applied. Inside the code block, you refer to the current element with the traditional variable. Here’s a really simple example: uppercase every element in a list.

my @lamps = qw(perl php python); my @uc_lamps = map { uc($_) } @lamps; # Result: PERL PHP PYTHON

I just shoved the list in the right side, and it travelled right to left until finally it popped out on the left side and got assigned into . You can do a lot more with , though. In fact, it’s pretty much infinitely powerful when it comes to transforming lists. It’s really just a glorified loop, but if you think of it as a transformation from input to output, you can really make some elegant code with it. Here’s another example – make a key-value hash out of a delimited string:

my $input = "a:1,b:2,d:3"; my %output = map { split(/:/, $_) } split(/,/, $input);

Do you see how that works? As before, start at the right. The function splits the incoming string on the character, and outputs a list. This list goes into the block, which splits each element into key and value. This gets assigned to the hash. That’s a heck of a lot easier than writing loops, and once you are familiar with it, much easier to read, too.

It’s also unsafe code. Here’s why: it doesn’t check for an odd number of elements in the resulting list, which could happen with input that’s not delimited as expected, like this:

my $input = "a1,b:2,d:3,e:f:g"; my %output = map { split(/:/, $_) } split(/,/, $input);

Assigning an odd number of list elements to a hash breaks the association between keys and values. You should always be saying “use warnings FATAL => ‘all’” to catch this, but it’s better to fix the broken code than to make it throw an error. This is a perfect opportunity for another list-oriented construct, , which takes a list on the right-hand-side and outputs every element that passes a certain test. Let’s add a test for splittability, split only into two elements, and re-align the code for readability:

my $input = "a1,b:2,d:3"; my %output = map { split(/:/, $_, 2) } grep { m/:/ } split(/,/, $input);

Now only the valid elements make it into the hash.

Trick 2: implement defaults with

One of the most annoying and tedious things you have to do as a programmer is check your inputs. Let’s just say you’re doing really basic checking to make sure you even have the input you’re expecting, and if you don’t, you’re going to fill it in with defaults. How do you do this? In most languages, you do it with the equivalent of this Perl code:

sub some_func { my ( $a, $b, $c ) = @_; if ( !$a ) { $a = 5; } # Real code here }

Any experienced programmer knows these one-line statements tend to take up a lot of code. In fact, they are veritable screen hogs, with a lower substance-to-lines ratio than most other programming constructs. Your screen fills with code that does nothing much functional, leaving you less space to see the real code, and less brain-power to think about it too. What can you do to fix this?

In Perl, you can use the operator. Its precedence rules are such that it’ll only do an assignment if the value is false (‘false’ generally means zero, undefined, or the empty string):

$a ||= 5;

“But wait just a dang minute!” you say. There are a bunch of other ways to do this, such as these:

$a = $a || 5; $a = 5 unless $a;

(Rhetorical question: how many other languages even have these alternatives?)

So what’s so great about the stuff, if there are so many other good ways to do things? Well, I’ve only shown you one place you can put to work. There are a million. Like , once you start using it, you can’t stop. You can use it for caches, for example:

my %cache; sub expensive_operation { my ( $key ) = @_; $cache{$key} ||= get_from_database($key); return $cache{$key}; }

In this example, getting something from the database is really expensive, so you want to cache it for future calls. The function uses to check the cache and fetch from the database only if the desired value isn’t already cached. This is so idiomatic in Perl, it’s actually called “the Orcish maneuver” (for or cache). But as I said, it’s not the only thing you can do. You can use for sorting on multiple keys, changing light bulbs, and generally achieving world peace.

(Another rhetorical question: why is Visual Basic code so slow to write, so hard to understand, and so verbose? Hint: think about the lack of early termination in statements. is analogous to early termination.)

Trick 3: hash and array slices

Have you ever passed around hashes and arrays and wanted to extract only certain elements from them? Let’s say you have a subroutine that accepts a hash reference. Its job is to reverse the query-string parsing I showed you above. In many languages, you’d have to loop through the hash’s keys, concatenating the key and value with , then concatenating these together with . You can use and to do this much more simply in Perl, like so:

sub make_query_string { my ( $vals ) = @_; return join("&", map { "$_=$vals->{$_}" } keys %$vals); } my %query_params = ( a => 1, b => 2, c => 3, d => 4, ); my $query_string = make_query_string(\%query_params);

That’s already a great improvement over looping, especially since doing it with loops requires keeping track of whether you’re at the first or the last iteration, so you know whether to insert a separator between elements. But what happens when you have a hash that has more keys and values than you want in the query string? This happens a lot. Coincidentally, my boss and I were pair programming today and needed to do this exact thing (maybe that’s why it’s so fresh in my mind).

The most obvious thing to do is build a new hash with only the keys you want, and send that hash to the subroutine:

my @desired = qw(a c); my %new_params; foreach my $key ( @desired ) { $new_params{$key} = $query_params{$key}; } my $query_string = make_query_string(\%new_params);

Ooooh, that’s ugly. We can at least use to get rid of the loop while building the new hash:

my %new_params = map { $_ => $query_params{$_} } @desired;

A hash slice is still better, though. It essentially does what that does, but it’s easier and clearer:

my %new_params; @new_params{@desired} = @query_params{@desired};

I just read a slice of the values from on the right, and assigned them into another slice with the same keys on the left. Here’s the whole thing, rewritten:

sub make_query_string { my ( $vals ) = @_; return join("&", map { "$_=$vals->{$_}" } keys %$vals); } my %query_params = ( a => 1, b => 2, c => 3, d => 4, ); my @desired = qw(a c); my %new_params; @new_params{@desired} = @query_params{@desired}; my $query_string = make_query_string(\%new_params); print "$query_string\n";

Though this is a somewhat contrived example in this article, in real life it’s the furthest thing from contrived. When you write code at a high level of abstraction, many of your subroutines will just receive a hash of this and a list of that, and be expected to “do the right thing” without a lot of fuss. Hash slices make this a lot easier.

Array slices are a related concept. You access a subset of the array elements as an entire list by simply defining the indexes you want:

my @letters = qw(a b c d e f); my @slice = @letters[1, 4, 3]; # @slice is now b, e, d @slice = @letters[0..3, 4]; # @slice is now a, b, c, d, f

Trick 4: executable regular expressions

If you’ve programmed in Perl, you’ve used regular expressions. Perl’s regular expressions are so powerful, Perl really redefined what it means to process text with a programming language, and regular expressions in most other languages owe a lot to Perl. But even other languages that implement Perl-compatible regular expressions may not implement some of Perl’s features, because in Perl, regular expressions are an integral part of the language.

One example is the ability to execute the result of a match as code, with the modifier at the end of a substitution. Here’s a real-world example. Let’s search a MySQL foreign key definition for column names and reorder them alphabetically, all in place:

my $fk = "FOREIGN KEY (`seq`, `name`) REFERENCES `tbl` (`seq`, `name`)"; $fk =~ s#(?<=\()([^\)]+)(?=\))#join(', ', sort(split(/, /, $1)))#ge; # $fk is now "FOREIGN KEY (`name`, `seq`) REFERENCES `tbl` (`name`, `seq`)";

If you want to know how that works, read the comments on my earlier post about a duplicate index and foreign key checker for MySQL.

If you’re like me five years ago, you might think that’s scary as hell at first. “Execute arbitrary text as though it’s Perl code!?!? What moron thought up that security exploit waiting to happen and made it part of the language?!?!?”

Wait a minute, though. Is it really insecure to match some text and execute it? No, it’s not. In fact, text you’ve matched with a regular expression is likely to be far better checked, just by the fact that you’ve specified what it has to look like, than most other input to your program. This is much more true than you think. In fact, one of the very safest ways to check any input to your program is by pattern matching. This is such a powerful way to validate input, it’s the main way to untaint data when you’re running in taint mode. This is from the perlsec man page:

Values may be untainted by using them as keys in a hash; otherwise the only way to bypass the tainting mechanism is by referencing subpatterns from a regular expression match. Perl presumes that if you reference a substring using $1, $2, etc., that you knew what you were doing when you wrote the pattern.

I won’t go any further into why it’s inherently safe to use the executable-regular-expression feature, but if you’re not convinced, talk to an experienced programmer about it. I do want to convince you this is incredibly powerful. My example above implements this pseudo-code:

for each string, split it around the delimiters sort it join it back together around the delimiters substitute it back into the original string done

You can write any valid Perl code on the right-hand side. Probably the clearest thing to do is just call a subroutine with the captured text, and do the work there, instead of inlining it all. Here’s my example rewritten with a subroutine, and reformatted with the modifier:

sub split_sort_join { my ($text) = @_; return join( ', ', sort( split( /, /, $text ) ) ); } $fk =~ s/ (?<=\() # Find an opening paren ([^\)]+) # Find everything inside parens (?=\)) # Find a closing paren /split_sort_join($1) # Call split_sort_join on the match /gex;

You can imagine how useful this is if your desired substition is not hard-coded into the right-hand-side of the substitution, too. For example, you could pass a callback function to a subroutine, and use that instead:

sub process_column_names { my ( $fk, $callback ) = @_; $fk =~ s/ (?<=\() # Find an opening paren ([^\)]+) # Find everything inside parens (?=\)) # Find a closing paren /$callback->($1) # Call $callback on the match /gex; return $fk; } print process_column_names( "FOREIGN KEY (`seq`, `name`) REFERENCES `tbl` (`seq`, `name`)", \&split_sort_join ), "\n";

If you’re not a Perl wizard, your head is probably spinning at this point, so I’ll ease off, even though I’m thinking of several other things I want to write about this. Here’s the take-away: it’s safe. It’s powerful. Use it. Once you learn it, you’ll be a much more capable programmer.

Trick 5: dispatch tables of coderefs

Newcomers to Perl often wonder where the statement is. If you really, really want to write something that looks like a or block, you’re a lost soul, but okay, . And before you go there, since I know you’re a lost soul, I’ll give you this ticket to get a slightly cooler room in you-know-where: basically anything you’ll ever want to do is explained in the Perl manual pages. Start with and go from there. Even if I can’t convert you away from , perhaps I’ve made a difference by pointing you towards these man pages. Fare thee well! I hardly knew ye, gentle reader…

If you’re still reading, you’re one of the ones walking the narrow path that leads to victory. Good! Let’s talk about how to execute some code branch depending on the value of a variable. My favorite technique for this is to use a dispatch table of coderefs – references to subroutines. This is a succinct way to dispatch execution to somewhere or other in your program, without the mess and tedious coding you get with statements. Believe me, if you’ve ever tried to maintain someone else’s of any size, you’re going to appreciate this.

Let’s say we have a hypothetical interactive program that waits for you to press a key and then does some function.

Okay, I lied. It’s not hypothetical. I use this technique extensively in innotop. Innotop has many dozens of key mappings, and they are mapped to different things depending on what mode you’re in. “You pressed ? Oh wait, let me scroll through my big honkin’ statement and see what that does… hang on, I’m getting there… can’t find it… oh, you were in that mode! No wonder. Well, let me look at the statement for that mode, then…”

Can you imagine? There’s no way I’d have added so many features to innotop if it were this much of a pain to write, debug and understand. It doesn’t really matter that I wrote it – six months from now, I won’t have a clue what all that code is doing. But I will be able to figure out what a keypress does, because I used a dispatch table.

What exactly is a dispatch table? It’s a hash of references to executable code. Let’s make a simple example: a program that has just two modes, and . Each of these is handled by a subroutine of the same name. Here is a complete program that’ll loop forever until you press :

#!/usr/bin/perl use strict; use warnings FATAL => 'all'; use Term::ReadKey; sub display_a { print "I am in display_a\n"; } sub display_b { print "I am in display_b\n"; } my $dispatch_for = { a => \&display_a, b => \&display_b, q => sub { ReadMode('normal'); exit(0) }, }; while ( 1 ) { print "Press a key!\n"; ReadMode('cbreak'); my $char = ReadKey(10); defined $dispatch_for->{$char} && $dispatch_for->{$char}->(); }

Innotop has tons of such dispatch tables. They’re so simple to use; you just look to see if there’s an entry for whatever your input is, and if so, you call that to do the work. It can be an anonymous subroutine, such as the anonymous ‘quit’ subroutine in the example, or it can be a reference to a named subroutine. If you want a ‘default’ entry, you can do that easily, too:

my $dispatch_for = { a => \&display_a, b => \&display_b, q => sub { ReadMode('normal'); exit(0) }, DEFAULT => sub { print "That key does nothing\n"; }, }; # Later my $func = $dispatch_for->{$char} || $dispatch_for->{DEFAULT}; $func->();

This is much, much simpler than writing statements, nested statements, or many other common programming constructs.

What am I getting at?

There is something common to all five of the tricks I listed. It’s somewhat arbitrary that I listed five (I wanted to keep the article small enough to digest), and it’s a bit arbitrary which five I chose, because I have many more ideas, but can you see the thread running through them?

It’s elimination of repetition.

Whether it’s repetitive typing, or coding constructs that obviously iterate over something, I’m trying to show you ways to a) avoid writing the same code over and over b) avoid reading code that does the same thing over and over.

Why?

Because repetition kills brain cells. When you’re typing nearly the same loop or copy-pasting nearly the same code, your brain is not engaged and productive. You had a moment of insight about how to do something. In a flash, you saw the way to the end product. Now you have to write the code to implement it. Let’s just pretend that takes an hour (on a good day), and you follow it with another insight, and so on, and so on. You only had eight interested, stimulated, excited moments in the whole work day? Shoot yourself now and get it over with!

By the same token, when you’re reading code, you have to follow the program’s logic to understand it. When most programmers study a loop, I’d bet money they mentally “execute the loop,” starting at the beginning and ending at the end, to understand the start, middle and end of the loop. Every careful coder I’ve known does this, at least sometimes, because it’s how you understand what the computer is doing. Mentally executing loops is incredibly draining. It’s just as bad as typing loops!

The reality is probably even worse, because you’re doing both at the same time. As soon as you type a loop, you’re immediately reading it. Reading it. Reading it. As soon as you type – Reading it. As – Reading it. As soon as you – as soon as you type – type – Reading it.

I’m not making this up. Studies show this is how people read any type of written material, on screen or off. In fact, one of the most important and difficult techniques to master in speed reading is to stop re-reading things you’ve just read. I’m doing it right now as I write this, backtracking and editing my writing (sometimes I type with my eyes closed so I can escape this trap more easily).

The combination of writing and reading iterative code is tedious and boring, and if you’re like me, you have a curious and lively mind, and you hate “tedious and boring.” That’s why I love writing code that doesn’t force me to circle like a tiger pacing a cage.

There’s another common thread to everything I wrote, too.

I’m showing you ways to code in a more declarative style.

This is subtle, but after you code in this style for a little while, you’ll come to understand it: it’s not a procedural programming style. It’s declarative, where you say what to do instead of how. It feels much more like writing a specification of the program’s desired behavior, instead of writing how to accomplish that behavior. And when you go back to the code later and read it, or maintain someone else’s code, you appreciate that even more. The program really does become a spec instead of just an implementation. It’s not that obvious at first, or with small programs, but take my word for it, it’s true.

Back to that moment of insight: what if, at the point of inspiration, you could just say “okay computer, do what I want, and you figure out how to do it.” That’s declarative. Really, once you had the inspiration that showed you the way to solve the problem, you didn’t need to write down the code, did you? You understood everything in that moment, and the rest was just tedium. Writing declaratively helps you get through the tedium that much faster.

  • The function is declarative because you specify a transformation and let Perl map it onto each element of a list.
  • Hash and array slices are declarative because you specify what elements you want to read or assign, and let Perl figure out how.
  • is declarative because you let Perl figure out whether the value exists, and whether to fetch a new one if it doesn’t.
  • Executable regular expressions are declarative because you just write a specification (pattern) of what you want to transform, and provide the transformation, and let Perl figure out how to do it.
  • Dispatch tables are declarative because you specify a mapping between some input and some code, and let Perl do the lookup and dispatch.

You can apply these techniques, one way or another, to any programming language. Another great example is the Behaviour JavaScript library, and the techniques it encourages. Or my own JavaScript date formatting and parsing library, which are not only clearer and simpler to use than their alternatives, but much more powerful and waaaay more efficient.

I'm Baron Schwartz, the founder and CEO of VividCortex. I am the author of High Performance MySQL and lots of open-source software for performance analysis, monitoring, and system administration. I contribute to various database communities such as Oracle, PostgreSQL, Redis and MongoDB. More about me.

NAME

Text::Table - Organize Data in Tables

VERSION

version 1.133

SYNOPSIS

use Text::Table; my $tb = Text::Table->new( "Planet", "Radius\nkm", "Density\ng/cm^3" ); $tb->load( [ "Mercury", 2360, 3.7 ], [ "Venus", 6110, 5.1 ], [ "Earth", 6378, 5.52 ], [ "Jupiter", 71030, 1.3 ], ); print $tb;

This prints a table from the given title and data like this:

Planet Radius Density km g/cm^3 Mercury 2360 3.7 Venus 6110 5.1 Earth 6378 5.52 Jupiter 71030 1.3

Note that two-line titles work, and that the planet names are aligned differently than the numbers.

DESCRIPTION

Organization of data in table form is a time-honored and useful method of data representation. While columns of data are trivially generated by computer through formatted output, even simple tasks like keeping titles aligned with the data columns are not trivial, and the one-shot solutions one comes up with tend to be particularly hard to maintain. Text::Table allows you to create and maintain tables that adapt to alignment requirements as you use them.

Overview

The process is simple: you create a table (a Text::Table object) by describing the columns the table is going to have. Then you load lines of data into the table, and finally print the resulting output lines. Alignment of data and column titles is handled dynamically in dependence on the data present.

Table Creation

In the simplest case, if all you want is a number of (untitled) columns, you create an unspecified table and start adding data to it. The number of columns is taken from the first line of data.

To specify a table you specify its columns. A column description can contain a title and alignment requirements for the data, both optional. Additionally, you can specify how the title is aligned with the body of a column, and how the lines of a multiline title are aligned among themselves.

The columns are collected in the table in the order they are given. On data entry, each column corresponds to one data item, and in column selection columns are indexed left to right, starting from 0.

Each title can be a multiline string which will be blank-filled to the length of the longest partial line. The largest number of title lines in a column determines how many title lines the table has as a whole, including the case that no column has any titles.

On output, columns are separated by a single blank. You can control what goes between columns by specifying separators between (or before, or after) columns. Separators don't contain any data and don't count in column indexing. They also don't accumulate: in a sequence of only separators and no columns, only the last one counts.

Status Information

The width (in characters), height (in lines), number of columns, and similar data about the table is available.

Data Loading

Table data is entered line-wise, each time specifying data entries for all table columns. A bulk loader for many lines at once is also available. You can clear the data from the table for re-use (though you will more likely just create another table).

Data can contain colorizing escape sequences (as provided by ) without upsetting the alignment.

Table Output

The output area of a table is divided in the title and the body.

The title contains the combined titles from the table columns, if any. Its content never changes with a given table, but it may be spread out differently on the page through alignment with the data.

The body contains the data lines, aligned column-wise as specified, and left-aligned with the column title.

Each of these is arranged like a Perl array (counting from 0) and can be accessed in portions by specifying a first line and the number of following lines. Also like an array, giving a negative first line counts from the end of the area. The whole table, the title followed by the body, can also be accessed in this manner.

The subdivisions are there so you can repeat the title (or parts of it) along with parts of the body on output, whether for screen paging or printout.

A rule line is also available, which is the horizontal counterpart to the separator columns you specify with the table. It is basically a table line as it would appear if all data entries in the line were empty, that is, a blank line except for where the column separators have non-blank entries. If you print it between data lines, it will not disrupt the vertical separator structure as a plain blank line would. You can also request a solid rule consisting of any character, and even one with the non-blank column separators replaced by a character of your choice. This way you can get the popular representation of line-crossings like so:

| ----+--- |

Warning Control

On table creation, some parameters are checked and warnings issued if you allow warnings. You can also turn warnings into fatal errors.

SPECIFICATIONS

Column Specification

Each column specification is a single scalar. Columns can be either proper data columns or column separators. Both can be specified either as (possibly multi-line) strings, or in a more explicit form as hash-refs. In the string form, proper columns are given as plain strings, and separators are given as scalar references to strings. In hash form, separators have a true value in the field while proper columns don't have this field.

Columns as strings

A column is given as a column title (any number of lines), optionally followed by alignment requirements. Alignment requirements start with a line that begins with an ampersand "&". However, only the last such line counts as such, so if you have title lines that begin with "&", just append an ampersand on a line by itself as a dummy alignment section if you don't have one anyway.

What follows the ampersand on its line is the alignment style (like left, right, ... as described in "Alignment"), you want for the data in this column. If nothing follows, the general default auto is used. If you specify an invalid alignment style, it falls back to left alignment.

The lines that follow can contain sample data for this column. These are considered for alignment in the column, but never actually appear in the output. The effect is to guarantee a minimum width for the column even if the current data doesn't require it. This helps dampen the oscillations in the appearance of dynamically aligned tables.

Columns as Hashes

The format is

{ title => $title, align => $align, sample => $sample, align_title => $align_title, align_title_lines => $align_title_lines, }

$title contains the title lines and $sample the sample data. Both can be given as a string or as an array-ref to the list of lines. $align contains the alignment style (without a leading ampersand), usually as a string. You can also give a regular expression here, which specifies regex alignment. A regex can only be specified in the hash form of a column specification.

In hash form you can also specify how the title of a column is aligned with its body. To do this, you specify the keyword with , or . Other alignment specifications are not valid here. The default is .

also specifies how the lines of a multiline title are aligned among themselves. If you want a different alignment, you can specify it with the key . Again, only , or are allowed.

Do not put other keys than those mentioned above (title, align, align_title, align_title_lines, and sample) into a hash that specifies a column. Most would be ignored, but some would confuse the interpreter (in particular, is_sep has to be avoided).

Separators as strings

A separator must be given as a reference to a string (often a literal, like ), any string that is given directly describes a column.

It is usually just a (short) string that will be printed between table columns on all table lines instead of the default single blank. If you specify two separators (on two lines), the first one will be used in the title and the other in the body of the table.

Separators as Hashes

The hash representation of a separator has the format

{ is_sep => 1, title => $title, body => $body, }

$title is the separator to be used in the title area and $body the one for the body. If only one is given, it will be used for both. If none is given, a blank is used. If one is shorter than the other, it is blank filled on the right.

The value of must be set to a true value, this is the distinguishing feature of a separator.

Alignment

The original documentation to Text::Aligner contains all the details on alignment specification, but here is the rundown:

The possible alignment specifications are left, right, center, num and point (which are synonyms), and auto. The first three explain themselves.

num (and point) align the decimal point in the data, which is assumed to the right if none is present. Strings that aren't numbers are treated the same way, that is, they appear aligned with the integers unless they contain a ".". Instead of the decimal point ".", you can also specify any other string in the form num(,), for instance. The string in parentheses is aligned in the data. The synonym point for num may be more appropriate in contexts that deal with arbitrary strings, as in point(=>) (which might be used to align certain bits of Perl code).

regex alignment is a more sophisticated form of point alignment. If you specify a regular expression, as delivered by , the start of the match is used as the alignment point. If the regex contains capturing parentheses, the last submatch counts. [The usefulness of this feature is under consideration.]

auto alignment combines numeric alignment with left alignment. Data items that look like numbers, and those that don't, form two virtual columns and are aligned accordingly: for numbers and for other strings. These columns are left-aligned with each other (i.e. the narrower one is blank-filled) to form the final alignment.

This way, a column that happens to have only numbers in the data gets num alignment, a column with no numbers appears left-aligned, and mixed data is presented in a reasonable way.

Column Selection

Besides creating tables from scratch, they can be created by selecting columns from an existing table. Tables created this way contain the data from the columns they were built from.

This is done by specifying the columns to select by their index (where negative indices count backward from the last column). The same column can be selected more than once and the sequence of columns can be arbitrarily changed. Separators don't travel with columns, but can be specified between the columns at selection time.

You can make the selection of one or more columns dependent on the data content of one of them. If you specify some of the columns in angle brackets [...], the whole group is only included in the selection if the first column in the group contains any data that evaluates to boolean true. That way you can de-select parts of a table if it contains no interesting data. Any column separators given in brackets are selected or deselected along with the rest of it.

PUBLIC METHODS

Table Creation

new()
my $tb = Text::Table->new( $column, ... );

creates a table with the columns specified. A column can be proper column which contains and displays data, or a separator which tells how to fill the space between columns. The format of the parameters is described under "Column Specification". Specifying an invalid alignment for a column results in a warning if these are allowed.

If no columns are specified, the number of columns is taken from the first line of data added to the table. The effect is as if you had specified , where is the number of columns.

select()
my $sub = $tb->select( $column, ...);

creates a table from the listed columns of the table $tb, including the data. Columns are specified as integer indices which refer to the data columns of $tb. Columns can be repeated and specified in any order. Negative indices count from the last column. If an invalid index is specified, a warning is issued, if allowed.

As with "new()", separators can be interspersed among the column indices and will be used between the columns of the new table.

If you enclose some of the arguments (column indices or separators) in angle brackets (technically, you specify them inside an arrayref), they form a group for conditional selection. The group is only included in the resulting table if the first actual column inside the group contains any data that evaluate to a boolean true. This way you can exclude groups of columns that wouldn't contribute anything interesting. Note that separators are selected and de-selected with their group. That way, more than one separator can appear between adjacent columns. They don't add up, but only the rightmost separator is used. A group that contains only separators is never selected. [Another feature whose usefulness is under consideration.]

Status Information

n_cols()
$tb->n_cols

returns the number of columns in the table.

width()
$tb->width

returns the width (in characters) of the table. All table lines have this length (not counting a final "\n" in the line), as well as the separator lines returned by $tb->rule() and $b->body_rule(). The width of a table can potentially be influenced by any data item in it.

height()
$tb->height

returns the total number of lines in a table, including title lines and body lines. For orthogonality, the synonym table_height() also exists.

table_height()

Same as .

title_height()
$tb->title_height

returns the number of title lines in a table.

body_height()
$tb->body_height

returns the number of lines in the table body.

colrange()
$tb->colrange( $i)

returns the start position and width of the $i-th column (counting from 0) of the table. If $i is negative, counts from the end of the table. If $i is larger than the greatest column index, an imaginary column of width 0 is assumed right of the table.

Data Loading

add()
$tb->add( $col1, ..., $colN)

adds a data line to the table, returns the table.

, ..., are scalars that correspond to the table columns. Undefined entries are converted to '', and extra data beyond the number of table columns is ignored.

Data entries can be multi-line strings. The partial strings all go into the same column. The corresponding fields of other columns remain empty unless there is another multi-line entry in that column that fills the fields. Adding a line with multi-line entries is equivalent to adding multiple lines.

Every call to increases the body height of the table by the number of effective lines, one in the absence of multiline entries.

load()
$tb->load( $line, ...)

loads the data lines given into the table, returns the table.

Every argument to represents a data line to be added to the table. The line can be given as an array(ref) containing the data items, or as a string, which is split on whitespace to retrieve the data. If an undefined argument is given, it is treated as an empty line.

clear()
$tb->clear;

deletes all data from the table and resets it to the state after creation. Returns the table. The body height of a table is 0 after .

Table Output

The three methods , , and are very similar. They access different parts of the printable output lines of a table with similar methods. The details are described with the method.

table()

The method returns lines from the entire table, starting with the first title line and ending with the last body line.

In array context, the lines are returned separately, in scalar context they are joined together in a single string.

my @lines = $tb->table; my $line = $tb->table( $line_number); my @lines = $tb->table( $line_number, $n);

The first call returns all the lines in the table. The second call returns one line given by $line_number. The third call returns $n lines, starting with $line_number. If $line_number is negative, it counts from the end of the array. Unlike the method, (and its sister methods and ) is protected against large negative line numbers, it truncates the range described by $line_number and $n to the existing lines. If $n is 0 or negative, no lines are returned (an empty string in scalar context).

stringify()

Returns a string representation of the table. This method is called for stringification by overload.

my @table_strings = map { $_->stringify() } @tables;
title()

Returns lines from the title area of a table, where the column titles are rendered. Parameters and response to context are as with , but no lines are returned from outside the title area.

body()

Returns lines from the body area of a table, that is the part where the data content is rendered, so that $tb->body( 0) is the first data line. Parameters and response to context are as with .

rule()
$tb->rule; $tb->rule( $char); $tb->rule( $char, $char1); $tb->rule( sub { my ($index, $len) = @_; }, sub { my ($index, $len) = @_; }, );

Returns a rule for the table.

A rule is a line of table width that can be used between table lines to provide visual horizontal divisions, much like column separators provide vertical visual divisions. In its basic form (returned by the first call) it looks like a table line with no data, hence a blank line except for the non-blank parts of any column-separators. If one character is specified (the second call), it replaces the blanks in the first form, but non-blank column separators are retained. If a second character is specified, it replaces the non-blank parts of the separators. So specifying the same character twice gives a solid line of table width. Another useful combo is , together with separators that contain a single nonblank "|", for a popular representation of line crossings.

uses the column separators for the title section if there is a difference.

If callbacks are specified instead of the characters, then they receive the index of the section of the rule they need to render and its desired length in characters, and should return the string to put there. The indexes given are 0 based (where 0 is either the left column separator or the leftmost cell) and the strings will be trimmed or extended in the replacement.

body_rule()

works like <rule()>, except the rule is generated using the column separators for the table body.

Warning Control

warnings()
Text::Table->warnings(); Text::Table->warnings( 'on'); Text::Table->warnings( 'off'): Text::Table->warnings( 'fatal'):

The method is used to control the appearance of warning messages while tables are manipulated. When Text::Table starts, warnings are disabled. The default action of is to turn warnings on. The other possible arguments are self-explanatory. can also be called as an object method ().

VERSION

This document pertains to Text::Table version 1.127

BUGS

o

auto alignment doesn't support alternative characters for the decimal point. This is actually a bug in the underlying Text::Aligner by the same author.

AUTHOR

MAINTAINER

Shlomi Fish, http://www.shlomifish.org/ - CPAN ID: "SHLOMIF".

ORIGINAL AUTHOR

Anno Siegel CPAN ID: ANNO siegel@zrz.tu-berlin.de http://www.tu-berlin.de/~siegel

COPYRIGHT

Copyright (c) 2002 Anno Siegel. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the ISC license.

(This program had been licensed under the same terms as Perl itself up to version 1.118 released on 2011, and was relicensed by permission of its originator).

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

Text::Aligner, perl(1) .

AUTHOR

Shlomi Fish <shlomif@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2002 by Anno Siegel and others.

This is free software, licensed under:

The ISC License

BUGS

Please report any bugs or feature requests on the bugtracker website http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-Table or by email to bug-text-table@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

perldoc Text::Table

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to , or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-Table. You will be automatically notified of any progress on the request by the system.

Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)

https://github.com/shlomif/Text-Table

git clone ssh://git@github.com:shlomif/Text-Table.git

syntax highlighting:

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *