Perl cheese and wine

In case you didn't know from my previous posts, I've been programming in Perl for the last 25 years.

Now during one week of holidays in North Italy, Alto Adige, I accidentally discovered :

• a cheese dairy called "Perl Hof". Unfortunately it was closed when I passed there, so I couldn't taste the products.
• a wine called "Perl", done with grape "Lagrein", very specific of that region.  Quite dark in color,rich and  fruity, very pleasant ... I brought a couple of bottles home :-) Come and see me if you want to taste it !

 

The 3rd generation of DBIx::DataModel is on CPAN

The 3rd generation of DBIx::DataModel has just been published to CPAN.

DBIx::DataModel is an object-relational mapping (ORM) framework for building Perl abstractions (classes, objects and methods) that interact with relational database management systems. It provides facilities for generating SQL queries, joining tables automatically, navigating through the results, converting values, assembling complex datastructures and packaging the results in various formats.Some of its strong points are :

1. centralized, UML-style declaration of tables and relationships (instead of many files with declarations such as 'has_many', 'belongs_to', etc.)
2. limited coupling with the database schema : there is no need to declare every column of every table; DBIx::DataModel only needs to know about tables, associations, primary keys and foreign keys
3. exposure of database operations like joins, bulk updates, subqueries, etc. The database is not hidden behind object-oriented programming concepts, as some other ORMs try to do, but rather made to explicitly collaborate with the object-oriented layer.
4. efficiency through a very lightweight infrastructure and through fine tuning of interaction with the DBI layer (prepare/execute, fetch into reusable memory location, etc.)
5. usage of SQL::Abstract::More for an improved API over SQL::Abstract (named parameters, additional clauses, simplified 'order_by', support for values with associated datatypes, etc.)
6. clear conceptual distinction between:
   • data sources (tables and joins),
   • database statements (stateful objects representing stepwise building of an SQL query and stepwise retrieval of results),
   • data rows (lightweight hashrefs containing nothing but column names and values)
7. simple syntax for joins, with the possibility to override default INNER JOIN/LEFT JOIN properties, and with clever usage of Perl multiple inheritance for simultaneous access to the methods of all tables that participate in that join
8. nested, cross-database transactions
9. choice between 'single-schema' mode (default, more economical) and 'multi-schema' mode (optional, more flexible, but a little more costly in memory)
10. detailed documentation exposing not only the surface API but also the internal architecture and design principles

Initially published in 2005, DBIx::DataModel had a 1^st refactoring in 2008 and a 2^nd refactoring in 2011. Novelties brought by this 3^rd refactoring of 2018 are :

1. architectural simplification : suppression of the ConnectedSource class
2. new extensible architecture for result kinds produced by calls to select(). Builtin result kinds include various datastructure and file formats ; applications can easily plug additional result kinds.
3. facilities for switching between several database schemas within the same database connection
4. method do_after_commit() for registering coderefs to be executed after the end of the outermost transaction.
5. option join_with_USING for generating joins of shape « Table1 JOIN Table 2 USING (common_key) »
6. restructuring of the update() method for easier extension by application subclasses
7. complete revision of the documentation

Very positive and refreshing articles on Perl 5 -- example for embedded systems

 Michel Conrad recently wrote two very positive articles on Perl 5. Those were relayed on the  LinkedIn Perl group but I haven't seen them on  usual Perl sites, so I share them here in the hope they get propagated better. :

 https://opensource.com/article/18/1/why-i-love-perl-5

https://opensource.com/article/18/1/my-delorean-runs-perl

The second article is very interesting in that it shows an unusual application area for Perl : realtime graphics for a car dashboard ! This reminded me of a very interesting presentation many years ago at the French Perl Workshop 2005 , where we saw an application driving all vehicles on the apron of Port Airport.

 

back from Swiss Perl Workshop 2014

The second Swiss Perl Workshop just ended, and it was really nice.

