PATCH: adding auto-detection for file types

Mark Stosberg <[email protected]> Sun, 30 Nov 2008 19:02:04 -0500
Newsgroups gmane.comp.lang.perl.modules.html-template
Message-ID <20081130190204.391fcc4e@mat> 
HTML::Template currently supports 4 formats for the input file, with three different APIs 
to specify it:

 First: 
   new( filename   => $f, ... );
   new( scalarref  => $f, ... );
   new( arrayref   => $f, ... );
   new( filehandle => $f, ... );
 
 Second:
   new_file($f, ... );
   new_scalar_ref($f, ... );
   new_array_ref($f, ... );
   new_filehandle($f, ... ); 
 
 Third: 
   new(type => 'filename'  , source => $f, ...);
   new(type => 'scalarref' , source => $f, ...);
   new(type => 'arrayref'  , source => $f, ...);
   new(type => 'filehandle', source => $f, ...);

###

I find these more verbose and confusing than it needs to be. Beecause the
second option provides alternate spellings for 3 out of 4 options, it's hard to
ever get the spelling right without consulting the docs.

I would like to contribute a patch that cleans all this up to this:

  new(source => $filehandle);
  new(source => $filename);
  new(source => $scalarref);
  new(source => $arrayref);

Since we can detect the difference between a string, a scalarref, an arrayref
and a filehandle, we don't need to user to repeat this information for us. It
can "just work". The auto-detection logic would come into play if "source" is
specified, but 'type' is not.

HTML::FillInForm had a similar interface and is a precendent for this kind of API overhaul. 
You can see their old API:

http://search.cpan.org/~tjmather/HTML-FillInForm-2.00/lib/HTML/FillInForm.pm#Old_syntax

And the new API:

http://search.cpan.org/~tjmather/HTML-FillInForm-2.00/lib/HTML/FillInForm.pm#SYNOPSIS

The attach patch includes working code and tests which head in this direction,
but it is not complete. (The current patch auto-detects the first arg, instead of 
the value for 'source').

The final patch would update the docs to highlight the simpler new syntax and
de-emphasize the other interfaces (The same approach used by HTML::FillInForm).
This would simplify things for new users, while users migrating from older
versions would still find the reference docs for the older APIs.

Before proceeding further, I wanted to get some feedback about heading in this
direction.

    Mark

-- 
http://mark.stosberg.com/blog/

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

_______________________________________________
Html-template-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/html-template-users
auto-type.patch (text/x-patch, 2.9 KB) 
Sun Nov 30 18:42:57 EST 2008  Mark Stosberg <[email protected]>
  * Add auto-detection for 3 out of 4 possible file types
diff -rN -u old-HTML-Template-2.9/t/11-non-file-templates.t new-HTML-Template-2.9/t/11-non-file-templates.t
--- old-HTML-Template-2.9/t/11-non-file-templates.t	2008-11-30 18:43:31.000000000 -0500
+++ new-HTML-Template-2.9/t/11-non-file-templates.t	2008-11-30 18:43:31.000000000 -0500
@@ -5,7 +5,9 @@
 
 my ($output, $template, $result);
 my ($fh, $template_string, @template_array,
-    $stemplate, $atemplate, $ftemplate, $fhtemplate, $typetemplate);
+    $stemplate, $atemplate, $fhtemplate,
+    $shortcut_stemplate, $shortcut_atemplate, $shortcut_fhtemplate,
+    $ftemplate, $typetemplate);
 
 $template = HTML::Template->new(
     path => 'templates',
@@ -28,11 +30,16 @@
     \$template_string,
     debug => 0
 );
+$shortcut_stemplate = HTML::Template->new( \$template_string, debug => 0);
 
 $atemplate = HTML::Template->new_array_ref(
     \@template_array,
     debug => 0
 );
+$shortcut_atemplate = HTML::Template->new(
+    \@template_array,
+    debug => 0
+);
 
 $ftemplate = HTML::Template->new_file(
     'simple.tmpl',
@@ -44,6 +51,12 @@
     $fh,
     debug => 0
 );
+seek $fh, 0, 0;
+
+$shortcut_fhtemplate = HTML::Template->new(
+    $fh,
+    debug => 0
+);
 
 $typetemplate = HTML::Template->new(
     type => 'filename',
@@ -52,8 +65,13 @@
     debug => 0
 );
 
-for my $t ($template, $stemplate, $atemplate, $ftemplate,
-           $fhtemplate, $typetemplate) {
+for my $t (
+     $template, $stemplate, $atemplate, $ftemplate,
+          $fhtemplate, $typetemplate,
+           $shortcut_stemplate, $shortcut_atemplate, 
+           $shortcut_fhtemplate,
+       ) {
+
     $t->param('ADJECTIVE', 'very');
     $output =  $t->output;
     ok( ( $output !~ /ADJECTIVE/ and $t->param('ADJECTIVE') eq 'very' ),
diff -rN -u old-HTML-Template-2.9/Template.pm new-HTML-Template-2.9/Template.pm
--- old-HTML-Template-2.9/Template.pm	2008-11-30 18:43:31.000000000 -0500
+++ new-HTML-Template-2.9/Template.pm	2008-11-30 18:43:31.000000000 -0500
@@ -981,6 +981,11 @@
                case_sensitive => 0,
                filter => [],
               );
+
+  # If the first arg to new turns out to a shortcut,
+  # convert it to the more verbose option
+  my $extra = _process_shortcuts_to_new($_[0]);
+  unshift @_, $extra if $extra;
   
   # load in options supplied to new()
   $options = _load_supplied_options( [@_], $options);
@@ -3018,6 +3023,18 @@
     values(%{$obj->[HTML::Template::LOOP::TEMPLATE_HASH]});
 }
 
+sub _process_shortcuts_to_new {
+    my $first_arg = shift;
+
+    my %refs = (
+        'SCALAR' => 'scalarref',
+        'ARRAY'  => 'arrayref',
+        'GLOB'   => 'filehandle',
+    );
+
+    return $refs{ref $first_arg};
+}
+
 # HTML::Template::VAR, LOOP, etc are *light* objects - their internal
 # spec is used above.  No encapsulation or information hiding is to be
 # assumed.