diff --git a/qi-doc/scribblings/forms.scrbl b/qi-doc/scribblings/forms.scrbl index 8de3b16b..9bb77b88 100644 --- a/qi-doc/scribblings/forms.scrbl +++ b/qi-doc/scribblings/forms.scrbl @@ -24,7 +24,7 @@ The syntax of a language is most economically and clearly expressed using a gram The symbol @racket[expr] is typically used in this sense to indicate a Racket nonterminal position in the syntax -- that is, a position that expects a Racket expression. Analogously, we use the identifier @deftech{@racket[floe]} (pronounced "flow-e," for "flow expression") to refer to the Qi nonterminal, i.e. a position expecting Qi syntax. -The full syntax of Qi ("Standard Qi") is given below. Note that Standard Qi expands to a @seclink["The_Qi_Core_Language"]{smaller core language} before being @seclink["It_s_Languages_All_the_Way_Down"]{compiled to Racket}. +The full surface syntax of Qi is given below. Note that this expands to a @seclink["The_Qi_Core_Language"]{smaller core language} before being @seclink["It_s_Languages_All_the_Way_Down"]{compiled to Racket}. It does not include the @seclink["List_Operations"]{list-oriented forms}, which may be added via @racket[(require qi/list)]. @racketgrammar*[ [floe @#,seclink["The_Qi_Core_Language"]{core-form} diff --git a/qi-doc/scribblings/list-operations.scrbl b/qi-doc/scribblings/list-operations.scrbl index 2b70c118..2119ae7c 100644 --- a/qi-doc/scribblings/list-operations.scrbl +++ b/qi-doc/scribblings/list-operations.scrbl @@ -1,20 +1,40 @@ #lang scribble/doc @require[scribble/manual - (for-label racket/list - racket/base)] + (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. +This module defines functional list operations analogous to those in +@racketmodname[racket/base] and @racketmodname[racket/list], except +that these forms support @tech{flows} in higher-order function +positions and leverage the @seclink["Don_t_Stop_Me_Now"]{stream fusion +/ deforestation} optimization to avoid constructing intermediate +representations along the way to computing the result. + +The forms in this module extend the syntax of the @seclink["The_Qi_Core_Language"]{core Qi language}. This extended syntax is given below: + +@racketgrammar*[ +[floe (map floe) + (filter floe) + (filter-map floe) + (foldl floe expr) + (foldr floe expr) + (range expr expr expr) + (take expr) + car + cadr + caddr + cadddr + (list-ref expr) + length + empty? + null?]] + +The operations are categorized based on their role in the deforested +pipeline. @section{Producers}