Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Printer::Filter(User Contributed Perl DocumentatData::Printer::Filter(3)

NAME
       Data::Printer::Filter - Create powerful stand-alone filters for
       Data::Printer

SYNOPSIS
       Create your filter module:

	 package Data::Printer::Filter::MyFilter;
	 use strict;
	 use warnings;

	 use Data::Printer::Filter;

	 # type	filter
	 filter	'SCALAR', sub {
	     my	($ref, $properties) = @_;
	     my	$val = $$ref;

	     if	($val >	100) {
		 return	'too big!!';
	     }
	     else {
		 return	$val;
	     }
	 };

	 # you can also	filter objects of any class
	 filter	'Some::Class', sub {
	     my	($object, $properties) = @_;

	     return $ref->some_method;	 # or whatever

	     # see 'HELPER FUNCTIONS' below for
	     # customization options, including
	     # proper indentation.
	 };

	 1;

       Later, in your main code:

	 use Data::Printer {
	     filters =>	{
		 -external => [	'MyFilter', 'OtherFilter' ],

		 # you can still add regular (inline) filters
		 SCALAR	=> sub {
		     ...
		 }
	     },
	 };

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.

   np()
       This is the same	as "Data::Printer"'s np().  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.

       In other	words, if you do this:

	  filter ARRAY => {
	      my ($ref,	$p) = @_;
	      my $string = "Hey!! I got	this array:";

	      foreach my $val (@$ref) {
		  $string .= newline . p($val);
	      }

	      return $string;
	  };

       ... 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:

	 filter	ARRAY => {
	     my	($ref, $p) = @_;
	     my	$string	= "Hey!! I got this array:";

	     indent;
	     foreach my	$val (@$ref) {
		 $string .= newline . p($val);
	     }
	     outdent;

	     return $string;
	 };

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!

   Databases
       Data::Printer::Filter::DB provides filters for Database objects.	So far
       only DBI	is covered, but	more to	come!

   Dates & Times
       Data::Printer::Filter::DateTime pretty-prints several date and time
       objects (not just DateTime) for you on the fly, including
       duration/delta objects!

   Digest
       Data::Printer::Filter::Digest displays a	string containing the hash of
       the actual message digest instead of the	object.	Works on
       "Digest::MD5", "Digest::SHA", any digest	class that inherits from
       "Digest::base" and some others that implement their own thing!

   ClassicRegex
       Data::Printer::Filter::ClassicRegex changes the way Data::Printer dumps
       regular expressions, doing it the classic "qr//"	way that got popular
       in "Data::Dumper".

   JSON
       Data::Printer::Filter::JSON, by Nuba Princigalli, lets you see your
       JSON structures replacing boolean objects with simple "true/false"
       strings!

   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).

   Perl	Data Language (PDL)
       Data::Printer::Filter::PDL, by Zakariyya	Mughal,	lets you quickly see
       the relevant contents of	a PDL variable.

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 caught 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.

       For example:

	 filter	SCALAR => sub {
	     my	($ref, $properties) = @_;
	     if	( Scalar::Util::looks_like_number $$ref	) {
		 return	sprintf	"%.8d",	$$ref;
	     }
	     return; # lets the	other SCALAR filter have a go
	 };

	 filter	SCALAR => sub {
	     my	($ref, $properties) = @_;
	     return qq["$$ref"];
	 };

       Note that this "filter stack" is	not possible on	inline filters,	since
       it's a hash and keys with the same name are overwritten.	Instead, you
       can pass	them as	an array reference:

	 use Data::Printer filters => {
	     SCALAR => [ sub { ... }, sub { ...	} ],
	 };

SEE ALSO
       Data::Printer

LICENSE	AND COPYRIGHT
       Copyright 2011 Breno G. de Oliveira "<garu at cpan.org>". All rights
       reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself. See	perlartistic.

perl v5.24.1			  2017-04-15	      Data::Printer::Filter(3)

NAME | SYNOPSIS | WARNING - ALPHA CODE (VERY LOOSE API) | DESCRIPTION | HELPER FUNCTIONS | COLORIZATION | EXISTING FILTERS | USING MORE THAN ONE FILTER FOR THE SAME TYPE/CLASS | SEE ALSO | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Printer::Filter&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help