|Keep It Simple, Stupid|
Do you like the interface, and is it simple enough to not be limiting?
Yes, that's a really clean implementation of this pattern, and in nicely idiomatic Perl.
Do you think people will use it?
That's hard to tell -- as Conway notes, this approach is underappreciated, and modules that make it easier may or may not push it over the tipping point of widespread acceptance... But it'd be nice if they did!
Something just doesn't feel comfortable about ... clone()
Looking at the code, what it does is store() some data and give you back the flyweight index. Calling it store() also fits in with fetch(), delete, and each(), all standard names for hash-like operators.
Where should I beef up/trim down/improve the documentation?
At times it's not immediately clear whether "the flyweight object" in the documentation is referring to the central Flyweight hash or to the individual objects; it might help to call them "the storage object" and "the index objects" or something like that.
It's probably worth noting in the "How do I use it?" section that in order to obtain the privacy benefits, the flyweight storage object should be held in a file lexical variable rather than a package variable.
The only part I was unclear about was the subclassing strategy -- if I'm using a Class::Flyweight to store private data for MyBank::Tx, with various subclasses like MyBank::Tx::Deposit, MyBank::Tx::LoanPmt, and so forth, is there some way to "stack on" the new accessors the subclasses will want to declare?
FWIW, that's the concern that drove me to adopt a one-hash-per-accessor approach in Class::MakeMethods::Template::Flyweight. As you noted in your firstname.lastname@example.org posting, that module is still sketchy, and the data is not fully private. To be honest, I've basically been ignoring the encapulation angle, and using it more for the ability to add arbitrary data to existing objects, like reconnect attributes for a DBI handle, without messing around with the tied-hash internals...
Anyway, again -- nice module, and it's good to see more explicit discussion of software patterns and other highbrow engineering concepts in a Perl context.