aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--gtwiwtg.lisp72
1 files changed, 36 insertions, 36 deletions
diff --git a/gtwiwtg.lisp b/gtwiwtg.lisp
index bb377e1..d94b7fd 100644
--- a/gtwiwtg.lisp
+++ b/gtwiwtg.lisp
@@ -6,15 +6,15 @@
;; None of the following are meant to be called directly by users of the library.
(defgeneric next (gen)
- (:documentation "Returns the next value of this generator, if
- available. Unspecified behavior if the generator has been exhausted."))
+ (:documentation "Returns the next value of the generator GEN, if
+ available. Unspecified behavior if the GEN has been exhausted."))
(defgeneric has-next-p (gen)
- (:documentation "Returns true if next can be called on the generator"))
+ (:documentation "Returns true if next can be called on the generator GEN."))
(defgeneric stop (gen)
(:documentation "Explicitly stops the generator. Specialize :after
- methods to implement any clean-up that needs to be done when the
+ methods to implement any clean up that needs to be done when the
generator has been consumed."))
;;; Base Generator Class ;;;
@@ -30,7 +30,7 @@
:initform nil
:documentation "Indicates whether or not this generator has been
explicitly stopped. All consumers explicitly stop the generators
- the consume.")))
+ they consume.")))
(defmethod stop ((g generator!))
(setf (stopped-p g) t))
@@ -131,7 +131,7 @@
(defun range (&key (from 0) to (by 1) inclusive)
"Create a generator that produces a series of numbers between FROM
-and TO with step size of BY.
+and TO with a step size of BY.
When INCLUSIVE is non NIL, then TO will be produced by the generator
if it would be the last member of generate series.
@@ -154,8 +154,8 @@ E.g.
(0 3 6 9)
-If TO is NIL, then the generator produces an infinite sequence.
-
+If TO is NIL, then the generator produces an infinite series of
+values.
"
(let ((comparator (if (plusp by)
(if inclusive #'<= #'<)
@@ -172,7 +172,7 @@ If TO is NIL, then the generator produces an infinite sequence.
(defun seq (sequence &key (start 0))
"Turns a sequecne (a list, vector, string, etc) into a
-generator. The resulting generator will generate exactly the memebers
+generator. The resulting generator will generate exactly the members
of the sequence."
(assert (typep sequence 'sequence))
(if (consp sequence)
@@ -183,13 +183,13 @@ of the sequence."
:index (1- start))))
(defun from-thunk-until (thunk &key (until (constantly nil)) clean-up)
- "Creates a generator that produces a series of value by successively
+ "Creates a generator that produces a series of values by successively
calling (FUNCALL THUNK). The iterator stops whenever (FUNCALL UNTIL)
is non null.
-If a CLEAN-UP thunk is supplied, it will be run after consumption of
-the new generator has finished. I.e. when passing this form to a
-consumer such as FOR, FOLD, COLLECT, etc.
+If a CLEAN-UP thunk is supplied, it will be run after the consumption
+of the new generator has finished. (Consumers are forms like FOR,
+COLLECT, FOLD, and so on.)
By default, UNTIL is the function (CONSTANTLY NIL). I.e. it will
generate forever."
@@ -219,13 +219,13 @@ generator, see FROM-THUNK-UNTIL."
(defun from-recurrence (rec n-1 &rest n-m)
"Creates a generator from a recurrence relation.
-REC is a function of K arguments.
+REC is a function of M arguments.
The Nth value of the series generated by the new generator is the result of
-calling REC on the previoius K results.
+calling REC on the previoius M results.
N-1 and N-M are used to initialize the recurrence. (1+ (LENGTH N-M))
-should be K, the number of arguments acepted by REC.
+should be M, the number of arguments acepted by REC.
Example
@@ -244,8 +244,8 @@ Example
(defun repeater (&rest args)
- "Produces a generator that produces an infinite series consisting in
-the values passed as ARGS looped forever."
+ "Creates a generator that produces an infinite series consisting in
+the the values of ARGS looped forever."
(let ((state (copy-list args)))
(from-thunk
(lambda ()
@@ -264,13 +264,16 @@ the values passed as ARGS looped forever."
"Create a generator from a STREAM.
You must supply as STREAM-READER function that accepts the stream as
-its only argument and returns NIL if the stream has run out of input,
+its only argument and returns NIL when the stream has run out of data,
Non-NIL otherwise.
-A quirk is that the last value returned from this generator is NIL.
+The new generator will return NIL as its final generated value..
-Consumers of the new generator will ensure that the stream is properly
-closed..
+Consumers of the new generator (forms like FOR, FOLD, COLLECT, and so
+on) will ensure that the stream is properly closed - you don't need to
+worry. If, however, you create a stream-backed-generator but do not
+actually consume it, then the stream will not be properly closed.
+Always consume your generators by passing them to a consumer!
Here is an example:
@@ -287,13 +290,12 @@ Here is an example:
(defun file-lines (file)
- "Creates a generator that produces the lines of a file. The stream
-to the file is closed when the generator finishes.
-
-FILE is either a path to a file.
+ "Creates a generator that produces the lines of a file. See
+ FROM-INPUT-STREAM for more details about stream-backed-generators.
-Returns NIL on the last iteration.
+FILE is a path to a file.
+The last generated value of the returned generator will be NIL.
"
(from-input-stream (open file)
(lambda (stream) (read-line stream nil nil))))
@@ -302,9 +304,9 @@ Returns NIL on the last iteration.
"Creates a generator that produces the characters of a file. The
stream to the file is closed when the generator finishes.
-FILE is either a path to a file.
+FILE is a path to a file.
-Returns NIL on the last iteration.
+The last generated value of the returned generator will be NIL.
"
(from-input-stream (open file)
(lambda (stream) (read-char stream nil nil))))
@@ -313,9 +315,9 @@ Returns NIL on the last iteration.
"Creates a generator that produces the bytes of a file. The
stream to the file is closed when the generator finishes.
-FILE is either a path to a file.
+FILE is a path to a file.
-Returns NIL on the last iteration.
+The last generated value of the returned generator will be NIL.
"
(from-input-stream (open file :element-type '(unsigned-byte 8))
(lambda (stream) (read-byte stream nil nil))))
@@ -358,12 +360,11 @@ Returns NIL on the last iteration.
(defun map! (map-fn gen &rest gens)
"Maps a function over a number of generators, returning a generator
that produces values that result from calling MAP-FN on those
-generators' elements, in sequence.
+generators' values, in sequence.
The resulting generator will stop producing values as soon as any one
of the source generators runs out of arguments to pass to
-MAP-FN. I.e. The mapped generator is as long as the shortest argument
-generators.
+MAP-FN. I.e. The new generator is as long as the shortest argument.
Error Conditions:
- If any of the generators compare EQL an error will be signalled
@@ -382,8 +383,7 @@ Error Conditions:
(dolist (g all-gens) (stop g))))))
(defun filter! (pred gen)
- "Produces a generator that filters out members of GEN that are NIL
-when applied to PRED.
+ "Creats a generator that generates the values of GEN for which PRED is non null.
Error Condition:
- If GEN has been used elsewhere, an error will be signalled.