added to readme, documenting with-generator

1 files changed, 25 insertions, 0 deletions

diff --git a/README.md b/README.md
index da27d0b..c5616b1 100644
--- a/README.md
+++ b/README.md
@@ -574,6 +574,7 @@ the `gtwiwtg.anaphora` package.  Here's an example:
 ```
 
 
+
 ### Making New Generators 
 
 Generators are subclasses of `gtwiwtg::generator!` that have at least
@@ -626,6 +627,30 @@ one of the reasons you are not ment to call `next` manually.  The
 `for` consumer automatically checks that there is a next value before
 trying to get it.
 
+
+### The Naughty Consumer 
+
+Now that the mysteries that make generators go has been explained in
+the previous section, you may be tempted to manually call `next` and
+`has-next-p` on your generators. If you must do this, you should use
+the `with-generator` macro:
+
+```lisp 
+
+> (with-generator (gen (seq "a1b2c3"))
+     (when (gtwiwtg::has-next-p gen)
+       (princ (gtwiwtg::next gen))
+       (terpri)))
+a
+
+```
+
+The `with-generator` form will ensure that the generator is properly
+closed. Could be useful with generators backed by input streams that
+need a custom logic that is hard to build using the basic tools. I'm
+not sure if you ever *will* need it, but the library provides it just
+in case.
+
 ## The Permutations Example
 
 One final example to show you what you can do. Here is a function that