From de25f555ec8f189908bc290d6fb011713c3c88ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?=
 <dominik.pantucek@trustica.cz>
Date: Fri, 14 Jun 2024 10:57:34 +0200
Subject: [PATCH] Split bindings module and add appropriate scribblings.

- scribblings for qi/list module
- scribble the new literals for matching in deforestation pass
- ensure for-label bindings in the generated documentation
- new bindings.rkt module
---
 qi-doc/scribblings/list-operations.scrbl      | 118 ++++++++++++++++++
 .../flow/core/compiler/deforest/bindings.rkt  |  35 ++++++
 qi-lib/list.rkt                               |   4 +-
 3 files changed, 155 insertions(+), 2 deletions(-)
 create mode 100644 qi-doc/scribblings/list-operations.scrbl
 create mode 100644 qi-lib/flow/core/compiler/deforest/bindings.rkt

diff --git a/qi-doc/scribblings/list-operations.scrbl b/qi-doc/scribblings/list-operations.scrbl
new file mode 100644
index 000000000..2b70c1181
--- /dev/null
+++ b/qi-doc/scribblings/list-operations.scrbl
@@ -0,0 +1,118 @@
+#lang scribble/doc
+@require[scribble/manual
+	 (for-label racket/list
+	 	    racket/base)]
+
+@title{List Operations}
+
+@defmodule[qi/list]
+
+This module defines bindings that can leverage stream fusion /
+deforestation optimization when found in succession within a
+flow. When not part of optimized flow, their behavior is identical to
+the bindings of the same name from @racketmodname[racket/base] and
+@racketmodname[racket/list].
+
+The bindings are categorized based on their intended usage inside the
+deforested pipeline.
+
+@section{Producers}
+
+@defproc*[(((range (end real?)) list?)
+           ((range (start real?) (end real?) (step real? 1)) list?))]{
+
+Deforestable version of @racket[range] from @racketmodname[racket/list].
+
+}
+
+@section{Transformers}
+
+@defproc[(filter (pred procedure?) (lst list?)) list?]{
+
+Deforestable version of @racket[filter] from @racketmodname[racket/base].
+
+}
+
+@defproc[(map (proc procedure?) (lst list?) ...+) list?]{
+
+Deforestable version of @racket[map] from @racketmodname[racket/base].
+
+}
+
+@defproc[(filter-map (proc procedure?) (lst list?) ...+) list?]{
+
+Deforestable version of @racket[filter-map] from @racketmodname[racket/list].
+
+}
+
+@defproc*[(((take (lst list?) (pos exact-nonnegative-integer?)) list?)
+           ((take (lst any/c) (pos exact-nonnegative-integer?)) list?))]{
+
+Deforestable version of @racket[take] from @racketmodname[racket/list].
+
+}
+
+@section{Consumers}
+
+@defproc[(foldl (proc procedure?) (init any/c) (lst list?) ...+) any/c]{
+
+Deforestable version of @racket[foldl] from @racketmodname[racket/base].
+
+}
+
+@defproc[(foldr (proc procedure?) (init any/c) (lst list?) ...+) any/c]{
+
+Deforestable version of @racket[foldr] from @racketmodname[racket/base].
+
+}
+
+@defproc[(car (p pair?)) any/c]{
+
+Deforestable version of @racket[car] from @racketmodname[racket/base].
+
+}
+
+@defproc[(cadr (v (cons/c any/c pair?))) any/c]{
+
+Deforestable version of @racket[cadr] from @racketmodname[racket/base].
+
+}
+
+@defproc[(caddr (v (cons/c any/c (cons/c any/c pair?)))) any/c]{
+
+Deforestable version of @racket[caddr] from @racketmodname[racket/base].
+
+}
+
+@defproc[(cadddr (v (cons/c any/c (cons/c any/c (cons/c any/c pair?))))) any/c]{
+
+Deforestable version of @racket[cadddr] from @racketmodname[racket/base].
+
+}
+
+@defproc*[(((list-ref (lst list?) (pos exact-nonnegative-integer?)) any/c)
+ 	   ((list-ref (lst pair?) (pos exact-nonnegative-integer?)) any/c))]{
+
+Deforestable version of @racket[list-ref] from @racketmodname[racket/base].
+
+}
+
+@defproc[(length (lst list?)) exact-nonnegative-integer?]{
+
+Deforestable version of @racket[length] from @racketmodname[racket/base].
+
+}
+
+@defproc[(empty? (v any/c)) boolean?]{
+
+Deforestable version of @racket[empty?] from @racketmodname[racket/list].
+
+}
+
+@defproc[(null? (v any/c)) boolean?]{
+
+Deforestable version of @racket[null?] from @racketmodname[racket/base].
+
+}
+
+
diff --git a/qi-lib/flow/core/compiler/deforest/bindings.rkt b/qi-lib/flow/core/compiler/deforest/bindings.rkt
new file mode 100644
index 000000000..22eccb9a7
--- /dev/null
+++ b/qi-lib/flow/core/compiler/deforest/bindings.rkt
@@ -0,0 +1,35 @@
+#lang racket/base
+
+(require (prefix-in r: racket/base)
+         (prefix-in r: racket/list)
+         syntax/parse/define
+         (for-syntax racket/syntax
+                     syntax/parse
+                     racket/base))
+
+(define-syntax-parser define-and-provide-deforestable-bindings
+  ((_ ids ...)
+   (with-syntax (((rids ...) (for/list ((s (attribute ids)))
+                               (format-id s "r:~a" s))))
+     #'(begin
+         (define ids rids) ...
+         (provide ids ...)))))
+
+(define-and-provide-deforestable-bindings
+  range
+  
+  filter
+  map
+  filter-map
+  take
+
+  foldr
+  foldl
+  car
+  cadr
+  caddr
+  cadddr
+  list-ref
+  length
+  empty?
+  null?)
diff --git a/qi-lib/list.rkt b/qi-lib/list.rkt
index 2558d68ae..0e8ca781f 100644
--- a/qi-lib/list.rkt
+++ b/qi-lib/list.rkt
@@ -3,6 +3,6 @@
 ;; Upon instantiation of the module it define-and-register-pass for
 ;; deforestation
 (require "flow/core/compiler/0100-deforest.rkt"
-         "flow/core/compiler/deforest/binding.rkt")
+         "flow/core/compiler/deforest/bindings.rkt")
 
-(provide (all-from-out "flow/core/compiler/deforest/binding.rkt"))
+(provide (all-from-out "flow/core/compiler/deforest/bindings.rkt"))