NAME

Data::Formatter::Text - Perl extension for formatting data stored in scalars, hashes, and arrays into strings, definition lists, and bulletted lists, etc. using plain ASCII text.

SYNOPSIS

  use Data::Formatter::Text;

  # The only argument to the constructor is a file handle. 
  # If no file handle is specified, output is sent to STDOUT
  my $text = new Data::Formatter::Text(\*STDOUT);

  $text->out('The following foods are tasty:',
             ['Pizza', 'Pumpkin pie', 'Sweet-n-sour Pork']);

  # Outputs,
  #
  # The following foods are tasty:
  #  * Pizza
  #  * Pumpkin pie
  #  * Sweet-n-sour Pork
  #

  $text->out('Do these things to eat an orange:',
            \['Peal it', 'Split it', 'Eat it']);

  # Outputs,
  #
  # Do these things to eat an orange: 
  #  1. Peal it 
  #  2. Split it 
  #  3. Eat it 
  #

  # If you don't need to output to a file, you can also use the format() class method
  # instead of the out() instance method.
  my $nums = Data::Formatter::Text->format(
      'Phone numbers' =>
       { 
           Pat => '123-4567',
           Joe => '999-9999',
           Xenu => '000-0000',
       }); 
                 
  # Stores in $nums:
  #
  # Phone numbers 
  # Joe:  999-9999
  # Pat:  123-4567
  # Xenu: 000-0000
  #

DESCRIPTION

A module that converts Perl data structures into formatted text, much like Data::Dumper, except for that it formats the data nicely for presentation to a human. For instance, refs to arrays are converted into bulleted lists, refs to arrays that contain only refs to arrays are converted into tables, and refs to hashes are converted to definition lists.

All in all, data structures are mapped to display elements as follows:

 SCALAR                    => Text,
 REF to an ARRAY of ARRAYs => Table
 REF to an ARRAY           => Unordered (bulleted) list
 REF to a REF to an ARRAY  => Ordered (numbered) list
 REF to a HASH             => Definition list

Elements can be nested, so, for instance, you may have an array that contains one or more references to arrays, and it will be translated into a nested bulletted list.

Methods

PACKAGE->new()

Returns a newly created Data::Formatter::Text object.

PACKAGE->format(ARRAY)

Returns the string representation of the arguments, formatted nicely.

$OBJ->out(ARRAY)

Outputs the string representation of the arguments to the file stream specified in the constructor.

$OBJ->heading(SCALAR)

Returns a new data-structure containing the same data as SCALAR, but which will be displayed as a heading if passed to out(). Headings are center aligned, made all uppercase, and surrounded by a thick border.

For example,

        $text->out($text->heading("Test Results"), "All is well!");
 

$OBJ->emphasized(SCALAR)

Returns a new data-structure containing the same data as SCALAR, but which will be displayed as emphasized text if passed to out(). Emphasized text is made all uppercase and surrounded by a thin border.

For example,

    $text->out($text->emphasized("Cannot find file!"));

Configuration

$PACKAGE::HEADING_WIDTH

The minimum width of a heading, as created by the heading() method, excluding its surrounding box and measured in characters. By default, this is 50.

@PACKAGE::BULLETS

An array of all the styles of bullet used for bulleted lists, in the order they are used as you move deeper into a nested list. This array must contain at least one element, and by default is equal to ('*', '-', '~').

$PACKAGE::COLUMN_SEPARATOR

The string used to separate columns in a table and draw the vertical portions of its border.

$PACKAGE::ROW_SEPARATOR

The string used to separate rows in a table and draw the horizontal portions of its border.

Example

    $formatter->out('Recipes',
        {
            "Peanutbutter and Jam Sandwich" =>
            [
                ['Ingredient', 'Amount', 'Preparation'],
                ['Bread', '2 slices', ''],
                ['Jam', 'Enough to cover inner face of slice 1', ''],
                ['Peanutbutter', 'Enough to cover inner face of slice 2', '']
            ]
        }
    );

The code above will output the text:

 Recipes
 Peanutbutter and Jam Sandwich:
     ----------------------------------------------------------------
     |Ingredient  |Amount                               |Preparation|
     |------------|-------------------------------------|-----------|
     |Bread       |2 slices                             |           |
     |------------|-------------------------------------|-----------|
     |Jam         |Enough to cover inner face of slice 1|           |
     |------------|-------------------------------------|-----------|
     |Peanutbutter|Enough to cover inner face of slice 2|           |
     ----------------------------------------------------------------

Note that the order of elements in a hash is not necessarily the same as the order the elements are printed in; instead, hash elements are sorted alphabetically by their keys before being output.

AUTHOR

Zachary Blair, <zblair@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Zachary Blair

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.