I must confess that I was quite skeptical when Roman and Matthias first came up with such an idea, thinking that Swiss french people would rather go the Journées Perl in Paris, and Swiss german people would rather go to the Deutscher Perl Workshop. But I was wrong : people came, and I was very happy to encounter new local people doing Perl. The organization was tip-top : well-chosen location in the center of Switzerland, in a cosy, ancient house, nice food eaten in the garden, with good Valpolicella ripasso wine.

For this event I expanded my YAPC::EU lightning talk on virtual tables for SQlite : the expanded slides are online at http://www.slideshare.net/ldami/sq-lite-virtualtables. The other talk on App::AutoCRUD was the same as in YAPC (slides here).

Thanks again to Roman and Matthias, and see you next year.

Plack::App::* namespace is not for apps - so which is the proper CPAN namespace ?

OOps ... I just realized that I had misunderstood the intent of the Plack::App namespace : the top-level Plack doc explicitly says :

DO NOT USE Plack:: namespace to build a new web application or a framework. It's like naming your application under CGI:: namespace if it's supposed to run on CGI and that is a really bad choice and would confuse people badly.

and the 2009 Plack Advent Calendar goes even further with

Think twice before using Plack::App::* namespace. Plack::App namespace is for middleware components that do not act as a wrapper but rather an endpoint. Proxy, File, Cascade and URLMap are the good examples. If you write a blog application using Plack, Never call it Plack::App::Blog, okay? Name your software by what it does, not how it's written.

OK, sorry, I got this wrong when publishing Plack::App::AutoCRUD -- but to my excuse, I'm not alone, several other CPAN authors did the same.

The app is quite young, so it is still time to repair its name (even if this operation will be quite tedious, because it involves changes in all module sources, in the CPAN distribution, in the github repository name, and in the upcoming YAPC::EU::2014 talk). But if I want to be a good citizen and engage into such an operation, what should be the proper name ? The CPAN namespace is becoming a bit crowded, as already noted 2 years ago by Joel Berger. For choosing a name, there seem to be several controversial and perhaps contradictory principles :

• CPAN is for modules, not for apps  : this was argued in 2008 in a Perlmonk discussion on the same topic ; however, many people replied in disagreement. I disagree too : publishing a Perl app on CPAN fully makes sense because we take advantage of the CPAN infrastructure for tests, dependency management, publication, etc. Furthermore, applications can be extended or forked, just like modules, so CPAN is a perfect environment for sharing.
  
• publish under the App::* namespace : this is the PAUSE recommendation. But applications in the App::* namespace are mainly  command-line utilities, which is quite different from Web applications. As a matter of fact, nobody used yet the App::Web namespace -- maybe it's time to start ?
  
• use a ::Web or ::WebApp suffix at the end of the module name :  I never saw this as a recommendation, but nevertheless many distributions adopted this approach. This is certainly appropriate if the main goal is to publish a functionality Foo::Bar, and by the way, there is also a web app at Foo::Bar::WebApp. But if the purpose of the whole distribution is just a web app, this approach tends to create a new top-level namespace, which is not considered good practice. Should I choose AutoCRUD::WebApp ? I think not, because other people might want to use the AutoCRUD::* namespace.
  
• avoid top-level namespaces : this used to be an important recommendation, but it doesn't seem to be well respected any more :-( -- nowadays I see more and more CPAN distributions taking up top-level names. I won't cite any particular example, not to offend anybody, but it's quite obvious if you look at the list of top-level namespaces .... and unfortunately many of those top-level names give no clue whatsoever about what kind of functionality will be found in the associated distribution.
  
