new(options)

  Usage:
  $t = Text::ASCIITable->new();

  Or with options:
  $t = Text::ASCIITable->new({ hide_Lastline => 1, reportErrors => 0});

setCols(@cols)

addRow(@collist)

  Note: It does not require argument to be an array, thus;
  $t->addRow(['id','name']) and $t->addRow('id','name') does the same thing.

This module is also overloaded to accept push. To construct a table with the use of overloading you might do the following:

  $t = Text::ASCIITable->new();
  $t->setCols('one','two','three','four');
  push @$t, ( "one\ntwo" ) x 4; # Replaces $t->addrow();
  print $t;                     # Replaces print $t->draw();
  
  Which would construct:
   .-----+-----+-------+------.
   | one | two | three | four |
   |=----+-----+-------+-----=|
   | one | one | one   | one  |  # Note that theese two lines
   | two | two | two   | two  |  # with text are one singe row.
   '-----+-----+-------+------'

There is also possible to give this function an array of arrayrefs and hence support the output from DBI::selectall_arrayref($sql) without changes.

  Example of multiple-rows pushing:
  $t->addRow([
    [ 1, 2, 3 ],
    [ 4, 5, 6 ],
    [ 7, 8, 9 ],
  ]);

addRowLine([$row])

Example without arguments: $t->addRow('one','two','three'); $t->addRowLine(); $t->addRow('one','two','three');

Example with argument: $t->addRow('one','two','three'); $t->addRow('one','two','three'); $t->addRow('one','two','three'); $t->addRow('one','two','three'); $t->addRowLine(1); # or multiple: $t->addRowLine([2,3]);

alignCol($col,$direction) or alignCol({col1 => direction1, col2 => direction2, ... })

alignColName($col,$direction)

setColWidth($col,$width,$strict)

 Usage:
  $t->setColWidth('Description',30);

getTableWidth()

setOptions(name,value) or setOptions({ option1 => value1, option2 => value2, ... })

  Usage:
  $t->setOptions('hide_HeadLine',1);
  
  Or set more than one option on the fly:
  $t->setOptions({ hide_HeadLine => 1, hide_HeadRow => 1 });

Possible Options

hide_HeadRow

Hides output of the columnlisting. Together with hide_HeadLine, this makes a table only show the rows. (However, even though the column-names will not be shown, they will affect the output if they have for example ridiculoustly long names, and the rows contains small amount of info. You would end up with a lot of whitespace)

reportErrors

Set to 0 to disable error reporting. Though if a function encounters an error, it will still return the value 1, to tell you that things didn't go exactly as they should.

allowHTML

If you are going to use Text::ASCIITable to be shown on HTML pages, you should set this option to 1 when you are going to use HTML tags to for example color the text inside the rows, and you want the browser to handle the table correct.

allowANSI

