Robert Feldt wrote:

> Since I haven't checked it out yet its hard to be specific, but I can give
> you the goal I *strive* for when doing a wrap or extension (collectively
> called a 'gem' below) for Ruby (BUT your milage may vary):
> 
>  SimpleAndNaturalDesign
>   Get the design as simple, natural and Ruby-esque as possible (in
>   that order). The gem should embody the best human knowledge on the
>   subject and package it so that it can be used with as little additional
>   knowledge as possible. Users should, ideally, be able to guess the
>   interface without reading docs.
> 
> For me, this is what sets Ruby apart from the other languages out
> there. IMHO, Matz has been amazingly successful in this regard.

I totally agree, although I'm straying from the original topic.  This is 
why I'm disappointed with most of the extant GUIs for Ruby.  Almost all of 
them are clones of the underlying GUI API, in Ruby; that is, they mirror 
the underlying API, not the Ruby philosophy.

This is what I realized when I was doing the port of the Electric XML Java 
API to Ruby: when doing a port or a wrap, you can either make it easy to 
port applications to Ruby, or easy to write new applications in Ruby.  I 
believe that the best way is to accommodate the Ruby users; otherwise, 
you're just perpetuating a bad API.  Caveat: it may be bad because of 
limitations of the original programming language, not because of any fault 
of the API programmers.  The Electric XML API, for example, was beautiful 
for a Java API, but it would have made a poor Ruby API.

> I guess it all boils down to adhering to PoLS ("Principle of Least
> Surprise") and/or PlatonicUniverseTM ("Things working as they should/would
> in an ideal (parallel) universe").

I'd heard of the first, but not the second.  What is the source?

> In line with above, it would be great if you pack the crypto-related stuff
> into a module Cryptography. They are important independently of SSL. I
> would put that module at top level (ie. not within OpenSSL or whatever you
> call your top-level module/namespace) since, when I need a cipher I don't
> want to think about whether it is in OpenSSL or not. But I guess
> OpenSSL::Cryptography might be ok as not to clash with other potential
> crypto libs.

There are a limited number of basic functions you can perform using 
cryptography: key generation, block d/encrypting, block 
signing/verification, and stream d/encrypting.  I'd suggest you look first 
at how you'd ideally USE the API (KISS and POLS) if you were a consumer of 
your API, write out stubs, then fill them in with the SSL stuff.  And, 
please, avoid the pitfall, common in Java APIs, of obscuring the starting 
point to support the plug-in model.  One thing I hate about Java APIs is 
having to get a base class of something through some obtuse factory.  I 
want to be able to say:

   crypt = Blowfish.new

not

   crypt = Crypto.lookup( "Blowfish" ).new_instance

Some libraries for Java are even worse than this.

> I'd like ruby-style, ie. attr_accessor, because its simpler and more
> natural.

Ditto.  Double ditto.  One of my pet loves of Ruby is the fact that it 
blurs the line between an attribute/instance variable and a method.  This 
is a great strength which should, IMO, be taken advantage of.

--- SER