* Dave Rolsky ([EMAIL PROTECTED]) [040126 23:58]: > 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.
> > 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. Ok... could be done: docs on different "experience" levels. Although, I haven't seen other large sets of documentation do that. It's easy to do when you have only 20 methods, but with 1000 it's much harder. For these things you need books. > Also, some methods are probably more important than others, but they're > all just there to be read. That's why there are also indexed, where methods are grouped on task. > 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. The question is: are you programming OO or imperative, or some intermediate thing. If you want to program OO, you group functionality in Objects and keep it there. Of course you can make short-cuts in object which have the other, but when you extend that too much, you get one blur of code. In this case, I think Mail::Internet is clean. Mail::Box offers a few other options: my $field = $msg->head->get('from'); my $field = $msg->get('from'); my @addrs = $msg->from; # already parsed > 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. Of course... documentation is never perfect. People complain if there is not enough, people complain if there is too much. Everyone has his/her own style. Not everyone has the same education, etc. That's why I invite everyone to write documentation for MailBox. Don't forget, it's a product of one person written in 2 years, so especially the docs need some aging. > The overview is mostly a description of the byzantine class relationships, > which is something I'd rather _not_ have to know. Then I think you have missed out the major part of the docs. > I haven't looked at the slides from the tutorial yet. Ah. (don't forget the papers which relate to them) > 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 => '...' ); This object is called: the Mail::Box::Manager. It takes care of all auto-detection and loading of the right classes, but also protects you from opening the same folder twice. Trying to put this folder factory code in a folder object itself is very clumpsy, although I have seen Perl modules do that before. Folder detection is a different job than managing a folder. That's the only place in the program where I spend one line extra, simply for OO reasons. my $mgr = Mail::Box::Manager->new; my $folder = $mgr->open(...); > foreach my $msg ( $folder->new_messages ) foreach my $msg ( $folder->messages('!seen') > { > # should be smart and give me everything but the main body > foreach my $att ( $msg->attachments ) Complicated case: what with nested multiparts and rfc822 encapsulated? Simplification of the situation is one way of making the API simpler, but cuts-out some users. foreach my $att ( $msg->parts('RECURSE') ) > { > ... > } > > # return the header as a nice simple string, no objects, no arrays, > # nothing fancy > my $to_line = $msg->header_string('to'); my $to_line = $msg->get('to'); > my $subject_line = $msg->header_string('subject'); my $subject_line = $msg->get('subject'); (probably you prefer to study('') which does field decoding as well. > # Again, just the body as a string. > my $body = $msg->body_string; my $body = $msg->body->string; Or use stringifation: print $msg->body; > if ( $msg->body->mime_type->is_html ) if($msg->body->mimeType eq 'text/html') Which has overloading to be case-insensive, provided by MIME::Types > { > ... > } > } > > 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. I agree... so just must be happy that it is all provided for already. MailBox only needs one line more, for cleaness sake. Examples, like above are in the tutorials. > 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? It's all internals... you shouldn't worry about it. And yes, I need it to get the best result. You have written large programs yourself. If you start off with a program which needs to implement your needs it is small. But than, your needs grow and it grows larger and larger. Then other people start using the module, and it grows and grows. That's how Mail::Internet became extended by MIME::Entity and many other packages. I have used them, but there were too many structural problems to handle nested multiparts and such. Mail::Box was designed to start with EVERYTHING which the RFCs specify, and ALL uses I know with e-mail. A very high level library. And that's quite a lot... And therefore suffers all the same problems as other large modules (like Tk) have: they are hard to understand when you start with them. I'm happy that the whole code is documented very well, that there are some examples and a few tutorials. There can always be more. -- MarkOv ------------------------------------------------------------------------ drs Mark A.C.J. Overmeer MARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
