Richard Jones wrote:
> Good user interface design does *not* require you to read manuals to
> find out how to use it

I don't expect programming APIs to be as obvious as user interfaces.  If 
I can work out how to use an API without reading a tutorial or HOWTO, 
that's great, but if not, I don't see it as a flaw in the API.

There is a tradeoff between power and flexibility on the one hand, and 
obviousness and simplicity on the other.

> I deliberately chose to make
> the common case this simple because it's the common case and people
> shouldn't have to remember much to use it.

Java does that, too.  If your default encoding is UTF-8, and you want to 
read a UTF-8 file, you can write this instead:

BufferedReader in = new BufferedReader(new FileReader(filename));

If you don't need buffering, you can write:

FileReader in = new FileReader(filename);

and read characters one at a time or in blocks, instead of line-by-line.

I like the fact that the API makes a distinction between bytes and 
characters; I can deal with I/O as raw bytes, or I can use an optional 
layer that translates bytes into characters.  If I don't need that 
layer, I don't have to pay for the overhead.  Likewise, I can add 
buffering only if I need it.  Best of all, if

 > Here's how you read in and parse a CSV file using my OCaml
 > CSV library:
 >
 >   let csv = Csv.load csvfile in

This seems to take too much for granted.  How do I specify the encoding 
and the line endings?  Is all that part of the Csv library, meaning that 
the Csv library has yet another mechanism for handling encodings?  What 
if my file is encrypted or compressed?  How do I make Csv.load use my 
decryption or decompression function?  Do you see what I'm getting at?

This is why I'm pleading for a layered API, so that character encoding, 
buffering, compression, encryption, and any other optional processing 
can be handled by optional layers that everyone can use, whether they're 
dealing with network protocols or just reading files from a disk. 
Moreover, I'm arguing that there should be some stream abstraction that 
can be passed around to things like Csv.load, and that different 
implementations of this abstraction should be free to implement 
decoding, decompression, and so on.  Does that make sense to you?

Ben

-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners