doc for _only methods

[p5sagit/Data-Dumper-Concise.git] / lib / Data / Dumper / Concise / Sugar.pm

diff --git a/lib/Data/Dumper/Concise/Sugar.pm b/lib/Data/Dumper/Concise/Sugar.pm
index 0515052..29400a8 100644 (file)
--- a/lib/Data/Dumper/Concise/Sugar.pm
+++ b/lib/Data/Dumper/Concise/Sugar.pm
@@ -7,12 +7,25 @@ use Data::Dumper::Concise ();
 
 BEGIN { @ISA = qw(Exporter) }
 
-@EXPORT = qw(Dwarn DwarnS);
+@EXPORT = qw(Dwarn DwarnS Dwarn_only DwarnS_only);
+
 
 sub Dwarn { warn Data::Dumper::Concise::Dumper @_; @_ }
 
 sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
 
+sub Dwarn_only (&@) {
+  my $only = shift;
+  warn Data::Dumper::Concise::Dumper $only->(@_);
+  @_
+}
+
+sub DwarnS_only (&$) {
+  my $only = shift;
+  warn Data::Dumper::Concise::Dumper do { local $_ = $_[0]; $only->($_[0]) };
+  $_[0]
+}
+
 =head1 NAME
 
 Data::Dumper::Concise::Sugar - return Dwarn @return_value
@@ -45,6 +58,28 @@ is equivalent to:
   warn Dumper($return);
   return $return;
 
+Sometimes you'll want to C<Dwarn> out part of a result, instead of the entire
+thing; for that we have C<Dwarn_only>:
+
+  # Dwarn the TO_JSON of all the objects in the list
+  my @results = Dwarn_only { map $_->TO_JSON, @_ } some_call(...);
+
+and C<DwarnS_only>:
+
+  # only Dwarn the first item
+  my $data = Dwarn_only { $_->[0] } [ some_call(...) ];
+
+Another trick that is extremely useful when doing method chaining is the
+following:
+
+  my $foo = Bar->new;
+  $foo->bar->baz->Data::Dumper::Concise::Sugar::DwarnS->biff;
+
+which is the same as:
+
+  my $foo = Bar->new;
+  (DwarnS $foo->bar->baz)->biff;
+
 =head1 DESCRIPTION
 
   use Data::Dumper::Concise::Sugar;
@@ -56,10 +91,30 @@ its docs for ways to make it do something else.
 
   sub Dwarn { warn Data::Dumper::Concise::Dumper @_; @_ }
 
-=head3 DwarnS
+=head2 DwarnS
 
   sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
 
-=cut 
+=head2 Dwarn_only
+
+  sub Dwarn_only (&@) {
+    my $only = shift;
+    warn Data::Dumper::Concise::Dumper $only->(@_);
+    @_
+  }
+
+=head2 DwarnS_only
+
+  sub DwarnS_only (&$) {
+    my $only = shift;
+    warn Data::Dumper::Concise::Dumper do { local $_ = $_[0]; $only->($_[0]) };
+    $_[0]
+  }
+
+=head1 SEE ALSO
+
+You probably want L<Devel::Dwarn>, it's the shorter name for this module.
+
+=cut
 
 1;