From ae16aa6dffb4c2b660a4aa0a8cd0ed7b96f8f48a Mon Sep 17 00:00:00 2001 From: Colin Okay Date: Fri, 10 Jul 2020 12:20:51 -0500 Subject: reorganize README for better thought flow --- README.md | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index a2eebbc..cc7bacb 100644 --- a/README.md +++ b/README.md @@ -273,24 +273,23 @@ consed during consumption. See the docstrings for both forms for more details. (Or, there's a reason those forms all end in `!`.) You must be cautious when incrementally building up generators. The -reason for caution is that generators cannot be "combined twice", but -you may be tempted to try doing just that. - -I.e.These generators are not functional objects. Combining them with -one other effectively "destroys" them as independent objects, by -marking them as unfit for use in other combining forms. - -[Aside: This was done for efficiency reasons, and I might make a -"purely functional" parallel universe for these generators in the -future.] - -The library tries to help you out by signalling an error whenever you -try to do something that would lead to _mangled memory_. Each -docstring provides details about when error conditions are signalled -for each combining form. Don't quote me on it, but I *think* that the +reason for caution is that generators cannot be "combined twice". If +you are storing intermediate generators in a `let` binding, for +example, you may be tempted to pass those bound variables into +generator combination functions more than once. If you do, an error +will be signalled. + +_The general rule_ is: if you pass a generator to more than one +combining function (those whose names end in `!`), or if you pass the +same generator to one such a function at two argument positions, then +an error will be raised and new the generator will not be built. + +Internally, the library keeps track of whether or not generators have +been combined with others. Don't quote me on it, but I *think* that the library will prevent you from making generators with surprising (i.e. erroneous) behavior. + Here is an example to show you the illegal behavior: ``` lisp @@ -304,14 +303,14 @@ Here is an example to show you the illegal behavior: ``` The gist is that we tried to zip a generator with itself. Such -behavior is not allowed. Generally speaking, if you pass a generator -to more than one combining form (all forms that end in a `!`), or if -you pass the same generator to such a form twice, then an error will -be raised and new the generator will not be built. +behavior is not allowed. An ongoing goal is to make those errors nicer to look at so that you can more easily pin-point where you goofed. +[Aside: This was done for efficiency reasons, and I might make a +"purely functional" parallel universe for these generators in the +future.] ### The Fundamental Consumer -- cgit v1.2.3