• hide the technology underlying your app : the Plack argument above says that the app should be named from its functionality, not from its implementation technology. Well ... I'm not so sure that this is always appropriate. Many modules sit under the Tie::Hash::* namespace, just because they used the tied hash technology, for providing various kinds of functionalities.
  Concerning  "Plack", when I see that keyword in a module name, I know that a) this is Web technology, and b) this will work on any kind of web server (as opposed to modules names containing "Apache" or "Apache2"), and I consider this to be useful information for a potential user. On the opposite, I didn't want to name my module DBIx::DataModel::AutoCRUD, even if it uses DBIx::DataModel quite heavily, because that's not hardwired into the architecture and I could easily imagine a later adaptation for supporting as well DBIx::Class.

So in the end I will probably end up with something like App::Web::AutoCRUD or WebApp::AutoCRUD ... unless somebody comes up with a better suggestion !

PS : see also Catalyst::Plugin::AutoCRUD .. which can be used either as a Catalyst plugin or as an application on its own.

Perl virtual tables for DBD::SQLite : ready to test

Followup to my previous article : a first draft of Perl virtual table support for DBD::SQLite is available at https://github.com/DBD-SQLite/DBD-SQLite/tree/vtab .

This is still alpha software, but it shows the idea; I still don't know when this work will be mature enough for a CPAN publication.

Two examples of virtual table modules are bundled with the distribution :

• FileContent : implements a virtual column that exposes file contents. This is especially useful
  in conjunction with a SQLite FTS fulltext index; see the doc in Fulltext_search.pod
• PerlData :  binds a virtual table to a Perl array within the Perl program. This can be used for simple import/export operations, for debugging purposes, for joining data from different
  sources, etc.

I'm currently thinking of one more example , which would be fun to play with : a virtual table that would proxy to another DBI connection. Then we could join data from various sources, using SQLite's features to do the joining work. Sounds quite exciting, but at this point this is just an idea.

Thanks to Salvador Fandiño who pointed me to https://metacpan.org/pod/SQLite::VirtualTable, which is similar in idea but more meant to embed a Perl interpreter inside a sqlite application, rather than the other way around; this code helped me build the DBD::SQLite version.

Of course any comments/suggestions are welcome.

project : Perl virtual tables for DBD::SQLite

During the year I have more and more management tasks and less time for programming. So for the holidays I wanted a change and decided to engage into a really "hardcore programming"  project, namely to add support for Perl virtual tables within the DBD::SQLite database driver. SQLite has this notion of "virtual tables" which look like regular tables but are implemented through callback routines. This project  implies some C programming, using Perl XS API, and the delicate part is to design some appropriate glue between SQLite's notion of "object-oriented", through extensible C structures and callbacks, and Perl's object-oriented features.

At the beginning I wasn't even sure if such a project would be feasible, but now it is slowly taking shape and I'm pretty confident that it will eventually reach something usable. The concept is quite similar to Perl's tied variables, where a published API is reused for accessing many different kinds of data; except that here the published API is SQL instead of hashes or array operators. As a result, we could have virtual tables bound to the filesystem, to the Win32::Registry, to some configuration data, or any other accessible resource. This will open a new field for lots of creative ideas.

My main motivation for doing this work is to be able to build a framework for collections of documents, using SQLite for the fulltext index, and using the filesystem for storing document content : this will be a much more powerful replacement for my very old File::Tabular::Web::Attachment::Indexed module. That module is still heavily used at Geneva courts of law, but now we have 10 years of data, and the old architecture is clearly showing its limits.

For the virtual tables project I need some test cases, so if anybody has ideas about Perl-accessible data to be published as an SQL table, I'm interested.

Perl smartmatch : what now ?

Sorry to wake up an old discussion, but ... does anybody have a clear idea of what is going to happen to smartmatch ?

Our team maintains dozens of internal applications and modules containing "given/when" and smartmatch statements. Most of this code was written between 2007 and 2012 -- remember, at that time smartmatch was an official feature, never mentioned as being "experimental", so we happily used it in many places. The reasons for using smartmatch were quite modest :

