Update docs for Qi 4 #146

countvajhula · 2024-01-05T11:22:38Z

Summary of Changes

WIP docs.

Public Domain Dedication

In contributing, I relinquish any copyright claims on my contribution and freely release it into the public domain in the simple hope that it will provide value.

(Why: The freely released, copyright-free work in this repository represents an investment in a better way of doing things called attribution-based economics. Attribution-based economics is based on the simple idea that we gain more by giving more, not by holding on to things that, truly, we could only create because we, in our turn, received from others. As it turns out, an economic system based on attribution -- where those who give more are more empowered -- is significantly more efficient than capitalism while also being stable and fair (unlike capitalism, on both counts), giving it transformative power to elevate the human condition and address the problems that face us today along with a host of others that have been intractable since the beginning. You can help make this a reality by releasing your work in the same way -- freely into the public domain in the simple hope of providing value. Learn more about attribution-based economics at drym.org, tell your friends, do your part.)

qi-doc/scribblings/interface.scrbl

qi-doc/scribblings/field-guide.scrbl

qi-doc/scribblings/forms.scrbl

qi-doc/scribblings/qi.scrbl

benknoble · 2024-01-12T13:57:13Z

qi-doc/scribblings/forms.scrbl

+
+@codeblock{(~> 5 (as v) (gen v))}
+
+... produces @racket[5].


Please use a real ellipsis character … (C-k ,. in Vim, or Alt-; on macOS). You could also repunctuate the sentence as

This example @codeblock{…} produces @racket[5].

Or use an examples form?

benknoble · 2024-01-12T13:57:49Z

qi-doc/scribblings/forms.scrbl

+
+In general, bindings are scoped to the @emph{outermost} threading form (as the first example above shows), and may be referenced downstream. We will use @racket[(gen v)] as an example of a flow referencing a binding, to illustrate variable scope.
+
+@codeblock{(~> 5 (as v) (gen v))}


