Skip to content

Commit

Permalink
Use of left-threading for list operations in docs
Browse files Browse the repository at this point in the history
Favor left threading, and note a commonly-encountered error in this
connection.
  • Loading branch information
countvajhula committed Jan 6, 2025
1 parent ffc767e commit 4b1ba3f
Show file tree
Hide file tree
Showing 2 changed files with 4 additions and 2 deletions.
4 changes: 3 additions & 1 deletion qi-doc/scribblings/field-guide.scrbl
Original file line number Diff line number Diff line change
Expand Up @@ -298,7 +298,7 @@ Qi aims to produce good error messages that convey what the problem is and clear

@bold{Common example}: Attempting to use a Qi macro in one module without @racketlink[provide]{providing} it from the module where it is defined -- note that Qi macros must be provided as @racket[(provide (for-space qi mac))]. See @secref["Using_Macros" #:doc '(lib "qi/scribblings/qi.scrbl")] for more on this.

@subsubsection{Contract Violation}
@subsubsection{@racket[map]/@racket[filter] Contract Violation}

@codeblock{
; map: contract violation
Expand All @@ -308,6 +308,8 @@ Qi aims to produce good error messages that convey what the problem is and clear

@bold{Meaning}: The interpreter attempted to apply a function to arguments but found that an argument was not of the expected type.

@bold{Common example}: Using @racket[map] or @racket[filter] without first @racket[(require qi/list)]. The built-in Racket versions are @emph{functions} that expect the input list argument at a specific position (i.e., on the right), whereas the Qi versions are @emph{macros} that are invariant to threading direction and expect precisely one input -- the list itself.

@bold{Common example}: Using a nested flow (such as a @racket[tee] junction or an @racket[effect]) within a right-threading flow and assuming that the input arguments would be passed on the right. At the moment, Qi does not propagate the threading direction to nested clauses. You could either use a fresh right threading form or indicate the argument positions explicitly in the nested flow using an @seclink["Templates_and_Partial_Application"]{argument template}.

@subsubsection{Compose: Contract Violation}
Expand Down
2 changes: 1 addition & 1 deletion qi-doc/scribblings/qi.scrbl
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ An embeddable, general-purpose language to allow convenient framing of programmi
Tired of writing long functional pipelines with nested syntax like this?
@racketblock[(map _f (filter _g (vector->list _my-awesome-data)))]
Then Qi is for you!
@racketblock[(~>> (_my-awesome-data) vector->list (filter _g) (map _f))]
@racketblock[(~> (_my-awesome-data) vector->list (filter _g) (map _f))]
But wait, there's more: Qi isn't just a turbo-charged threading language. It
supports multiple values and a suite of other operators for describing
computations:
Expand Down

0 comments on commit 4b1ba3f

Please sign in to comment.