- NAME
- SYNOPSIS
- DESCRIPTION
- EXAMPLE
- METHODS/FUNCTIONS

- Dumper
- dump
- dump_structure

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# NAME

GT::Dumper - Convert Perl data structures into a string.

# SYNOPSIS

        use GT::Dumper;
        print Dumper($complex_var);
        print GT::Dumper->dump ( var => '$MYVAR', data => $complex_var);

# DESCRIPTION

GT::Dumper by default exports a method `Dumper()` which will behave similar to Data::Dumper's Dumper(). It differs in that it will only take a single argument, and the variable dumped will be $VAR instead of $VAR1. Also, to provide easier control to change the variable name that gets dumped, you can use:

        GT::Dumper->dump ( var => string, data => yourdata );

and the dump will start with string = instead of $VAR = .

# EXAMPLE

        use GT::Dumper;
        my %foo;
        my @bar = (1, 2, 3);
        $foo{alpha} = \@bar;
        $foo{beta} = 'a string';
        print Dumper(\%foo);

This will print:

        $VAR = {
            'beta' => 'a string',
            'alpha' => [
                '1',
                '2',
                '3',
            ],
        };

# METHODS/FUNCTIONS

## Dumper

`Dumper()` is exported by default when using GT::Dumper. It takes a single variable and returns a string representation of the variable. The string can then be eval()'ed back into the same data structure.

It takes only one argument - the variable to dump. The return is a string of the form:

$VAR = DATA

where 'DATA' is the actual data structure of the variable. A more powerful and customizable dumping method is the dump method.

## dump

`dump()` provides a more customizable method to dumping a data structure. Through the various options available, listed below, the output of a data structure dump can be formatted in several different ways.

The options are as follows. Only the data option is required.

- data

  The data option takes a data structure to dump. It is required.

- var

  By default, a dump is output as an assignment to `$VAR`. For example, dumping the string `foo` would return: `$VAR = 'foo'`. You can change and even omit the assignment using the `var` option. To specify a different variable, you simply specify it as the value here. To have 'foo' dump as just `'foo'` instead of `$VAR = 'foo'`, specify var as an empty string, or undef.

- tab

  When indenting for complex data structures (array refs, hash refs, etc.) an indent is used. By default, the indent is 4 spaces, however you can change this by using the `tab` option.

- sort

  The `sort` option enables hash key sorting. It is not on by default - to enable, simply specify the sort option with 1 as the value. The default sort method is case-sensitive alphabetical. See the order option for specifying your own sort order.

- order

  When sorting, it is sometimes desirable to use a custom sort order rather than the default case-sensitive alphabetical sort. The `order` option takes a code reference and enables custom sort ordering. The code reference will be passed 4 variables. The first and second are the two items being compared - $a and $b in Perl's sort mechanism. The third and fourth are the values in the hash being sorted. The code reference, like a Perl sort routine, should return -1 if $a should come before $b, 0 if $a and $b are equivelant in your sort order, and 1 if $b should come before $a. Because of scoping and package issues in Perl, it is not possible to directly use $a and $b.

- compress

  The default dump method is to use ' => ' between hash key and value, to use indenting, and to add a line break after each dumped element. You can turn all of these off by using the compress option.

  Compression removes all non-essential characters from the output, thus reducing data size, however also generally making the dump very difficult to read. If enabled, the dumping behaviour is changed as follows:

  - assignment

    If using a var (ie. `$VAR = DATA`), the spaces around the = will be stripped. The output will look like: `$VAR=DATA`

  - hash keys

    Instead of placing the 4 characters ' => ' between hash keys and values, a single ',' will be used.

  - tabs

    Tabs will not be used.

  - newlines

    Normally, a newline character is added after each dumped element. Compress turns this off.

- structure

  The structure option causes the dump to be a valid perl structure rather than a valid perl statement. This differs in two ways - for one, the `var` option is ignored - it is treated as if a blank `var` was entered, thereby not returning an assignment. The other difference is that an an ordinary dump adds a semicolon and newline at the end of the dump, but these are not added when the structure option is enabled.

## dump_structure

This is a quick method to do a structure dump. It takes one argument - the data to dump. Calling: $class->dump_structure($DATA); is identical to calling: $class->dump(data => $DATA, structure => 1); See the structure option.

# SEE ALSO

the Data::Dumper manpage

# MAINTAINER

Jason Rhinelander

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Dumper.pm,v 1.39 2007/02/10 15:59:02 sbeck Exp $