WARNING - ALPHA CODE (VERY LOOSE API)

We are still experimenting with the standalone filter syntax, so filters written like so may break in the future without any warning!

If you care, or have any suggestions, please drop me a line via RT, email, or find me ('garu') on irc.perl.org.

You have been warned.

DESCRIPTION

Data::Printer lets you add custom filters to display data structures and objects, by either specifying them during "use", in the .dataprinter configuration file, or even in runtime customizations.

But there are times when you may want to group similar filters, or make them standalone in order to be easily reutilized in other environments and applications, or even upload them to CPAN so other people can benefit from a cleaner - and clearer - object/structure dump.

This is where Data::Printer::Filter comes in. It exports into your package's namespace the "filter" function, along with some helpers to create custom filter packages.

Data::Printer recognizes all filters in the Data::Printer::Filter::* namespace. You can load them by specifying them in the '-external' filter list (note the dash, to avoid clashing with a potential class or pragma labelled 'external'):

use Data::Printer {
filters => {
-external => 'MyFilter',
},
};

This will load all filters defined by the Data::Printer::Filter::MyFilter module.

If there are more than one filter, use an array reference instead:

-external => [ 'MyFilter', 'MyOtherFilter' ]

IMPORTANT: THIS WAY OF LOADING EXTERNAL PLUGINS IS EXPERIMENTAL AND SUBJECT TO SUDDEN CHANGE! IF YOU CARE, AND/OR HAVE IDEAS ON A BETTER API, PLEASE LET US KNOW

HELPER FUNCTIONS

filter TYPE, sub { ... };

The filter function creates a new filter for TYPE, using the given subref. The subref receives two arguments: the item itself - be it an object or a reference to a standard Perl type - and the properties in effect (so you can inspect for certain options, etc). The subroutine is expected to return a string containing whatever it wants Data::Printer to display on screen.

p()

This is the same as Data::Printer's p(), only you can't rename it. You can use this to throw some data structures back at Data::Printer and use the results in your own return string - like when manipulating hashes or arrays.

newline()

This helper returns a string using the linebreak as specified by the caller's settings. For instance, it provides the proper indentation level of spaces for you and considers the multiline option to avoid line breakage.

... your p($val) returns will be properly indented, vertically aligned to your level of the data structure, while simply using "\n" would just make things messy if your structure has more than one level of depth.

indent()

outdent()

These two helpers let you increase/decrease the indentation level of your data display, for newline() and nested p() calls inside your filters.

For example, the filter defined in the newline explanation above would show the values on the same (vertically aligned) level as the "I got this array" message. If you wanted your array to be one level further deep, you could use this instead:

COLORIZATION

You can use Term::ANSIColor's colored()' for string colorization. Data::Printer will automatically enable/disable colors for you.

EXISTING FILTERS

This is meant to provide a complete list of standalone filters for Data::Printer available on CPAN. If you write one, please put it under the Data::Printer::Filter::* namespace, and drop me a line so I can add it to this list!

Dates & Times

URIs

Data::Printer::Filter::URI filters through several URI manipulation classes and displays the URI as a colored string. A very nice addition by Stanislaw Pusep (SYP).

USING MORE THAN ONE FILTER FOR THE SAME TYPE/CLASS

As of version 0.13, standalone filters let you stack together filters for the same type or class. Filters of the same type are called in order, until one of them returns a string. This lets you have several filters inspecting the same given value until one of them decides to actually treat it somehow.

If your filter catched a value and you don't want to treat it, simply return and the next filter will be called. If there are no other filters for that particular class or type available, the standard Data::Printer calls will be used.