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

[Marius via "Bug reports for GUILE, GNU's Ubiquitous Extension Language" <bug-guile@gnu.org>]

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