• match a scalar against an array
• match 2 scalars, without a warning when one of the scalars is undef
• more readable switch statements, thanks to "given/when"

 When 5.18 came out, I was quite worried about the regression of smartmatch to  "experimental" status, but I was confident that things would be settled in 5.20, so I decided not to upgrade (we still use 5.14). Now 5.20 is out .. and nothing has changed about smartmatch, without even a clue about how this is going to evolve.

Our servers cannot easily upgrade to 5.20, because this would throw warnings all over the place. I tried to find a way to globally turn off these warnings (like set PERL5OPT=-M-warnings=experimental::smartmatch, or  PERL5OPT=-M=experimental::smartmatch), but this doesn't work because the "no warnings" pragma is lexically scoped, so global settings are not taken into account.

So my options are :

1. don't change anything, don't upgrade, and wait for 5.22, hoping that some reasonable form of smartmatch will be reintroduced into the core
2. revise all source files, adding a line "use experimental qw/smartmatch/;" at the beginning of each lexical scope ... but I have no guarantee that this will still work in future versions
3. revise all source files, removing the given/when/smartmatch statements and replacing them with plain old Perl, or with features from some CPAN modules like match::smart or Smart::Match ... but it would be a pity to engage in such work if regular smartmatch comes back in a future version of Perl.

As you can see, none of these options is really satisfactory, so I would be interested in hearing if other companies are in the same situation and how they decided to handle it.

By the way, I love the new Perl way of introducing new features as "experimental", until they become stable and official ... but this only works well when the experimental status is declared from the start. The problem with smartmatch is that it had been official for several years, before being retrograted to experimental. Agreed, the full semantics of smartmatch as published in 10.0 had inconsistencies, but throwing away the whole thing is a bit too harsh -- I'm sure that many users like me would be happy with a reasonable subset of rules for matching common cases.
  

Thanks in advance, Laurent Dami

 

surprising interaction betwen list context and range operator

I was preparing a quiz for Perl programmers, and wanted a question on the difference between arrays and lists. So the question was : what do you get in $x and $y after

my @tab = ( 1, 3, 6..9 );
my $x   = @tab;
my $y   = ( 1, 3, 6..9 );

where I expected $x to be 6 (the number of items) and $y to be 9 (the last element), as documented in perldata. But before distributing the quiz I thought it was worth a test ... and indeed it was! To my surprise, $y turns out to be an empty string. It took me some time to find out why : with

my $y = ( 1, 3, 6, 7, 8, 9 );

the result is 9 indeed. But with

my $y = ( 1, 3, 6..9 );


the interpreter does not build the range in  list context, and then keep the last element. What happens instead is that it throws away the beginning of the list (there is even a warning about that), and then evaluates

my $y = 6..9;


in scalar context; where 6..9 is no longer a range, but a flip-flop operator. Now since the left-hand side is true, that operator is supposed to be true, right ? Well, no, because 6 is a constant, and in that case, perlop tells us that the flip-flop is  "considered true if it is equal (==) to the current input line number (the $. variable)". So $y ends up being an empty string, while

my $six  = 6;
my $nine = 9;
my $y    = $six..$nine;


would yield 1E0!

I couldn't be that nasty to the interviewed programmers, so in the end that question will not be part of the quiz.

Slices of method calls within an object

Several years ago I complained that object accessors prevent you from using some common Perl idioms; in particular, you couldn't take a slice of several attributes within an object.

Now I just discovered the Want module; this is great for playing with lvalue subroutines. With the help of this module, I was finally able to use slices of method calls within an object : see https://metacpan.org/module/Method::Slice . There are some caveats in comparison with a usual hash slice, but nevertheless the main point is there : you can extract some values :

  my @coordinates = mslice($point, qw/x y/);

or even assign to them:

  (mslice($point, qw/x y/)) = (11, 22);

This was written just for fun ... but in the end I might use it in real code, because in some situations, I find slices to be more compact and high-level than multiple assignment statements.

How to test if something is a Perl class ?

