bug#72347: Mismatch between documentation and real implementation of list-index

[Marius]

Thank you for the quick response,

El 29 de julio de 2024 10:28:00 UTC, Tomas Volf <~@wolfsden.cz> escribió:
>Hello,
>
>On 2024-07-29 00:34:14 +0000, Marius via Bug reports for GUILE, GNU's 
>Ubiquitous Extension Language wrote:
>> Good evening,
>>
>> I don't know if this is actually a Guile bug or a documentation bug, but I'm 
>> currently learning Guile from the "Guile reference manual" and I've found a 
>> mismatch between what the documentation says and what "my" guile does. I use 
>> Guile 3.0.9.
>>
>> In my Guile instance (from what I can deduce), last-index is a procedure 
>> that returns the index of the first element of a list that matches with a 
>> s-expresion.
>>
>> For example:
>>
>> (list-index '(1 2 3) 3) -> 2
>> (list-index '(height width) 'width) -> 1
>>
>> But the documentation says otherwise 
>> (<https://www.gnu.org/software/guile//manual/guile.html#SRFI_002d1-Filtering-and-Partitioning>):
>>
>> list-index pred lst1 lst2 ...
>>
>> Returns the index of the first set of elements, one from each of lst1 lst2 
>> ..., which satisfies pred.
>
>This is documentation for SRFI-1, and that is not available by default (at 
>least
>not fully), you need to (use-modules) it.  See below.
>
>>
>>
>> If I try to run list-index examples (from the documentation) I get an error 
>> because it doesn't know how to deal with a procedure as the first argument.
>>
>>
>> I'm missing something? I understand that list-index it's defined in SRFI-1 
>> and maybe a Guile definition is shadowing the SRFI-1 definition. But where 
>> is the Guile documentation for this shadowing list-index? In the Guile 
>> Reference Manual list-index it's only described inside SRFI-1 module.
>
>It seems that Guile provides 2 different list-index procedures.  One defined in
>the ice-9/boot-9.scm, and one in the srfi-1 module.  By default the boot-9's 
>one
>is available.
>
>    $ guile -q
>    GNU Guile 3.0.9
>    Copyright (C) 1995-2023 Free Software Foundation, Inc.
>
>    Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
>    This program is free software, and you are welcome to redistribute it
>    under certain conditions; type `,show c' for details.
>
>    Enter `,help' for help.
>    scheme@(guile-user)> list-index
>    $1 = #<procedure list-index (l k)>
>    scheme@(guile-user)> ,use (srfi srfi-1)
>    scheme@(guile-user)> list-index
>    $2 = #<procedure list-index (pred clist1 . rest)>
>
>Notice that by importing srfi-1 the list-index changes to the documented one.
>
>You are right that the "default" list-index indeed does not seem to be
>documented.  It also uses `eq?' for comparisons and does not allow changing
>that.
>
>I hope this sheds some light on the problem.
>
>Tomas

Yes, that makes sense. But this arises another question. The Guile manual 
states that some SRFI procedures are native to Guile by default (I imagine that 
that means that they are defined in ice-9/boot.scm). This is explained in 
<https://www.gnu.org/software/guile/manual/guile.html#About-SRFI-Usage> 
(section 7.5.1 in the manual). All of this is in regards documentation:

In the manual there are procedures that are both explained in the their API 
reference section and in the SRFI section. When that is the case, it means that 
the guile default implementation (ice-9) differs from the SRFI (most of the 
time it's because of the order of arguments). But if the procedure it's ONLY 
present in the SRFI documentation part then it should mean that it's 
implemented following the SRFI standard only, no?

The problem is that it seems like there are some procedures (named as in SRFI) 
that are implemented by default in guile (via ice-9 module) but aren't 
documented in API reference section of the manual. Instead they are only 
documented in the SRFI section of the manual. This is very confusing for anyone 
using the Guile reference manual as a "reference manual" because you suddenly 
get procedures that do not follow the behavior that the manual is telling you 
that should follow.

Again from the manual it's understood that if a procedure from SRFI is defined 
in the default Guile (ice-9) then it's implemented following the SRFI standard 
(cite: "The second reason is that some features defined in SRFIs had been 
implemented in Guile before the developers started to add SRFI implementations 
as modules"). That's true unless in the API reference section of the manual the 
procedure is defined in another way.

Since list-index is only documented in SRFI section but the default list-index 
(ice-9) does not follow the SRFI convention then I still think this is a bug. A 
documentation bug. Adding list-index inside the API documentation (list 
section) would solve this. Then it would be clear that the default list-index 
implementation differs from the SRFI.
>
>--
>There are only two hard things in Computer Science:
>cache invalidation, naming things and off-by-one errors.


Thank you,
Marius