and-map and or-map not documented in the manual

and-map and or-map not documented in the manual

[Gregory Marton]

Hi Folks,

A colleague just noticed that and-map and or-map, defined in boot-9.scm 
with some helpful comments above them, are not actually documented in the 
Guile Manual.  How might I go about adding them?

Many thanks,
Grem

-- 
------ __@   Gregory A. Marton                http://csail.mit.edu/~gremio/
--- _`\<,_                                                                .
-- (*)/ (*)                Abstinence is fine in moderation.
~~~~~~~~~~~~~~~~-~~~~~~~~_~~~_~~~~~v~~~~^^^^~~~~~--~~~~~~~~~~~~~~~++~~~~~~~

Re: and-map and or-map not documented in the manual

[Andy Wingo]

Hey Gregory,

On Wed 08 Oct 2008 18:19, Gregory Marton <gremio@csail.mit.edu> writes:

> Hi Folks,
>
> A colleague just noticed that and-map and or-map, defined in boot-9.scm
> with some helpful comments above them, are not actually documented in
> the Guile Manual.  How might I go about adding them?

Good question. The thing is, they are the same as SRFI-1's `every' and
`any', which have a longer heritage; Common Lisp appears to call `any'
`some'.

I think the SRFI names are clearer[1], so you should use them. We have a
problem that we provide less general implementations[2] under strange
names[3].

So ideally instead of documenting them, if you're with me, we should
deprecate them, replacing them with their srfi-1 counterparts.

What do you think?

Andy

1. `and-map' implies that you can map syntax, which you cannot.
2. `and-map' doesn't handle multiple lists as `map' and `every' do.
3. I think only Chicken has and-map, and calls it `andmap'.
-- 
http://wingolog.org/

Re: and-map and or-map not documented in the manual

[Ludovic Courtès]

Hi,

Andy Wingo <wingo@pobox.com> writes:

> So ideally instead of documenting them, if you're with me, we should
> deprecate them, replacing them with their srfi-1 counterparts.

I'm with you, but I think the status quo is safer, so that code from the
late 90's can run forever with Guile (hmm, how convincing is that?).

Thanks,
Ludo'.

Re: and-map and or-map not documented in the manual

[Gregory Marton]

From a user's perspective, reading code containing these functions, it can 
be confusing that they're undocumented and not defined in the user portion 
of the code.  Either deprecating them or documenting them with the caveats 
mentioned would be better than the status quo.

I would prefer to document them, because it's less work, and because the 
pointer into srfi-1 would help new users find other tools they might need.
Can I be helpful in making that happen?

Thanks,
Grem

> Hi,
>
> Andy Wingo <wingo@pobox.com> writes:
>
>> So ideally instead of documenting them, if you're with me, we should
>> deprecate them, replacing them with their srfi-1 counterparts.
>
> I'm with you, but I think the status quo is safer, so that code from the
> late 90's can run forever with Guile (hmm, how convincing is that?).
>
> Thanks,
> Ludo'.
>
>
>
>

-- 
------ __@   Gregory A. Marton                http://csail.mit.edu/~gremio/
--- _`\<,_                                                                .
-- (*)/ (*)     Confidence is the feeling you have until you understand.
~~~~~~~~~~~~~~~~-~~~~~~~~_~~~_~~~~~v~~~~^^^^~~~~~--~~~~~~~~~~~~~~~++~~~~~~~

Re: and-map and or-map not documented in the manual

[Sebastian Tennant]

Quoth ludo@gnu.org (Ludovic Courtès):
> Andy Wingo <wingo@pobox.com> writes:
>
>> So ideally instead of documenting them, if you're with me, we should
>> deprecate them, replacing them with their srfi-1 counterparts.
>
> I'm with you, but I think the status quo is safer, so that code from the
> late 90's can run forever with Guile (hmm, how convincing is that?).

How about deprecating them in the documentation only.

Dare I say that if it exists, it should be documented, (if only to
direct the user elsewhere).

Something like this maybe:

  -- Scheme Procedure: and-map pred lst1 lst2 ... lstN

  Please see <info-xref to 'every'>.

  Note: The reason for having two procedures that do the same thing is
        primarily historical. 'and-map' only exists in Guile whereas
        'every' can be found in most (if not all) Scheme
        implementations.  It will not be removed (for the sake of
        backwards compatiblity) but there's no reason to use it unless
        you want your code to be non-portable.

Seb


 

Re: and-map and or-map not documented in the manual

[Andy Wingo]

Hi Gregory,

On Thu 09 Oct 2008 18:22, Gregory Marton <gremio@csail.mit.edu> writes:

> I would prefer to document them, because it's less work, and because the
> pointer into srfi-1 would help new users find other tools they might
> need.
> Can I be helpful in making that happen?

I apologize for hijacking your thread, it just reminded me of some
things I've been thinking about for a while. I think that documentation
would be great, as long as the docs suggest `every' for new code. A
patch to doc/ref/api-compound.texi in the "List Mapping" node would be
great.

That said, the fact that so many definitions are available in a normal
Guile session is a kind of problem -- it's useful but not very
orthogonal. On the other hand, as Ludovic mentioned, we don't want to
cause bitrot in old code, so we can't really change that interface.

I think that the proper solution to this is to finally allow Guile to
deal in other "languages", in the sense that mzscheme does. The default
language would be "guile", which corresponds to what we have now. We
could implement r6rs, which has a more orthogonal set of bindings. That
way we can e.g. have a session without all of the posix API visible from
the root module. It will be tricky but doable I think.

Cheers,

Andy
-- 
http://wingolog.org/