Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?"

My main objection to this module is that it's a catch-all for everything. If I do

my $foo = io('some/thing');
[download]

then, what is it? What do I expect it to be, a file, a directory? It can be either. It can even be something else entirely, I don't know.

Yet, later on, if it's a directory, I can do $foo->next, if it's a file, I can do $foo->slurp, but not vice versa.

This is the exact opposite of where strong typing wants to go: bugs aren't visible at compile time, it won't even complain at run time before you've already gone deep into the code: at the time of the next/slurp call.

I don't like this. If you want a dir, say so. If you want a file, idem ditto. The module shouldn't have to guess. Because the chances are, it guesses wrong.

No, I don't think one constructor io() for everything is a proper API.

Ideally, I'd like an io::dir() call to produce a directory thingy, and a io::file() call for a file. These look nice, but, as those a fully qualified names, thus you can't subclass them. io_dir() or io_file() don't look even half as nice.

Comment on Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" Select or Download Code

Replies are listed 'Best First'.
Re^2: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by Aristotle (Chancellor) on Mar 25, 2004 at 03:41 UTC
Exactly my thoughts. Thanks for putting into words and a simple example what I couldn't seem to, obvious as it may be in retrospect. Makeshifts last the longest.	[reply]
Re: Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by dragonchild (Archbishop) on Mar 25, 2004 at 04:03 UTC
What about IO::All, instead of being a facade, instead is a factory? ------ We are the carpenters and bricklayers of the Information Age. Then there are Damian modules.... sigh* ... that's not about being less-lazy -- that's about being on some really good drugs -- you know, there is no spoon.* - flyingmoose	[reply]
Re: Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by mvc (Scribe) on Mar 27, 2004 at 16:07 UTC
My main objection: `my $foo = io('some/thing');` Yes it would be better to trap such a mistake ASAP. Would this be OK? `my $foo = io(-filename => 'some/thing');` You could even add some kind of policy enforcement aspect that will trap all dubious instantiations on runtime. I am not worried about a developer calling `$foo->slurp` when the intention was to use `$foo` as a directory, for the same reason that I am not worried about it being used as a Person object. It is just a coincidence that file and directory features are in the same physical package. BTW: The Java class java.io.File is also a file or a directory, and it implements some methods that are directory specific, like `listFiles()`. So it is a similar situation, despite the static typing. Of course that is a poor example, and anybody with a brain would use a util lib, e.g. the apache commons. It is leaky abstraction, but it looks like a pretty cool one to me! The freedom from having to check return values is a justification for this by itself.	[reply] [d/l] [select]


Pathologically Eclectic Rubbish Lister
	PerlMonks