For Data::Domain I needed a way to test if something is a Perl class. Since UNIVERSAL is the mother of all classes, it seemed to make sense to define the test as

defined($_) && !ref($_) && $_->isa('UNIVERSAL')

Other people did it through $_->can('can') or UNIVERSAL::can($_, 'can'). Both ways used to work fine, but this is no longer true since June 22, 2012 (bleadperl commit 68b4061) : now just any string matches these conditions.

At first I found this change a bit odd, but somehow it makes sense because any string will answer to the 'can' and 'isa' methods. Also, bless({}, 'Foo') and 'Foo' now return consistent answers for ->isa() and for ->can(), which was not the case before. So let's agree that this change was a good step.


But now it means that  while every object or class is a UNIVERSAL, the reverse is not true : things that are UNIVERSAL are not necessarily objects or classes. Hum ... but what "is a class", really ?

Moose type 'ClassName' defines this through Class::Load::is_class_loaded, which returns true if this is a package with a $VERSION, with an @ISA, or with at least one method. By this definition, an empty package is not a class. However, perldoc says that a class is "just a package", with no restriction.

So after some thoughts I ended up with this implementation :

defined($_) && !ref($_) && $_->can($_)

This returns true for any defined package, false otherwise, and works both before and after June 22.

Thoughts ?

Hash key order : beware of implicit assumptions

Perl hashes are not ordered, so one is not supposed to make assumptions about the key order. I thought I did not ... but Perl 5.17.6 showed me that I was wrong !

About two weeks ago I started receiving report about test failures which were totally incomprehensible to me. Since I work on Windows, I had no bleadperl environment, so it was hard to guess what was wrong just from the test reports. Andreas König kindly opened a ticket in which he spotted that the problem was related to a recent change in bleadperl : now Perl not only makes no guarantee about the key order, it even guarantees that the key order will be different through several runs of the same program!

This convinced me of investing some time to get a bleadperl environment on my Windows machine : VMware player + a virtual Unbutu + perlbrew did the job perfectly. Now I could start working on the bug.

The point were I was making an implicit assumption was a bit nasty, so I thought it was worth writing this post to share it : the code in SQL::Abstract::More more or less went like this :

  my $ops   = join "|", map quotemeta, keys %hash;
  my $regex = qr/^($ops)?($rest_of_regex)/;

See the problem ? The regex starts with an alternation derived from the hash keys. At first glance one would think that the order of members in the alternation is not important ... except when one member is a prefix of the other, because the first member wins. For example, matching "absurd" against qr/^(a|ab|abc)?(.*)/ is not the same as qr/^(abc|ab|a)?(.*)/ : in one case $1 will contain 'a', in the other case it will contain 'ab'.

To fix the problem, the code above was rewritten to put the longest keys first, and everything is fine again.

updated Data::Domain and new Test::InDomain

This is to announce new modules on CPAN:

a) module Data::Domain, written a couple of years ago for checking input from Web forms, now has number of new functionalities in v1.02  : new builtin domains 'Nat', 'Handle', 'Regexp', 'Obj', 'Class', 'Ref', new properties like -isweak, -readonly, etc., and new experimental support for checking method calls and coderef calls. Also, it now relies on Scalar::Does (for having a nice uniform way of checking what references "do" either as builtin Perl operations, or through overloaded methods), and on Sub::Exporter (for allowing clients to rename the imported functions). If you need to check deep datastructures against complex constraints, possibly with contextual dependencies or even recursive rules, then this module may be of interest to you.

b) the new module Test::InDomain is a wrapper around Data::Domain for writing automated tests; it sits more or less in the same niche as Test::Deep, but with a different API and some differences in functionalities.

I hope it might be useful to some of you. Have a look, and let me know of any comments/suggestions.

Rediscovering smart match

