On Mon, 26 Jan 2004, Mark Overmeer wrote: > > >- Not so great API. The API isn't so bad that I'd call it awful, but it's > > > inelegant and bulky, and definitely doesn't make simple things simple. > > Then please read the tutorial. It shows how simple things can be done. > > The main user interface is much like Mail::Internet and MIME::Entity provide: > (see one of my papers for a more detailed comparison) > > use Mail::Message; > > my $msg = Mail::Message->build > ( From => 'me', To => 'you', Cc => [EMAIL PROTECTED] > , data => [EMAIL PROTECTED], file => 'attach.html' > ); > > $msg->send(via => 'sendmail'); > > That's not hard to construct and send a fully RFC compliant multipart > message. Please start reading the introduction, if the whole is too hard > to understand at once... And certainly when you write a paper about the > subject.
It wasn't construction I found difficult. I've written an app that uses Mail::Box to read folders and insert messages into a database. I thought I had to read way too much just to figure out how to do simple things like get the body of an attachment, etc. > > >- This API problems are compounded by the docs, which are too > > > nitty-gritty, and basically treat every method and class as equally > > > important. Since there so many methods and classes, this makes it > > > really hard to find the bit you need. > > Depends what you have read. POD is not sufficient for such a large module. > Did you take a look http://perl.overmeer.net/mailbox/html/ ? Yes, but it _still_ by default shows me _every_ module and _every_ method. I really shouldn't have to care much about the delayed/complete/fast modules, etc. That's just implementation details. Also, some methods are probably more important than others, but they're all just there to be read. The other thing I don't like is that I usually have to read many modules worth of docs to figure out what I want. I think Simon nails this when he talks about how Mail::Internet forces users to call something like "$msg->head->get", etc. Mail::Box has the same problem. If I start by looking at the Mail::Message docs, I sometimes have to follow a bit of a twisty path through Mail::Header::* or Mail::Body::* to find what I want. Like I said, I think it doesn't do enough to make simple things simple. > Have a look at the website, it's all there. > http://perl.overmeer.net/mailbox/ The overview is mostly a description of the byzantine class relationships, which is something I'd rather _not_ have to know. This is a problem that occurs throughout the docs. I get way too much info on how things are implemented, and not enough abstraction. I haven't looked at the slides from the tutorial yet. > I am open for suggestions, and have even a mailinglist for that. Show > me some things you want to code (and how simple it should be), and I will > show you the elegance of MailBox's interface. I've _used_ Mail::Box, as I said. Here's a quick example of something that'd be nice: # figures out what type this is my $folder = Mail::Box::Folder->new( path => '...' ); foreach my $msg ( $folder->new_messages ) { # should be smart and give me everything but the main body foreach my $att ( $msg->attachments ) { ... } # return the header as a nice simple string, no objects, no arrays, # nothing fancy my $to_line = $msg->header_string('to'); my $subject_line = $msg->header_string('subject'); # Again, just the body as a string. my $body = $msg->body_string; if ( $msg->body->mime_type->is_html ) { ... } } See, the above requires very little knowledge of internals, and makes simple things such as getting headers, getting the body, looping through attachments, and so on easy. AFAIK, none of those things can be done with Mail::Box as easily as I show above. BTW, all of those operations are things I do in the code I wrote which uses Mail::Box. But the actual code is signficantly more complex. > But I'm really fed-up by this FUD which Simon spreads. It's unjustified, > coming from ignorance and envy.. I doubt it comes from ignorance or envy. However, as usual, Simon's manner is far more irritating than it needs to be, and I think you're justified in being angry at him. Nonetheless, I think his points about API design are correct. Here's the key phrase in his article, IMO: This is quite a shame, because mail handling as an abstract concept is very simple indeed. Nine times out of ten, you want to look at a piece of mail, get or set some of its headers, and look at its body. I also tend to agree with him that Mail::Box is a bit over-engineered in the OO department. Do you _really_ need _eleven_ classes for Mail::Message::Field, which in turn are presumably used by the _nine_ Mail::Message::Head classes? And even if you really do need them, is this something that the end user needs to be exposed to? -dave /*======================= House Absolute Consulting www.houseabsolute.com =======================*/
