NAME

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

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!"));

Example

$formatter->out('Recipes',
    {
        "Zack's Kickin' Bannana Milkshake" =>
        [
            ['Ingredient', 'Amount', 'Preparation'],
            ['1% milk', '1 L',    ''],
            ['Ripe Banana', '2 peeled', \['Peel bananas', 'Chop into quarters for blender']],
            ['Organic eggs', '1 whole', \['Crack', 'Pour']],
            ['Wheat germ', '1 tablespoon', ''],
            ['Honey', 'To taste', 'Mix it in well!'],
        ],
        "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|           |
    ----------------------------------------------------------------
Zack's Kickin' Bannana Milkshake:
    --------------------------------------------------------------
    |Ingredient  |Amount      |Preparation                       |
    |------------|------------|----------------------------------|
    |1% milk     |1 L         |                                  |
    |------------|------------|----------------------------------|
    |Ripe Banana |2 peeled    |1.  Peel bananas                  |
    |            |            |2.  Chop into quarters for blender|
    |------------|------------|----------------------------------|
    |Organic eggs|1 whole     |1.  Crack                         |
    |            |            |2.  Pour                          |
    |------------|------------|----------------------------------|
    |Wheat germ  |1 tablespoon|                                  |
    |------------|------------|----------------------------------|
    |Honey       |To taste    |Mix it in well!                   |
    --------------------------------------------------------------

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.

SEE ALSO

Data::Formatter::Html - A compatible module that outputs formatted information using HTML, rather than plain text.

AUTHOR

Zachary Blair, <zack_blair@hotmail.com>

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.