filled out the prelim docs headers for each example type, and refactors the $fill...
John Napiorkowski [Wed, 6 Apr 2011 02:42:00 +0000 (22:42 -0400)]
t/fill.t

index beba105..dbc9f25 100644 (file)
--- a/t/fill.t
+++ b/t/fill.t
@@ -141,7 +141,7 @@ sub code_stream (&) {
 {
   use Scalar::Util ();
   
-  my $next_item_from_array = sub {
+  my $itr_from_list = sub {
     my @items = @_;
     return sub { shift @items };      
   };
@@ -153,7 +153,7 @@ sub code_stream (&) {
       ref $proto eq 'HASH' ||
       Scalar::Util::blessed($proto)
     ) {
-      return $next_item_from_array->($proto, @_);
+      return $itr_from_list->($proto, @_);
     } elsif(ref $proto eq 'CODE' ) {
       return $proto;
     } else {
@@ -164,16 +164,35 @@ sub code_stream (&) {
   my $normalize_targets = sub {
     my $targets = shift;
     my $targets_type = ref $targets;
-    return $targets_type eq 'ARRAY' ? $targets : do {
-      $targets_type eq 'HASH' ? [ map { +{$_=>$targets->{$_}} } keys %$targets ]
-        : die "targets data structure ". ref($targets). " not understood";
-    }
+    return $targets_type eq 'ARRAY' ?
+      $targets
+      : do {
+        $targets_type eq 'HASH' ?
+          [ map { +{$_=>$targets->{$_}} } keys %$targets ]
+          : die "targets data structure ". ref($targets). " not understood";
+      }
   };
   
-  my $replace_from_hash_or_object = sub {
-    my ($datum, $value) = @_;
-    return ref($datum) eq 'HASH' ?
-      $datum->{$value} : $datum->$value; 
+  my $replace_from_hash = sub {
+    my ($datum, $key) = @_;
+    return $datum->{$key};
+  };
+
+  my $replace_from_array = sub {
+    my ($datum, $target, $idx) = @_;
+    return $datum->[$idx];
+  };
+  
+  my $replace_from_ob = sub {
+    my ($datum, $accessor) = @_;
+    return $datum->$accessor;
+  };
+
+  my $replace_from_proto = sub {
+    return $replace_from_hash->(@_) if ref($_[0]) eq 'HASH';
+    return $replace_from_array->(@_) if ref($_[0]) eq 'ARRAY';
+    return $replace_from_ob->(@_) if Scalar::Util::blessed($_[0]);
+    die "Don't know how to handle ".ref($_[0]);
   };
   
   my $fill = sub {
@@ -191,17 +210,19 @@ sub code_stream (&) {
                 my $target = $targets->[$idx];
                 my ($match, $replace) = do {
                   my $type = ref $target;
-                  $type ? ($type eq 'HASH' ? do { 
-                      my ($match, $value) = %$target;
-                      ($match, ref($value) eq 'CODE' ?
-                        $value->($datum, $idx, $_)
-                        : $replace_from_hash_or_object->($datum, $value))
-                    } : die "What?")
+                  $type ?
+                    $type eq 'HASH' ?
+                      do { 
+                        my ($match, $value) = %$target;
+                        $match, ref($value) eq 'CODE' ?
+                          $value->($datum, $idx, $_)
+                          : $replace_from_proto->($datum, $value)
+                      }
+                      : die "I don't know what to do with target type of $type"
                     : do {
-                        ref($datum) eq 'ARRAY' ?
-                        ($target, $datum->[$idx]) :
-                        ( '.'.$target, $replace_from_hash_or_object->($datum, $target));
-                      };
+                      ( ref $datum eq 'ARRAY' ? $target : ".$target"),
+                      $replace_from_proto->($datum, $target, $idx);
+                    }
                 };
                 $_ = $_->select($match)
                   ->replace_content($replace);                
@@ -215,8 +236,11 @@ sub code_stream (&) {
     });
   };
 
+  ## $fill( \@target, @list[\@values] )
   ## fill a selection from an array of targets, using a list.  Syntax is a bit
-  ## like DBIC->populate
+  ## like DBIC->populate, the first argument is an array of css style selectors
+  ## while the remaining list is a list of arrayrefs where each arrayref item
+  ## matches the expected value for the cooresponding css selection in $target
   
   {
     ok my $z = HTML::Zoom
@@ -234,7 +258,8 @@ sub code_stream (&) {
       'Got correct from repeat_content'
     );  
   }
+
+  ## $fill( \@target, \&code ) 
   ## Same as above but using an iterator coderef instead of a pregenerated list 
   {
     my @items = ( [0,1], [2,3] );
@@ -259,6 +284,7 @@ sub code_stream (&) {
     }
   }
 
+  ## $fill( \@targets[\%pair[$selector, \&code]], @list[\@values] )
   ## Target has a value of a coderef that is expected to take the item from the
   ## list of data and provide the actual value that goes into the target
   
@@ -283,7 +309,8 @@ sub code_stream (&) {
       );
     }
   }
-
+  
+  ## $fill( \@targets[\%pair[$selector, \&code]], @list[\%values] )
   ## Like above but showing how this can be used to get a value from any type of
   ## list item.
   
@@ -308,6 +335,10 @@ sub code_stream (&) {
       );
     }
   }
+
+  ## As above example, but showing how you can an anonymous subroutine in a
+  ## reusable way.  This technique makes the power of closures possible.  Also
+  ## since the current $zoom is passed, opens the possibility for recursivity.
   
   {
     ok my $even_or_odd = sub {
@@ -337,7 +368,7 @@ sub code_stream (&) {
   }
 
   ## Just an example of above showing off how you can use Perl to generate the
-  ## needed structures.
+  ## needed structures.  Does the same thing as the above example.
   
   {
     ok my $even_or_odd = sub {
@@ -364,7 +395,8 @@ sub code_stream (&) {
       );
     }
   }
-
+  
+  ## $fill( \@targets[\%pair[$selector, \&code]], @list[$object] )
   ## using a list of objects, we get replace values.
   
   {
@@ -405,8 +437,11 @@ sub code_stream (&) {
     }
   }
 
+  ## fill( \@targets[\%pair[$selector, $key_or_accessor]], @list[\%values] )
   ## Looks a lot like how pure.js uses 'directives' to map a selector to a value
-  ## from each item in the data list.
+  ## from each item in the data list.  In this example the value part of the
+  ## \@targets pair is a scalar that should be the name of a key (for hashref
+  ## values) or an accessor (as in below example) when the @list is of $objects.
   
   {
     ok my $z = HTML::Zoom
@@ -430,6 +465,8 @@ sub code_stream (&) {
     }
   }
 
+  ## fill( \@targets[\%pair[$selector, $key_or_accessor]], @list[$object] )
+  ## As above example, but with objects instead of plain hashrefs.
   {
     ok my $z = HTML::Zoom
       ->from_html(q[<ul><li class="even">Even</li><li class="odd">Odd</li></ul>])
@@ -452,6 +489,7 @@ sub code_stream (&) {
     }
   }
 
+  ## fill( \%targets, @list[$object] )
   ## Ideally the targets are an array so that you properly control the order that
   ## the replaces happen, but if you don't care you can take advantage of the
   ## shorthand target structure of a hashref
@@ -479,7 +517,7 @@ sub code_stream (&) {
   }
   
   ## Helper for when you have a list of object or hashs and you just want to map
-  ## target classes to accessors
+  ## target classes to accessors.  Otherwise as above example.
   
   {
     ok my $z = HTML::Zoom
@@ -500,6 +538,7 @@ sub code_stream (&) {
     }
   }
 
+  ## fill( \@targets, @list[$object_or_hashref])
   ## if the target is arrayref but the data is a list of objects or hashes, we
   ## guess the target is a class form of the target items, but use the value of
   ## the item as the hash or object accessor