spec       => {
     img_1 => {    
         gen_files => {       
             'img_1_thmb_1' => gen_thumb({ w => 100, h => 100 }),
             'img_1_thmb_2' => gen_thumb({ w => 50,  h => 50 }),
           }                                                          
+                                       
     },        
 },
[download]

I've compactly represented that I want to upload one image and from it generate two different thumbnails of different sizes.

The benefit of closures

I want to explain how the gen_thumb() call here works, because it's a uncommon technique that is the crux of building powerful and easy to use declarative interfaces.

The problem is here is that as part of declaring the spec I want to refer to arbitrary chunks of code to transform file uploads, and I want these code references to have options, but I don't have all the data I need to pass into the routine--- we won't get that until the spec is actually used later.

In this case, gen_thumb() also needs at least a file name as input so it has a file to transform. However, you can see that no file name is passed into the function.

A peek inside

What happening is that gen_thumb() is being executed immediately as it would appear to be, but all it does for the moment is to return a custom-built subroutine to be called later. Sort of like this:

sub gen_thumb  {
  my %args = @_;
  return sub {
      my $self = shift;
      my $filename = shift;
      _really_gen_thumb($self, {
              filename => $filename,
              %args,
          });
  }
}
[download]

So we're building the function we'll need later but not actually executing it. The function is designed to receive the object and filename that it will receive later, and blend them with the arguments its getting now.

The ugly alternative

Without using the technique, declarative programming in Perl can become awkward. To illustrate, Here's what the same CGI::Uploader spec looked like before I had this conceptual breakthrough.

 spec => {
   img_1 => {   
     gen_files => {   
           'img_1_thmb_1' => {                                        
+                                  
                   transform_method => \&gen_thumb,                
                   params => [{ w => 100, h => 100 }],                
+                                             
           }                                                          
+                                               
           'img_1_thmb_2' => {                                        
+                                              
                   transform_method => \&gen_thumb, 
                   params => [{ w => 50, h => 50 }], 
           }                                                          
+                                                
   }                                                                  
+                                              
 },   
},
[download]

It worked, but it was unnecessarily unwieldy.

Going further

If functions that generate other functions interest you, I recommend the book Higher Order Perl, which illustrates several other uses besides declarative programming.