Merge pull request #188 from countvajhula/address-code-review

Address code review comments

qi-doc/scribblings/forms.scrbl

@@ -22,7 +22,9 @@ The syntax and semantics of the Qi language. Qi @tech{flows} may be described us
 
 The syntax of a language is most economically and clearly expressed using a grammar, in the form of "nonterminal" symbols along with production rules expressing the syntax that is entailed in positions marked by those symbols. We may thus take the single starting symbol in such a grammar to formally designate the entire syntax of the language.
 
-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 symbol @racket[expr] is typically used in this sense to indicate a Racket nonterminal position in the syntax, i.e., 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.
+
+@tech{floe} is not to be confused with @tech{flow}. The relationship between the two is one of syntax and semantics, that is, the meaning of a @tech{floe} is a @tech{flow}.
 
 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)].
 
@@ -96,9 +98,9 @@ The full surface syntax of Qi is given below. Note that this expands to a @secli
          box-literal
          prefab-literal
          (@#,racket[quote] value)
-         (quasiquote value)
-         (quote-syntax value)
-         (syntax value)]
+         (@#,racket[quasiquote] value)
+         (@#,racket[quote-syntax] value)
+         (@#,racket[syntax] value)]
 [expr a-racket-expression]
 [index exact-positive-integer?]
 [nat exact-nonnegative-integer?]

qi-doc/scribblings/list-operations.scrbl

@@ -14,14 +14,18 @@ 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:
+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)
+      (range expr expr)
       (range expr expr expr)
       (take expr)
       car

qi-doc/scribblings/principles.scrbl

@@ -19,11 +19,11 @@
 
 @section{What is a Flow?}
 
- A @deftech{flow} is either made up of flows, or is a native (e.g. Racket) @seclink["lambda" #:doc '(lib "scribblings/guide/guide.scrbl")]{function}. Flows may be composed using a number of combinators that could yield either linear or nonlinear composite flows.
+ A @deftech{flow} is either composed of flows, or is a native (e.g. Racket) @seclink["lambda" #:doc '(lib "scribblings/guide/guide.scrbl")]{function}. In the former case, the composite flow is made up of flows that are combined in @seclink["Qi_Forms"]{well-defined structural ways} specifying the role of each component flow.
 
  A flow in general accepts @code{m} inputs and yields @code{n} outputs, for arbitrary non-negative integers @code{m} and @code{n}. We say that such a flow is @code{m × n}.
 
- The semantics of a flow is function invocation -- simply invoke a flow with inputs (i.e. ordinary arguments) to obtain the outputs.
+ Flows are @seclink["Embedding_a_Hosted_Language"]{embedded} into the host language (e.g. Racket) using the @racket[☯] macro which evaluates to an ordinary function. To use the flow, simply invoke this function with inputs as ordinary arguments to obtain the outputs as ordinary return values.
 
  The Qi language allows you to describe and use flows in your code.
 
@@ -146,7 +146,7 @@ This architecture is achieved through the use of @seclink["top" #:indirect? #t #
 
 @section{The Qi Core Language}
 
-Qi flow expressions expand to a small core language which is then @seclink["It_s_Languages_All_the_Way_Down"]{optimized and compiled to Racket}. The core language specification is given below. This syntax is a sub-language of the @seclink["Syntax"]{full Qi language}.
+Qi flow expressions expand to a small core language which is then @seclink["It_s_Languages_All_the_Way_Down"]{optimized and compiled to Racket}. The core language specification is given below. This syntax is a subset of the @seclink["Syntax"]{full Qi language}.
 
 @racketgrammar*[
 [floe _

qi-lib/flow/core/compiler/1000-qi0.rkt

@@ -394,8 +394,8 @@ the DSL.
 
   (define (deforestable-clause-parser c)
     (syntax-parse c
-      [((~datum f) e) #'(qi0->racket e)]
-      [((~datum e) e) #'e]))
+      [((~datum floe) e) #'(qi0->racket e)]
+      [((~datum expr) e) #'e]))
 
   (define (deforestable-parser e)
     (syntax-parse e

qi-lib/flow/core/compiler/deforest/syntax.rkt

@@ -50,7 +50,7 @@
   #:attributes (blanket? fine? arg pre-arg post-arg)
   #:literal-sets (fs-literals)
   #:datum-literals (range)
-  (pattern (#%deforestable range _info ((~datum e) the-arg) ...)
+  (pattern (#%deforestable range _info ((~datum expr) the-arg) ...)
     #:attr arg #'(the-arg ...)
     #:attr pre-arg #f
     #:attr post-arg #f
@@ -79,28 +79,28 @@
   #:attributes (f)
   #:literal-sets (fs-literals)
   #:datum-literals (filter)
-  (pattern (#%deforestable filter _info ((~datum f) f-uncompiled))
+  (pattern (#%deforestable filter _info ((~datum floe) f-uncompiled))
     #:attr f (run-passes #'f-uncompiled)))
 
 (define-syntax-class fst-map
   #:attributes (f)
   #:literal-sets (fs-literals)
   #:datum-literals (map)
-  (pattern (#%deforestable map _info ((~datum f) f-uncompiled))
+  (pattern (#%deforestable map _info ((~datum floe) f-uncompiled))
     #:attr f (run-passes #'f-uncompiled)))
 
 (define-syntax-class fst-filter-map
   #:attributes (f)
   #:literal-sets (fs-literals)
   #:datum-literals (filter-map)
-  (pattern (#%deforestable filter-map _info ((~datum f) f-uncompiled))
+  (pattern (#%deforestable filter-map _info ((~datum floe) f-uncompiled))
     #:attr f (run-passes #'f-uncompiled)))
 
 (define-syntax-class fst-take
   #:attributes (n)
   #:literal-sets (fs-literals)
   #:datum-literals (take)
-  (pattern (#%deforestable take _info ((~datum e) n))))
+  (pattern (#%deforestable take _info ((~datum expr) n))))
 
 (define-syntax-class fst-syntax0
   (pattern (~or _:fst-filter
@@ -127,8 +127,8 @@
   (pattern (#%deforestable
             foldr
             _info
-            ((~datum f) op-uncompiled)
-            ((~datum e) init))
+            ((~datum floe) op-uncompiled)
+            ((~datum expr) init))
     #:attr op (run-passes #'op-uncompiled)))
 
 (define-syntax-class fsc-foldl
@@ -138,8 +138,8 @@
   (pattern (#%deforestable
             foldl
             _info
-            ((~datum f) op-uncompiled)
-            ((~datum e) init))
+            ((~datum floe) op-uncompiled)
+            ((~datum expr) init))
     #:attr op (run-passes #'op-uncompiled)))
 
 (define-syntax-class cad*r-datum
@@ -155,7 +155,7 @@
   #:literal-sets (fs-literals)
   #:datum-literals (list-ref)
   ;; TODO: need #%host-expression wrapping idx?
-  (pattern (#%deforestable list-ref _info ((~datum e) idx))
+  (pattern (#%deforestable list-ref _info ((~datum expr) idx))
     #:attr pos #'idx
     #:attr name #'list-ref)
   ;; TODO: bring wrapping #%deforestable out here?

qi-lib/flow/extended/expander.rkt

@@ -245,8 +245,8 @@ core language's use of #%app, etc.).
         #'(esc spaced-f)))
 
   (nonterminal deforestable-clause
-    ((~datum f) e:closed-floe)
-    ((~datum e) g:racket-expr))
+    ((~datum floe) e:closed-floe)
+    ((~datum expr) g:racket-expr))
 
   (nonterminal arg-stx
     (~datum _)

qi-lib/list.rkt

@@ -16,27 +16,27 @@
          (prefix-in r: racket/base)
          (prefix-in r: racket/list))
 
-(define-deforestable (map [f f])
+(define-deforestable (map [floe f])
   #'(lambda (vs)  ; single list arg
       (r:map f vs)))
 
-(define-deforestable (filter [f f])
+(define-deforestable (filter [floe f])
   #'(λ (vs)
       (r:filter f vs)))
 
-(define-deforestable (filter-map [f f])
+(define-deforestable (filter-map [floe f])
   #'(λ (vs)
       (r:filter-map f vs)))
 
-(define-deforestable (foldl [f f] [e init])
+(define-deforestable (foldl [floe f] [expr init])
   #'(λ (vs)
       (r:foldl f init vs)))
 
-(define-deforestable (foldr [f f] [e init])
+(define-deforestable (foldr [floe f] [expr init])
   #'(λ (vs)
       (r:foldr f init vs)))
 
-(define-deforestable (range [e low] [e high] [e step])
+(define-deforestable (range [expr low] [expr high] [expr step])
   #'(λ ()
       (r:range low high step)))
 
@@ -58,7 +58,7 @@
           "(range arg ...)"
           "range expects at least one argument")])
 
-(define-deforestable (take [e n])
+(define-deforestable (take [expr n])
   #'(λ (vs)
       (r:take vs n)))
 
@@ -74,7 +74,7 @@
 (define-deforestable cadddr
   #'r:cadddr)
 
-(define-deforestable (list-ref [e n])
+(define-deforestable (list-ref [expr n])
   #'(λ (vs)
       (r:list-ref vs n)))
 

qi-lib/macro.rkt

@@ -141,7 +141,7 @@
 (define-syntax define-deforestable
   (syntax-parser
     [(_ (name spec ...+) codegen)
-     #:with ([typ arg] ...) #'(spec ...)
+     #:with ([_typ arg] ...) #'(spec ...)
      #:with codegen-f #'(lambda (arg ...)
                           ;; var bindings vs pattern bindings
                           ;; arg are syntax objects but we can't

qi-test/tests/expander.rkt

@@ -105,11 +105,11 @@
                              (#%host-expression 1)
                              __))))
     (test-expand "#%deforestable"
-                 #'(#%deforestable name info (f 0) (e 0))
+                 #'(#%deforestable name info (floe 0) (expr 0))
                  #'(#%deforestable name
                                    info
-                                   (f (gen (#%host-expression 0)))
-                                   (e (#%host-expression 0)))))
+                                   (floe (gen (#%host-expression 0)))
+                                   (expr (#%host-expression 0)))))
    (test-suite
     "utils"
     ;; this is just temporary until we properly track source expressions through