Should this be (~> (5)?

These code samples are in Qi context rather than Racket context.

Perhaps that should be clearer? It reads like a common syntax error, and I worry about the possible confusion there.

(I think using flow context is also what makes using something like examples harder, so I'd encourage revising that decision even if it ends up dragging in "incidental" Racket stuff.)

benknoble · 2024-01-12T13:58:29Z

qi-doc/scribblings/forms.scrbl

+@codeblock{(if (~> ... (as v) ...) (gen v) (gen v))}
+
+Analogously, in a @racket[switch], variables bound in each condition bind the corresponding consequent flow.
+
+@codeblock{(switch [(~> ... (as v) ...) (gen v)]
+                   [(~> ... (as v) ...) (gen v)])}
+


Non-elided examples would probably be more helpful here.

benknoble · 2024-01-12T14:00:15Z

qi-doc/scribblings/field-guide.scrbl

@@ -29,6 +29,10 @@ Decompose your @tech{flow} into its smallest components, and name each so that t

 A journeyman of one's craft -- a woodworker, electrician, or a plumber, say -- always goes to work with a trusty toolbox that contains the tools of the trade, some perhaps even of their own design. An electrician, for instance, may have a voltage tester, a multimeter, and a continuity tester in her toolbox. Although these are "debugging" tools, they aren't just for identifying bugs -- by providing rapid feedback, they enable her to explore and find creative solutions quickly and reliably. It's the same with Qi. Learn to use the @seclink["Debugging"]{debugging tools}, and use them often.

+@subsection{Be Intentional About Effects}
+
+Qi encourages a style that avoids "accidental" effects. A flow should either be pure (that is, it should be free of "side effects" such as printing to the screen or writing to a file), or its entire purpose should be to fulfill a side effect. It is considered inadvisable to have a function with sane inputs and outputs (resembling a pure function) that also performs a side effect. It would be better to decouple the effect from the rest of your function (@seclink["Use_Small_Building_Blocks"]{splitting it into smaller functions}, as necessary) and perform the effect explicitly via the @racket[effect] form, or otherwise escape from Qi using something like @racket[esc] (note that @seclink["Identifiers"]{function identifiers} used in a flow context are implicitly @racket[esc]aped) in order to perform the effect. This will ensure that there are no surprises with regard to @seclink["Order_of_Effects"]{order of effects}.


Perhaps don't quote "side effects"?

A short example of what this paragraph says would be useful.

benknoble · 2024-01-12T14:01:04Z

qi-doc/scribblings/field-guide.scrbl

+
+Consider the Racket expression: @racket[(map sqr (filter odd? (list 1 2 3 4 5)))]. As this invokes @racket[odd?] on all of the elements of the input list, followed by @racket[sqr] on all of the elements of the intermediate list, if we imagine that @racket[odd?] and @racket[sqr] print their inputs as a side effect before producing their results, then executing this program would print the numbers in the sequence @racket[1,2,3,4,5,1,3,5].
+
+The equivalent Qi flow is @racket[(~> ((list 1 2 3 4 5)) (filter odd?) (map sqr))]. As this sequence is @seclink["Don_t_Stop_Me_Now"]{"deforested" by Qi's compiler} to avoid multiple passes over the data and the memory overhead of intermediate representations, it invokes the functions in sequence @emph{on each element} rather than @emph{on all of the elements of each list in turn}. The printed sequence with Qi would be @racket[1,1,2,3,3,4,5,5].


I don't think we should quote "deforested" either.

benknoble · 2024-01-12T14:01:57Z

qi-doc/scribblings/field-guide.scrbl

@@ -350,6 +354,18 @@ Worse still, even though this computation raises an error, we find that the orig

 So in general, use mutable values with caution. Such values can be useful as side effects, for instance to capture some idea of statefulness, perhaps keeping track of the number of times a @tech{flow} was invoked. But they should generally not be used as inputs to a flow, especially if they are to be mutated.

+@subsection{Order of Effects}
+
+ Qi flows may exhibit a different order of effects (in the functional programming sense) than equivalent Racket functions.


…unless those effects are marked with effect or esc, in which case the order is supposed to be guaranteed, right?

countvajhula changed the title ~~Update docs for qi4~~ Update docs for Qi 4 Jan 5, 2024

countvajhula had a problem deploying to test-env January 5, 2024 11:25 — with GitHub Actions Failure

countvajhula had a problem deploying to test-env January 5, 2024 11:38 — with GitHub Actions Failure

benknoble reviewed Jan 5, 2024

View reviewed changes

qi-doc/scribblings/interface.scrbl Outdated Show resolved Hide resolved

qi-doc/scribblings/field-guide.scrbl Show resolved Hide resolved

qi-doc/scribblings/forms.scrbl Show resolved Hide resolved

qi-doc/scribblings/qi.scrbl Outdated Show resolved Hide resolved

countvajhula mentioned this pull request Jan 5, 2024

Let's Write a Qi Compiler! #74

Merged

29 tasks

countvajhula had a problem deploying to test-env January 6, 2024 02:41 — with GitHub Actions Failure

countvajhula added 11 commits January 10, 2024 22:34

doc: update grammar for the flow macro

ff84ac4

update advice on currying and partial application quirks

5ac92d3

minor capitalization in a comment

3dbd5d3

basic doc for the as binding form

568d336

doc: counting flows

5118880

mention performance gains in some parts of the docs

cc35173

add a placeholder doc page for the compiler (and expander)

16ddc9a

document an error re: ambiguous binding

36e9896

fix tab indent

e4ddfe7

fix a typo

e52aeda

remove unused test dependency on syntax-spec

9b2e6a3

countvajhula force-pushed the update-docs-for-qi4 branch from 61d293c to 9b2e6a3 Compare January 11, 2024 08:33

countvajhula added 2 commits January 11, 2024 01:34

doc: avoid empty production of literal

009fa0e

doc: basic example of binding more than one value with as

30fdffe

countvajhula had a problem deploying to test-env January 11, 2024 08:38 — with GitHub Actions Failure

countvajhula added 2 commits January 11, 2024 13:17

doc: variable scoping rules

87758ad

doc: minor improvements

e425d93

countvajhula had a problem deploying to test-env January 11, 2024 20:23 — with GitHub Actions Failure

doc: try only-space-in to link qi form literals

3e4f7d9

countvajhula had a problem deploying to test-env January 12, 2024 03:15 — with GitHub Actions Failure

countvajhula added 2 commits January 12, 2024 03:33

remove draft "under the hood" doc

a97879a

doc: relating to deforestation and order of effects

f6e7e1e

countvajhula marked this pull request as ready for review January 12, 2024 10:36

countvajhula had a problem deploying to test-env January 12, 2024 10:39 — with GitHub Actions Failure

doc: fix hierarchy

58ed04e

countvajhula had a problem deploying to test-env January 12, 2024 10:50 — with GitHub Actions Failure

countvajhula requested a review from benknoble January 12, 2024 11:00

benknoble reviewed Jan 12, 2024

View reviewed changes

countvajhula merged commit 64976db into drym-org:lets-write-a-qi-compiler Jan 12, 2024
5 of 6 checks passed

countvajhula mentioned this pull request Jan 15, 2024

Docs arrears #152

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for Qi 4 #146

Update docs for Qi 4 #146

countvajhula commented Jan 5, 2024

benknoble Jan 12, 2024

benknoble Jan 12, 2024

countvajhula Jan 12, 2024

benknoble Jan 12, 2024

benknoble Jan 12, 2024

benknoble Jan 12, 2024

benknoble Jan 12, 2024

benknoble Jan 12, 2024

benknoble Jan 12, 2024


		In general, bindings are scoped to the @emph{outermost} threading form (as the first example above shows), and may be referenced downstream. We will use @racket[(gen v)] as an example of a flow referencing a binding, to illustrate variable scope.

		@codeblock{(~> 5 (as v) (gen v))}


		Consider the Racket expression: @racket[(map sqr (filter odd? (list 1 2 3 4 5)))]. As this invokes @racket[odd?] on all of the elements of the input list, followed by @racket[sqr] on all of the elements of the intermediate list, if we imagine that @racket[odd?] and @racket[sqr] print their inputs as a side effect before producing their results, then executing this program would print the numbers in the sequence @racket[1,2,3,4,5,1,3,5].

		The equivalent Qi flow is @racket[(~> ((list 1 2 3 4 5)) (filter odd?) (map sqr))]. As this sequence is @seclink["Don_t_Stop_Me_Now"]{"deforested" by Qi's compiler} to avoid multiple passes over the data and the memory overhead of intermediate representations, it invokes the functions in sequence @emph{on each element} rather than @emph{on all of the elements of each list in turn}. The printed sequence with Qi would be @racket[1,1,2,3,3,4,5,5].

Update docs for Qi 4 #146

Update docs for Qi 4 #146

Conversation

countvajhula commented Jan 5, 2024

Summary of Changes

Public Domain Dedication

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment