From: ara.t.howard@...
Date: 2006-02-10T05:25:35+09:00
Subject: Re: How to improve this kind of API?

On Fri, 10 Feb 2006, Berger, Daniel wrote:

>> -----Original Message-----
>> From: Lyle Johnson [mailto:lyle.johnson@gmail.com]
>> Sent: Thursday, February 09, 2006 12:43 PM
>> To: ruby-talk ML
>> Subject: How to improve this kind of API?
>>
>>
>> I'm looking to make an API change for some methods in FXRuby
>> and would appreciate some suggestions about how to improve
>> them. The pattern shows up in several places in the code, but
>> it always boils down to some widget attribute that can have a
>> combination of bit-flags. For example, the 4-way splitter
>> window can be configured to expand only its top-left pane:
>>
>> splitter1.expanded = TOP_LEFT
>>
>> or to expand both the top left and top right panes:
>>
>> splitter2.expanded = TOP_LEFT | TOP_RIGHT
>>
>> And to check whether, say, the BOTTOM_LEFT pane is expanded:
>>
>> (splitter3.expanded & BOTTOM_LEFT) != 0
>>
>> Now, what I'm thinking of doing is replacing the symbolic
>> constants with Ruby symbols, and doing something like this instead:
>>
>> splitter1.expand(:top_left)
>> splitter2.expand(:top_left, :top_right)
>>
>> and then having checks like:
>>
>> splitter3.expanded? :bottom_left
>>
>> I think that in order to "turn off" one of those bits, I'm
>> probably also going to need to add something like:
>>
>> splitter4.unexpand(:bottom_right)
>>
>> Now, the question is, is there some existing pattern in Ruby
>> that this reminds you of? In other words, what is the Ruby
>> Way to handle this kind of setting?
>>
>> Thanks in advance for your suggestions!
>>
>> Lyle
>
> FWIW, I think what you've posted here looks good, so long as I could use
> strings as well, e.g. splitter.expand("top_left").

indeed.  a symbols only api is evil - makes reading config info from
files/yaml a pain.

a config method is also quite nice

   splitter.configure {
     expand 'top_left'
     something 'foobar'
   }

which should also take a hash

   splitter.configured(
     'expand' => 'top_left',
     'something' => 'foobar'
   )

which makes

   splitter.configure(YAML::load(IO:;read('config.yml')))

a one liner.

if config.yml has

   ---
   expand : top_left
   something : foobar

in it.

regards.

-a

-- 
happiness is not something ready-made.  it comes from your own actions.
- h.h. the 14th dali lama