What CPAN modules are "good reads"?

tlm has asked for the wisdom of the Perl Monks concerning the following question:

IMO, the Perl literature is relatively thin on matters of module/class design and organization. A typical response to this observation is to point to CPAN while saying the words "Use the Source, Luke!" Unfortunately, CPAN modules are often quite difficult to read. This may be because the module is badly written, or because it is doing some very cutting edge stuff that only the most advanced Perl programmers can follow. Or perhaps because it is too huge to be comprehensible by the uninitiated.

What CPAN modules stand out in your experience for their readability and "didactic value"?

the lowliest monk

Comment on What CPAN modules are "good reads"?

Replies are listed 'Best First'.
Re: What CPAN modules are "good reads"? by samtregar (Abbot) on Jun 13, 2005 at 18:49 UTC
I addressed this in chapter 7 of my book - Writing Perl Modules for CPAN. You can download it for free. Interestingly, the two modules mentioned above - DBI and CGI - are both on my list of great CPAN modules but I don't consider either to be "good reads" for learning about Perl module design. They both contain rather unusual abuses of Perl's OO system that shouldn't be replicated without due cause. -sam	[reply]
Re: What CPAN modules are "good reads"? by dbwiz (Curate) on Jun 13, 2005 at 18:18 UTC
DBI is my favorite. The book came from that documentation. Its docs include also a roadmap. For other monks' opinion, see Looking for Mr. Good Documentation!.	[reply]
Re^2: What CPAN modules are "good reads"? by stvn (Monsignor) on Jun 13, 2005 at 21:17 UTC
DBI is great, but it's source can be hard to follow at times unless you are willing to dive into the XS code, and DBI::PurePerl is not a complete DBI implementation and so somewhat hard to follow too. However, that said, if you can manage to get your head around DBI you will certainly learn a lot. -stvn	[reply]
Re: What CPAN modules are "good reads"? by tilly (Archbishop) on Jun 13, 2005 at 21:41 UTC
I personally liked LWP as an example of OO design. And, of course, anything by TheDamian walks that fine line between inspiration and madness. OK, I lie. Many of them don't walk. They stagger somewhere close, where "close" is measured in very large units. But still they are interesting reads.	[reply]
Re: What CPAN modules are "good reads"? by rinceWind (Monsignor) on Jun 13, 2005 at 23:39 UTC
I'm surprised that nobody has mentioned the Perl Advent Calendar. 2004 was its fifth year. -- Oh Lord, won’t you burn me a Knoppix CD ? My friends all rate Windows, I must disagree. Your powers of persuasion will set them all free, So oh Lord, won’t you burn me a Knoppix CD ? (Missquoting Janis Joplin)	[reply]
Re: What CPAN modules are "good reads"? by fauria (Deacon) on Jun 13, 2005 at 19:20 UTC
Some days ago, perrin addressed a bug in Business::OnlinePayment, you can read it at Business::OnlinePayment sub redefined warnings. I took a look at the code for that module, and i found it simple to read and understand the code. Maybe you find Acme modules also easy to understand, because some of them are really simple, but suitable for your needs. For example, Acme::Palindrome is only 30 lines long.	[reply]
Re^2: What CPAN modules are "good reads"? by chromatic (Archbishop) on Jun 13, 2005 at 23:15 UTC
I've always liked the idea that a good Acme module not only does something useless, but it also shows off an interesting use of Perl in a fairly clear way.	[reply]
Re^2: What CPAN modules are "good reads"? by polettix (Vicar) on Jun 14, 2005 at 09:55 UTC
Maybe the cleanest Acme module is Acme::Bleach :) Flavio (perl -e 'print(scalar(reverse("\nti.xittelop\@oivalf")))') Don't fool yourself.	[reply]
Re: What CPAN modules are "good reads"? by stvn (Monsignor) on Jun 13, 2005 at 21:31 UTC
I have found DBD::mysqlPP to be very cleanly written code, and a wonderful way to learn more about DBD's (I use it as reference everytime I get stuck with DBD::Mock). I was also reading the Catalyst sources recently and found them very interesting. I usually try to read modules that I myself use, because I find it much easier to map my own usages to the source code I am looking at . Lots of "oh, so that's how they did it" moments and the like. As for the module/package organization part of your question. I think this is partially a personal style choice, but in general good modular decomposition is good modular decompostion :) -stvn	[reply]
Re^2: What CPAN modules are "good reads"? by perrin (Chancellor) on Jun 13, 2005 at 22:34 UTC
Catalyst contains some code that I consider pretty questionable -- things like undocumented abuses of import(), assumptions about the internal structure of other people's classes, etc. It's not all bad, but I wouldn't call it "clean."	[reply]
Re^3: What CPAN modules are "good reads"? by Hansen (Friar) on Jun 14, 2005 at 00:41 UTC
undocumented abuses of import() The only place we use import() is when you declare which engine and plugins you want to use, but it is documented. assumptions about the internal structure of other people's classes We only make a assumption of your internal structure if you inherit from Catalyst::Base and don't overload the constructor, perfectly sensible IMO. etc It would be interesting to hear about the real cases, where we are unclean.	[reply]
Re^4: What CPAN modules are "good reads"? by perrin (Chancellor) on Jun 16, 2005 at 04:28 UTC
Re^5: What CPAN modules are "good reads"? by dragonchild (Archbishop) on Jun 16, 2005 at 12:59 UTC
Some notes below your chosen depth have not been shown here
Re^5: What CPAN modules are "good reads"? by Hansen (Friar) on Jun 21, 2005 at 09:09 UTC
Some notes below your chosen depth have not been shown here
Re^3: What CPAN modules are "good reads"? by sri (Vicar) on Jun 14, 2005 at 00:17 UTC
Feel free to discuss this on the Mailinglist. Isn't blind bashing under your level? This is everything, but not productive...	[reply]
Re^4: What CPAN modules are "good reads"? by perrin (Chancellor) on Jun 16, 2005 at 04:33 UTC
Re^4: What CPAN modules are "good reads"? by insaniac (Friar) on Jun 14, 2005 at 13:52 UTC
Re^5: What CPAN modules are "good reads"? by sri (Vicar) on Jun 14, 2005 at 16:22 UTC
Re^3: What CPAN modules are "good reads"? by astroboy (Chaplain) on Jun 15, 2005 at 01:39 UTC
I'm still waiting for a response to this. I'm all for reasoned debate, but you've made sweeping criticisms of Catalyst, without backing up your claims. No Open Source project is above criticism, but it should be measured and considered. Come on, show us some examples of "undocumented abuses of import(), assumptions about the internal structure of other people's classes." If you can't find any, then the developers don't deserve the slur on the project, and if you can then hopefully they'll work to make it better.	[reply]
Re^4: What CPAN modules are "good reads"? by perrin (Chancellor) on Jun 16, 2005 at 03:32 UTC
Re: What CPAN modules are "good reads"? by perrin (Chancellor) on Jun 13, 2005 at 22:41 UTC
Template Toolkit has a nice design and clean code. OpenInteract2 looked pretty good to me too, but I don't know it as well.	[reply]
Re: What CPAN modules are "good reads"? by SolidState (Scribe) on Jun 14, 2005 at 10:50 UTC
IO::All stands out in my opinion. It seperates All.pod from All.pm (which I have always felt is the right thing to do), the comments stand out and make sense, the coding style is kept clean and consistent (something sadly lacking in many otherwise good modules). I haven't looked at the code for Brian's other modules (such as Inline, Kwiki and YAML, to name a few), but I assume they are also excellent examples of Perl code, having been written by the same person.	[reply]
Re^2: What CPAN modules are "good reads"? by stvn (Monsignor) on Jun 14, 2005 at 13:10 UTC
I will agree that IO::All (with it's use of Spiffy) makes for some clean looking code. However, IO::All is just crammed with everything and the kitchen sink thrown into one module, and even a way to further extend it with plugins! Spiffy itself is somewhat questionable in my mind as well since it does so many different things in one module. But after seeing how quickly ingy can whip out new Spiffy based modules, I am less bothered by that fact (usefulness almost always outweighs overly-anal-elegance). Back to IO::All, I do have to say that it is very nice when you are writing quick scripts and tools. It takes the headache out of doing some very complex stuff when you just don't have the time to do it the "right" way (the "right" way being a subjective thing). But to use it for any serious sizable project IMO would be inadvisable. But of course, this does not mean it is not good code to read :), in fact I rather enjoyed reading it (and learned plenty about obscure IO techniques as well). I would also recommend a look at Spiffy too, it has some rather interesting code in it as well. -stvn	[reply]
Re: What CPAN modules are "good reads"? by ghenry (Vicar) on Jun 13, 2005 at 17:57 UTC
I have learnt a lot from CGI.pm Walking the road to enlightenment... I found a penguin and a camel on the way..... Fancy a yourname@perl.me.uk? Just ask!!!	[reply]
Re^2: What CPAN modules are "good reads"? by merlyn (Sage) on Jun 14, 2005 at 11:37 UTC
As in, "What not to do?" {grin} Let's see: The "lincoln loader" instead of SelfLoader: check Custom importer instead of Exporter: check Funky "is this a method or a subroutine" repeated everywhere: check Funky "args preceded by dash and/or args inside a hashref": check Odd mix of globals and/or `use` parameters and/or object instance vars to determine behavior: check Admittedly, some of this stuff was created before the core functionality was available. But there's some mighty scary code in there. In Lincoln's defense, this code is probably the second most frequently invoked module, after strict, and has had to deal with a lot of legacy issues. -- Randal L. Schwartz, Perl hacker Be sure to read my standard disclaimer if this is a reply.	[reply]
Re^2: What CPAN modules are "good reads"? by bart (Canon) on Jun 13, 2005 at 19:26 UTC
Better unlearn it fast!	[reply]
Re^3: What CPAN modules are "good reads"? by ghenry (Vicar) on Jun 13, 2005 at 19:45 UTC
Yes, it sounds as if I should. Walking the road to enlightenment... I found a penguin and a camel on the way..... Fancy a yourname@perl.me.uk? Just ask!!!	[reply]
Re^3: What CPAN modules are "good reads"? by SolidState (Scribe) on Jun 14, 2005 at 10:30 UTC
Err... why?	[reply]
Re^4: What CPAN modules are "good reads"? by bart (Canon) on Jun 14, 2005 at 10:59 UTC
Re: What CPAN modules are "good reads"? by donarb (Beadle) on Jun 14, 2005 at 03:09 UTC
I don't have a specific CPAN module in mind, but any module which contains a thorough test harness is a great read, because it shows how to use the module and all of its APIs. Sometimes the POD lags behind, but if there is a test for it, the test helps to explain what it does and how to call it.	[reply]
Re: What CPAN modules are "good reads"? by 5mi11er (Deacon) on Jun 14, 2005 at 23:01 UTC
I've only viewed the source of a few modules, but I've thought that the Date:: modules to be relatively short/easy to understand. However, I've not attempted to view any them using a "the way to code in perl" filter, so whether any of them are well written, I can't comment on. I think any module you use effectively a lot is something you can learn from, provided you keep a healthy "grain of salt" attitude toward any given incantation. Whether a given incantation is great or not usually depends on what kind of efficiency filter you happen to be viewing it through. -Scott	[reply]
Re^2: What CPAN modules are "good reads"? by perrin (Chancellor) on Jun 16, 2005 at 04:38 UTC
The DateTime modules are really nice. Good design, good docs, and what I've seen of the code looks nice too.	[reply]

Back to Seekers of Perl Wisdom