Perl's "smart match" operator came with Perl 5.10 in 2007 (as a matter of fact, it was released during the French Perl Workshop 2007, and this is where I also learned about this new feature). I immediately thought : "Wow, this is great, it is going to dramatically change my way of programming!".

Unfortunately, our infrastructure at work still remained Perl 5.8 for several years, and by the time I was at last able to make use of smart match, I had nearly forgotten all its virtues. I have a couple of lines of code with "given/when" statements, but that's mostly it.

However, after having recently attended the excellent class by Damian Conway on Advanced Perl Programming Techniques, smart match came back to my mind. I know, it's been criticized for being too complex in some of its matching rules; but the basic rules are great and yield more readable and more flexible code.

Here are some examples that I'm refactoring right now :

List membership

Instead of 

  if ($data =~ /^(@{[join '|', @array]})$/) {...}

or

  use List::MoreUtils qw/any/;
 if (any {$data eq $_} @array) {...}

write

 if ($data ~~ @array) {...}

No need to test for undef

Instead of

  my $string = $hashref->{some_field} || '';
  if ($string eq 'foo') {...}

write

  if ($hashref->{some_field} ~~ 'foo') {...}

No need to test for numish

Instead of

  use Scalar::Util qw/looks_like_number/;
  my $both_nums = looks_like_number($x)
               && looks_like_number($y);
  if ($both_nums ? $x == $y : $x eq $y) {...}

write

  if ($x ~~ $y) {...}

My slides for FPW12 are online

For info, the slides of my talks at the French Perl Workshop 2012 are now online :

• a comparison of Perl ORMs DBIx::Class and DBIx::DataModel
• a CPAN  module for generating SQL::Abstract datastructures from a web form

Translating user queries into SQL::Abstract (using Regexp::Grammars)

As mentioned in my previous post , I've been quite interested in  Regexp::Grammars recently.

My latest project with it is SQL::Abstract::FromQuery , just released to CPAN. This is a module to help building Web applications with complex search forms. It translates user input, as obtained from an HTML form, into a datastructure suitable as a %where clause for SQL::Abstract; that module will in turn produce the SQL statement and bind parameters to query the database.Users can type regular values, comparison operators, patterns, etc 


Technically, this uses many advanced features of Regexp::Grammars : list results,"autoactions", named grammars, multiple inheritance of grammars and of actions, etc.; so if you ever wondered what these features are good for, here is an example. It also uses some great features of Perl, like dynamic loading of components, dynamic building of an anonymous subclass ... I really feel happy to work with a language that has such a wonderful toolbox.

Nate Wiger, the original author of  SQL::Abstract, already had this vision of translating Web forms into SQL queries; here we elaborate on that idea and support some more details.

The module is still in early infancy, so avoid using it in production (the API probably needs some improvements); suggestions are welcome. Enjoy!

Who is using Regexp::Grammars ?

I've been using Regexp::Grammars for a couple of projects and I find this module really amazing : so much power in such a compact form ! Actually, the whole thing is a gigantic hack, but an extremely clever hack. The learning curve is steep, but once you are used to it, playing with callback actions, grammar inheritance trees or fancy "result distillation" strategies is a joy. The only drawback is that running callback functions within the Perl regexp compiler is sometimes tricky (in Perl versions prior to 5.14, the regexp engine is not reentrant; and debugging may be acrobatic).

I just had a look at the reverse dependencies and was very surprised to find so few CPAN modules that depend on Regexp::Grammars, while its predecessor Parse::RecDescent has many more dependencies. So I'm wondering why Regexp::Grammars is not more widespread. Some guesses :

• the learning curve
• the dependency on perl 5.10 regexes
• the regex engine reentrance problem mentioned above

Any other opinions ?

Plat-forms 2012 : Perl on Amazon Web Services ?

A new edition of the Plat-forms programming competition will take place in Berlin, 2nd to 4th of April --- see the announcement.

I enjoyed participating in the 2007 edition (see our report from that time), so I'm tempted to apply again; currently I'm trying to convince people to join in a team, and to convince my management to support this initiative.

