[Xapian-devel] ruby bindings odds and ends

[Paul Legato]

Olly Betts wrote:
> In the Ruby bindings, set_X and get_X are renamed to remove the get/set,
> so MSet::get_matches_estimated() becomes a read-only property (if I have
> my terminology right) of the Ruby MSet class called matches_estimated.
> This matches how a Ruby programmer would expect a class to be designed.

Yup, that's right (though Ruby calls them 'attributes'.)

foo.some_property = "bar" # method signature is def some_property=(value)
print foo.some_property  # method signature is def some_property()

> 
> I was looking through the getters and setters list.  I wonder if a few
> entries shouldn't be there, (the comment says it was auto-generated, so
> I'm guessing it currently simply includes every method matching set_* or
> get_*).
> 

They could probably stand some tweaking. I auto-generated them exactly
as you guessed, by grepping the C++ header files for get_ and set_
method declarations.

> The ones I'm thinking of are those set_ methods which don't take exactly
> one parameter, and perhaps those get_ methods which take parameters.
> 
> For example, Enquire::set_sort_by_relevance doesn't take any parameters,
> while Enquire::set_sort_by_value takes two (the second is optional,
> but it allows you to reverse the sort order which is a common thing to
> want to do).  Neither of these methods is really a setter method in
> the usual sense.  They're just methods with names which happen to start
> "set_".

The Rubish way to do something like set_sort_by_relevance would be with
a method called sort_by_relevance!. Method names ending in ! signify a
method that modifies the internal state of an instantiated object
(versus just returning a result; e.g. Array#sort returns a sorted copy
of the array, whereas Array#sort! causes the array object to sort
itself.) Similarly, I can see something like sort_by_value!(param1,
param2), if that causes some general internal state of an Enquire object
to change rather than acting as a setter method for some specific
instance variable.

> I'm also wondering if we should avoid wrapping C++ methods which are
> deprecated (since there's no previous version of the Ruby bindings to
> remain compatible with and those methods will be removed at some point,
> possibly in 1.0 which should happen fairly soon).  This isn't a Ruby
> specific thought - I think it makes sense generally.

This sounds like a good idea. No need to get people used to using things
that are going to disappear :)


> 
> And lastly, for most languages, there's an extra Enquire method -
> get_matching_terms() which just returns the matching terms as a list or
> array or similar.  I'm not sure why this one case gets special treatment
> really - I think it's mostly just a historical oddity.
> 
> Anyway, this wasn't being renamed (because it's not in the C++ header
> I guess).  I added a rename, but then it collides with a hand-coded
> matching_terms in xapian.rb, so I've now disabled it for Ruby.  It
> seems rather superfluous given we wrap all iterators to produce an
> array anyway.

If we want to expose this method, we can always call it
matching_terms_list or something along those lines...

Best,
Paul


-- 

--------------------------------------------------
--    Paul Legato, Senior Software Engineer     --
---       Networked Knowledge Systems          ---
----   P.O. Box 20772 Tampa, FL. 33622-0772   ----
----- (813)594-0064 Voice  (813)594-0045 FAX -----
------           plegato at nks.net            ------
--------------------------------------------------


--------------------------------------------------
-----   This email bound by the following:   -----
---- http://www.nks.net/email_disclaimer.html ----
--------------------------------------------------