If you use ANSI codes like <ESC>[1mHi this is bold<ESC>[m or similar. This option will make the table to be displayed correct when showed in a ANSI compliant terminal. Set this to 1 to enable. There is an example of ANSI support in this package, named ansi-example.pl.

alignHeadRow

Set wich direction the Column-names(in the headrow) are supposed to point. Must be left, right, center, justify, auto or a user-defined subroutine.

hide_FirstLine, hide_HeadLine, hide_LastLine

Speaks for it self?

drawRowLine

Set this to 1 to print a line between each row. You can also define the outputstyle of this line in the draw() function.

headingText

Add a heading above the columnnames/rows wich uses the whole width of the table to output a heading/title to the table. The heading-part of the table is automatically shown when the headingText option contains text. Note: If this text is so long that it makes the table wider, it will not hesitate to change width of columns that have "strict width".

It supports multiline, and with Text::ASCIITable::Wrap you may wrap your text before entering it, to prevent the title from expanding the table. Internal wrapping-support for headingText might come in the future.

headingAlign

Align the heading(as mentioned above) to left, right, center, auto or using a subroutine.

headingStartChar, headingStopChar

Choose the startingchar and endingchar of the row where the title is. The default is '|' on both. If you didn't understand this, try reading about the draw() function.

cb_count

Set the callback subroutine to use when counting characters inside the table. This is useful to make support for having characters or codes inside the table that are not shown on the screen to the user, so the table should not count these characters. This could be for example HTML tags, or ANSI codes. Though those two examples are alredy supported internally with the allowHTML and allowANSI, options. This option expects a CODE reference. (\&callback_function)

undef_as

Sets the replacing string that replaces an undef value sent to addRow() (or even the overloaded push version of addRow()). The default value is an empty string ''. An example of use would be to set it to '(undef)', to show that the input really was undefined.

chaining

Set this to 1 to support chainging of methods. The default is 0, where the methods return 1 if they come upon an error as mentioned in the reportErrors option description.

  Usage example:
  print Text::ASCIITable->new({ chaining => 1 })
    ->setCols('One','Two','Three')
    ->addRow([
      [ 1, 2, 3 ],
      [ 4, 5, 6 ],
      [ 7, 8, 9 ],
      ])
    ->draw();
    

Note that ->draw() can be omitted, since Text::ASCIITable is overloaded to print the table by default.

draw([@topdesign,@toprow,@middle,@middlerow,@bottom,@rowline])

Custom tables

The draw method takes 6 arrays of strings to define the layout. The first, third, fifth and sixth is LINE layout and the second and fourth is ROW layout. The "fourth" parameter is repeated for each row in the table. The sixth parameter is only used if drawRowLine is enabled.

 $t->draw(<LINE>,<ROW>,<LINE>,<ROW>,<LINE>,[<ROWLINE>])

LINE

Takes an array of 4 strings. For example "['|','|','-','+']"

ROW

Takes an array of 3 strings. You should not give more than one char to any of these parameters, if you do.. it will probably destroy the output.. Unless you do it with the knowledge of how it will end up. An example: "['|','|','+']"

Examples:

The easiest way:

 print $t;

Explanatory example:

 print $t->draw( ['L','R','l','D'],  # LllllllDllllllR
                 ['L','R','D'],      # L info D info R
                 ['L','R','l','D'],  # LllllllDllllllR
                 ['L','R','D'],      # L info D info R
                 ['L','R','l','D']   # LllllllDllllllR
                );

Nice example:

 print $t->draw( ['.','.','-','-'],   # .-------------.
                 ['|','|','|'],       # | info | info |
                 ['|','|','-','-'],   # |-------------|
                 ['|','|','|'],       # | info | info |
                 [' \\','/ ','_','|'] #  \_____|_____/
                );

Nice example2:

 print $t->draw( ['.=','=.','-','-'],   # .=-----------=.
                 ['|','|','|'],         # | info | info |
                 ['|=','=|','-','+'],   # |=-----+-----=|
                 ['|','|','|'],         # | info | info |
                 ["'=","='",'-','-']    # '=-----------='
                );

With Options:

 $t->setOptions('drawRowLine',1);
 print $t->draw( ['.=','=.','-','-'],   # .=-----------=.
                 ['|','|','|'],         # | info | info |
                 ['|-','-|','=','='],   # |-===========-|
                 ['|','|','|'],         # | info | info |
                 ["'=","='",'-','-'],   # '=-----------='
                 ['|=','=|','-','+']    # rowseperator
                );
 Which makes this output:
   .=-----------=.
   | col1 | col2 |
   |-===========-|
   | info | info |
   |=-----+-----=| <-- rowseperator between each row
   | info | info |
   '=-----------='

A tips is to enable allowANSI, and use the extra charset in your terminal to create a beautiful table. But don't expect to get good results if you use ANSI-formatted table with $t->drawPage.

User-defined subroutines for aligning

If you want to format your text more throughoutly than "auto", or think you have a better way of aligning text; you can make your own subroutine.

  Here's a exampleroutine that aligns the text to the right.
  
  sub myownalign_cb {
    my ($text,$length,$count,$strict) = @_;
    $text = (" " x ($length - $count)) . $text;
    return substr($text,0,$length) if ($strict);
    return $text;
  }

  $t->alignCol('Info',\&myownalign_cb);

User-defined subroutines for counting

This is a feature to use if you are not happy with the internal allowHTML or allowANSI support. Given is an example of how you make a count-callback that makes ASCIITable support ANSI codes inside the table. (would make the same result as setting allowANSI to 1)

  $t->setOptions('cb_count',\&myallowansi_cb);
  sub myallowansi_cb {
    $_=shift;
    s/\33\[(\d+(;\d+)?)?[musfwhojBCDHRJK]//g;
    return length($_);
  }

drawPage($page,@topdesign,@toprow,@middle,@middlerow,@bottom,@rowline)

Example:

  $t->setOptions('outputWidth',80);
  for my $page (1..$t->pageCount()) {
    print $t->drawPage($page)."\n";
    print "continued..\n\n";
  }