Re: [PATCHv2] Extensions for SRFI-171 (Transducers)

[Ludovic Courtès]

Hi Colin and all!

These patches look like a nice addition.

First, you have the option of assigning your copyright for this
contribution (and future Guile contributions if you wish) to the FSF, or
you can choose not to:

  https://lists.gnu.org/archive/html/guile-devel/2022-10/msg00008.html

Please take a look at the message above and let us know what you’d like
to do.  If you choose not to assign copyright, you’ll have to add
copyright lines for you (or whatever entity holds copyright on your
work) in the modified files.

Overall the changes LGTM; I have minor comments and suggestions:

Colin Woodbury <colin@fosskers.ca> skribis:

> From 96856b184a507886db2c5c20323983ae125a6bdb Mon Sep 17 00:00:00 2001
> From: Colin Woodbury <colin@fosskers.ca>
> Date: Mon, 19 Dec 2022 09:39:37 +0900
> Subject: [PATCH 1/4] srfi-171: add twindow and various reducers
>
> This adds a number of reduction primitives often seen in other languages
> to Guile's SRFI-171 extensions.
>
> Most critical may be `rfold`, which could be called the fundamental
> reducer, as it's likely that all other reducers could be defined in
> terms of it (though not all are). While `tfold` already exists in
> Guile's SRFI-171 extension as a transducer, folding is in essence a
> reduction. Also without a primative like `rlast` (also introduced here),
> the results of `tfold` are difficult to consume. This is avoided by
> providing `rfold` directly as a generalised means to collapse an entire
> transduction down into a single value (i.e. the whole point of
> reducers). `rfold` is also useful for the creation of ad-hoc reducers,
> as any 2-arg function can be passed to it to fold the stream of values.
>
> `rfirst`, `rlast`, and `rfind` are common idioms and so have been added.
>
> The equivalent of `rmax` and `rmin` are easy to write manually via
> `rfold`, but they have been provided here as a convenience in the same
> spirit as `rcons`.
>
> `rfor-each` also cannot be forgotten as a classic adaptation of its
> SRFI-1 cousin.
>
> Also added is `twindow`, handy for analysing groups of adjacent items.

[...]

> From 58e7ca2718a860ca2fb5692684d6d128a7c1ae75 Mon Sep 17 00:00:00 2001
> From: Colin Woodbury <colin@fosskers.ca>
> Date: Tue, 20 Dec 2022 09:41:51 +0900
> Subject: [PATCH 2/4] doc: add new SRFI-171 reducers to the manual
>
> ---
>  doc/ref/srfi-modules.texi | 96 +++++++++++++++++++++++++++++++++++++--

[...]

> From 7b7538c61799fa0fa0e2fa18efba98b7de7da1ca Mon Sep 17 00:00:00 2001
> From: Colin Woodbury <colin@fosskers.ca>
> Date: Wed, 21 Dec 2022 09:30:50 +0900
> Subject: [PATCH 3/4] srfi-171: add unit tests for new functions
>
> These tests mainly match the examples shown in the docs.
> ---
>  test-suite/tests/srfi-171.test | 66 ++++++++++++++++++++++++++++++----

We’d squash these three commits together to provide a single
self-contained commit with code and the corresponding tests and doc.

The convention in Guile is for commit logs to follow the ChangeLog style
(see ‘git log’ for examples).  If you’re not sure how to do that, I can
do it on your behalf as a welcome present.  ;-)

> From 87a74d106f11680c4924befb664d7ef685c16b06 Mon Sep 17 00:00:00 2001
> From: Colin Woodbury <colin@fosskers.ca>
> Date: Thu, 22 Dec 2022 20:32:33 +0900
> Subject: [PATCH 4/4] doc: added a guide for writing custom reducers
>
> The guide previously explained what reducers were, but not the specifics
> of how to write them yourself. This commits rectifies this.

Nice!

> +++ b/doc/ref/srfi-modules.texi
> @@ -5966,6 +5966,82 @@ Yield the maximum (or minimum) value of the 
> transduction, or the
>  @var{seed} value if there is none.
>  @end deffn
>  
> +@subheading Writing your own reducers
> +If you want to reduce some values via an ordinary function that you

Please capitalize section titles and leave a blank line below it (same
for the section that follows).

> +However, if you want more customized behaviour (such as early
> +termination and/or arbitrary manipulation of the input values) then
> +you're free to write a reducer manually. To do so, we need to write a

Normally we leave two spaces after end-of-sentence periods, to ease
navigation in Emacs and please Texinfo (info "(texinfo) Ending a
Sentence").

Could you send updated patches?

Thanks for your work!

Ludo’.