Adding apropos to repl-utils

[Michel Salim]

Hello,

I proposed adding an 'apropos' function a few months ago -- I think it
was before Clojure Dev was set up:

http://groups.google.com/group/clojure/browse_thread/thread/66190355c83a29f0/64dbce51f3c9cdbf?lnk=gst&q=apropos#64dbce51f3c9cdbf

I've created a ticket for it in Assembla and submitted a patch
(modifying repl_utils)

http://www.assembla.com/spaces/clojure-contrib/tickets/38-repl_utils-addition--apropos

Do let me know if there's any changes necessary.

Thanks,

--
Michel S.

[Chouser]

On Fri, Oct 23, 2009 at 5:08 AM, Michel Salim
<michael....@gmail.com> wrote:
>
> I proposed adding an 'apropos' function a few months ago -- I think it
> was before Clojure Dev was set up:
>
> http://groups.google.com/group/clojure/browse_thread/thread/66190355c83a29f0/64dbce51f3c9cdbf?lnk=gst&q=apropos#64dbce51f3c9cdbf

When would this be preferred over 'find-doc'?

--Chouser

[Michel Salim]

On Oct 23, 9:46 am, Chouser <chou...@gmail.com> wrote:
> On Fri, Oct 23, 2009 at 5:08 AM, Michel Salim
>

> <michael.silva...@gmail.com> wrote:
>
> > I proposed adding an 'apropos' function a few months ago -- I think it
> > was before Clojure Dev was set up:
>

> >http://groups.google.com/group/clojure/browse_thread/thread/66190355c...

>
> When would this be preferred over 'find-doc'?

- find-doc only finds functions that have documentation strings;
apropos finds both functions and variables
- find-doc requires a search string; apropos first stringifies its
argument -- (str kw) -- so you can search using
numbers or symbols as well
- apropos returns a list, similar to (Chez) Scheme's apropos-list, so
its result can be used for further processing

If point #2 can be rolled back into find-doc, I'd be happy, of course,
but points #1 and #3 still stand, I think.

Thanks,

--
Michel S.

[Chouser]

On Fri, Oct 23, 2009 at 3:59 PM, Michel Salim
<michael....@gmail.com> wrote:
>
> On Oct 23, 9:46 am, Chouser <chou...@gmail.com> wrote:
>> On Fri, Oct 23, 2009 at 5:08 AM, Michel Salim
>>
>> <michael.silva...@gmail.com> wrote:
>>
>> > I proposed adding an 'apropos' function a few months ago -- I think it
>> > was before Clojure Dev was set up:
>>
>> >http://groups.google.com/group/clojure/browse_thread/thread/66190355c...
>>
>> When would this be preferred over 'find-doc'?
>
> - find-doc only finds functions that have documentation strings;
> apropos finds both functions and variables

find-doc searches both the name and docstring of all vars that
have docstrings, regardless if they hold functions or other
values. Is it that you want to include vars that have no
docstrings?

> - find-doc requires a search string; apropos first stringifies its
> argument -- (str kw) -- so you can search using
>  numbers or symbols as well

Since neither is a macro you'd still need to quote a symbol. It
would be slightly more frictionless if there were a macro
version.

> - apropos returns a list, similar to (Chez) Scheme's apropos-list, so
> its result can be used for further processing

There's a tension here between providing data that can be
processed further vs. providing pleasantly-formatted data at the
REPL. I had noticed similar tension in repl-utils/show, where
returning a vector of all methods would have made it almost
useless by itself, and yet it's not uncommon to want a list of
methods for further processing.

I wonder if it would be reasonble to handle this by providing
custom print methods for these things, so that they would
actually *be* a list (or map or vector or whatever), but when the
REPL prints them they'd be all nicely formatted.

Does anyone else think they'd use apropos?
--Chouser