However, my worry is that this year's competition is targeted at cloud computing and Amazon Web Services (AWS),  of which I know nothing ... and the  http://aws.amazon.com/ web site, which advertises "developer centers" for various languages, doesn't say a word about Perl. So it seems that quite an investment will be needed for learning how to use this environment and build up appropriate tools for a Perl AWS ecosystem.

Am I too pessimistic ? Is it much simpler than what I think ? If anybody has information about Perl projects on AWS, please post comments here. Thanks in advance, Laurent D.

Beautiful Riga

This year Perl YAPC::EU::2011 conference brought us to Riga : what a nice discovery!

I barely knew about the existence of this city (apart some vague remembrances of having seen this name when reading Jules Verne's Un drame en Livonie, long long time ago). Now I will recommend it to friends.

Riga has a lot of beautiful buildings, mostly from end of 19th-beginning of 20th century. The Art Nouveau museum has an interesting film explaining various architectural substyles during that period; then you can easily recognize them when walking in the city. By the way, walking is a pleasure because there are large pedestrian areas through the old town, and several beautiful parks just around that center. There are various churches of different eras and styles, and a tremendous romantic organ in the Dom Cathedral, with a concert every day at noon !

I discovered interesting composers at the Sacred Music Festival (with high-quality choir, orchestra and soloists); and discovered many interesting painters at the Latvian National Museum of Arts.

So Riga has many advantages of a capital with rich cultural life, but seemingly without too many of its inconveniences : most buildings look fresh and unaffected by pollution, I didn't see any traffic jams, prices are reasonable, etc. Maybe that's the positive aspect of Soviet occupation, that the city was preserved so many years from wild capitalism...

In short, not only was YAPC a very nice conference, it was also the totally unexpected pleasure of a very interesting touristical exploration (albeit too short).

Thanks to the YAPC organizers for having brought us there!

about MsOffice::Word::HTML::Writer

Yesterday I gave a lightning talk on MsOffice::Word::HTML::Writer, a module to produce documents for MsWord from HTML content. To anybody interested, here is some more info :

• the module only needs Perl, and therefore can run on a server; it doesn't need MsWord to be installed (actually, that's the whole purpose of that module).
  


• it was written for the needs of Geneva courts of law, where we needed to generate thousands of documents every day, from hundreds of models, with libraries of reusable content parts, with fusion of complex datastructures ... but the resulting docs must be editable in MsWord.
  

Other technologies considered, but rejected, were :

• remote control of an MsWord instance, through a OLE connection. That's what most other courts do, but it only works on a local workstation : you could hardly do the same on a server, first because you would need to install MsOffice, and second because this architecture is not reliable enough : the MsWord instance is a bottleneck, it might break, or it might suddenly put a popup to ask the user for something ... except there is nobody to answer if running on a server. So this approach can be considered if you have a heavy application, deployed on everybody's PC; but not for a Web application.
  


• generating RTF, using some templating tool : this works on a server, but authoring models can be tricky (esp. it is not obvious to factorize reusable parts).
  


• generating XML, either in ODF (open format used by OpenOffice), or in OOXML (Microsoft proprietary format) : here the main problem is authoring, because both XML specs are huge, so you really need specialists to produce your models
  


• generating ODF from http://search.cpan.org/dist/OpenOffice-OODoc/ : well, ODF can be read by MsWord, but many features are missing. Besides, OODoc uses a programming approach, not a templating approach, so it's harder to delegate authoring of models to people who are not familiar with Perl.

MsOffice::Word::HTML::Writer works by assembling HTML content (the main document, the headers/footers, other resources like images or CSS stylesheets), and then packaging the whole thing as a single MIME/multipart file. Model authors just need to know HTML, so it's easy to build an authoring team; and if you have a good templating framework, it's also easy to build a library of reusable content parts.