The com.clearly-useful.iterator-protocol Reference Manual
Table of Contents
The com.clearly-useful.iterator-protocol Reference Manual
This is the com.clearly-useful.iterator-protocol Reference Manual, version 0.1,
generated automatically by Declt version 3.0 "Montgomery Scott"
on Tue Dec 22 13:09:29 2020 GMT+0.
1 Introduction
#+TITLE: simple iterator protocol for common lisp
* com.clearly-useful.iterator-protocol
*Overview*:
This package provides a simple iterator protocol for common lisp
which integrates with the sequence protocol.
From the protocol docstring:
A simple iteration protocol for Common Lisp.
Unlike sequences, iterators are stateful, and are
not intended to be held onto or passed around. Their
use should be hidden by some other construct. If you
are explicitly creating and advancing an iterator,
chances are you are Doing It Wrong.
Iterators should be be treated as though they
have dynamic extent.
This package is intentionally minimal, and only provides
a protcol for handling stateful iterators & basic implementations
for built in types. This protocol e.g. consume an object representing
the lines of a file, or some strings in memory, without having to
special case anything. The actual implementation of such an object
is beyond the scope of this package.
* exported symbols:
** iterator
/protocol/
the iterator protocol, which has two methods:
=iterator-next!= and =iterator-finish!=
** iterator
/type/
the type of the iterator protocol
** iterator
/generic function/
a function to produce an iterator from an object.
this function acts as the identity function for
iterators, and provides a default implementation
for the built in types =vector= and =array=, as
well as any object implementing the =seq= protocol.
** iterator-p
/function/
the test function for the iterator protocol
** iterator-next!
/protocol method/
returns two values:
1. the value of the iterator or nil,
2. t or nil depending whether a value was found.
then advances the iterator.
** iterator-finish!
/protocol method/
performs 'clean up' operations specific
to the iterator. e.g. closing a file.
** do-iterator
/macro/
similar to dolist.
#+begin_src lisp
(do-iterator (x '(a b c) (list x x))
(print x))
#+end_src
will call iterator on '(a b c),
bind x to subsequent values of
iterator-next!, finally call
iterator-finish! and return the value
of (list x x), i.e.
print a, b, and c, then return '(c c)
2 Systems
The main system appears first, followed by any subsystem dependency.
2.1 com.clearly-useful.iterator-protocol
- Author
Jason Aeschliman <j.aeschliman@gmail.com>
- License
revised BSD
- Description
A simple iterator protocol for Common Lisp.
- Version
0.1
- Dependencies
- com.clearly-useful.protocols
- com.clearly-useful.generic-collection-interface
- Source
com.clearly-useful.iterator-protocol.asd (file)
- Components
-
3 Files
Files are sorted by type and then listed depth-first from the systems
components trees.
3.1 Lisp
3.1.1 com.clearly-useful.iterator-protocol.asd
- Location
com.clearly-useful.iterator-protocol.asd
- Systems
com.clearly-useful.iterator-protocol (system)
3.1.2 com.clearly-useful.iterator-protocol/package.lisp
- Parent
com.clearly-useful.iterator-protocol (system)
- Location
package.lisp
- Packages
com.clearly-useful.iterator-protocol
3.1.3 com.clearly-useful.iterator-protocol/com.clearly-useful.iterator-protocol.lisp
- Dependency
package.lisp (file)
- Parent
com.clearly-useful.iterator-protocol (system)
- Location
com.clearly-useful.iterator-protocol.lisp
- Exported Definitions
-
- Internal Definitions
-
4 Packages
Packages are listed by definition order.
4.1 com.clearly-useful.iterator-protocol
- Source
package.lisp (file)
- Use List
- com.clearly-useful.generic-collection-interface
- com.clearly-useful.protocols
- common-lisp
- Exported Definitions
-
- Internal Definitions
-
5 Definitions
Definitions are sorted by export status, category, package, and then by
lexicographic order.
5.1 Exported definitions
5.1.1 Macros
- Macro: do-iterator (VAR FORM &optional RETURN-FORM) &body BODY
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
5.1.2 Functions
- Function: iterator-p OBJECT
-
test if object implements ITERATOR
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
5.1.3 Generic functions
- Generic Function: iterator OBJECT
-
convert an object to ITERATOR protocol, or error.
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Methods
- Method: iterator (A hash-table)
-
- Method: iterator (AN array)
-
- Method: iterator (A vector)
-
- Method: iterator OBJECT
-
- Method: iterator (OBJECT %indexable-iterator)
-
- Method: iterator (OBJECT %vector-iterator)
-
- Method: iterator (OBJECT %seq-iterator)
-
- Generic Function: iterator-finish! IT
-
performs ’clean up’ operations specific
to the iterator. e.g. closing a file.
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Methods
- Method: iterator-finish! (IT %indexable-iterator)
-
- Method: iterator-finish! (IT %vector-iterator)
-
- Method: iterator-finish! (IT %seq-iterator)
-
- Method: iterator-finish! IT
-
- Generic Function: iterator-next! IT
-
returns two values:
1. the next value of the iterator or nil,
2. t or nil depending depending whether a value was found.
then advances the iterator.
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Methods
- Method: iterator-next! (IT %indexable-iterator)
-
- Method: iterator-next! (IT %vector-iterator)
-
- Method: iterator-next! (IT %seq-iterator)
-
- Method: iterator-next! IT
-
5.1.4 Types
- Type: iterator ()
-
A simple iteration protocol for Common Lisp.
Unlike sequences, iterators are stateful, and are
not intended to be held onto or passed around. Their
use should be hidden by some other construct. If you
are explicitly creating and advancing an iterator,
chances are you are Doing It Wrong.
Iterators should be be treated as though they
have dynamic extent.
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
5.2 Internal definitions
5.2.1 Functions
- Function: %advance O
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %has-value O
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %indexable-iterator-idx INSTANCE
-
- Function: (setf %indexable-iterator-idx) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %indexable-iterator-p OBJECT
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %indexable-iterator-pos INSTANCE
-
- Function: (setf %indexable-iterator-pos) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %indexable-iterator-size INSTANCE
-
- Function: (setf %indexable-iterator-size) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %seq-iterator-p OBJECT
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %seq-iterator-seq INSTANCE
-
- Function: (setf %seq-iterator-seq) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %value O
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %vector-iterator-p OBJECT
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %vector-iterator-pos INSTANCE
-
- Function: (setf %vector-iterator-pos) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %vector-iterator-size INSTANCE
-
- Function: (setf %vector-iterator-size) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: %vector-iterator-vec INSTANCE
-
- Function: (setf %vector-iterator-vec) VALUE INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: copy-%indexable-iterator INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: copy-%seq-iterator INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: copy-%vector-iterator INSTANCE
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: make-%indexable-iterator &key (SIZE SIZE) (IDX IDX) (POS POS)
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: make-%seq-iterator &key (SEQ SEQ)
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Function: make-%vector-iterator &key (SIZE SIZE) (VEC VEC) (POS POS)
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
5.2.2 Structures
- Structure: %indexable-iterator ()
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Direct superclasses
structure-object (structure)
- Direct methods
-
- Direct slots
- Slot: size
-
- Readers
%indexable-iterator-size (function)
- Writers
(setf %indexable-iterator-size) (function)
- Slot: idx
-
- Readers
%indexable-iterator-idx (function)
- Writers
(setf %indexable-iterator-idx) (function)
- Slot: pos
-
- Readers
%indexable-iterator-pos (function)
- Writers
(setf %indexable-iterator-pos) (function)
- Structure: %seq-iterator ()
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Direct superclasses
structure-object (structure)
- Direct methods
-
- Direct slots
- Slot: seq
-
- Readers
%seq-iterator-seq (function)
- Writers
(setf %seq-iterator-seq) (function)
- Structure: %vector-iterator ()
-
- Package
com.clearly-useful.iterator-protocol
- Source
com.clearly-useful.iterator-protocol.lisp (file)
- Direct superclasses
structure-object (structure)
- Direct methods
-
- Direct slots
- Slot: size
-
- Readers
%vector-iterator-size (function)
- Writers
(setf %vector-iterator-size) (function)
- Slot: vec
-
- Readers
%vector-iterator-vec (function)
- Writers
(setf %vector-iterator-vec) (function)
- Slot: pos
-
- Readers
%vector-iterator-pos (function)
- Writers
(setf %vector-iterator-pos) (function)
Appendix A Indexes
A.1 Concepts
A.2 Functions
| Index Entry | | Section |
|
% | | |
| %advance : | | Internal functions |
| %has-value : | | Internal functions |
| %indexable-iterator-idx : | | Internal functions |
| %indexable-iterator-p : | | Internal functions |
| %indexable-iterator-pos : | | Internal functions |
| %indexable-iterator-size : | | Internal functions |
| %seq-iterator-p : | | Internal functions |
| %seq-iterator-seq : | | Internal functions |
| %value : | | Internal functions |
| %vector-iterator-p : | | Internal functions |
| %vector-iterator-pos : | | Internal functions |
| %vector-iterator-size : | | Internal functions |
| %vector-iterator-vec : | | Internal functions |
|
( | | |
| (setf %indexable-iterator-idx) : | | Internal functions |
| (setf %indexable-iterator-pos) : | | Internal functions |
| (setf %indexable-iterator-size) : | | Internal functions |
| (setf %seq-iterator-seq) : | | Internal functions |
| (setf %vector-iterator-pos) : | | Internal functions |
| (setf %vector-iterator-size) : | | Internal functions |
| (setf %vector-iterator-vec) : | | Internal functions |
|
C | | |
| copy-%indexable-iterator : | | Internal functions |
| copy-%seq-iterator : | | Internal functions |
| copy-%vector-iterator : | | Internal functions |
|
D | | |
| do-iterator : | | Exported macros |
|
F | | |
| Function, %advance : | | Internal functions |
| Function, %has-value : | | Internal functions |
| Function, %indexable-iterator-idx : | | Internal functions |
| Function, %indexable-iterator-p : | | Internal functions |
| Function, %indexable-iterator-pos : | | Internal functions |
| Function, %indexable-iterator-size : | | Internal functions |
| Function, %seq-iterator-p : | | Internal functions |
| Function, %seq-iterator-seq : | | Internal functions |
| Function, %value : | | Internal functions |
| Function, %vector-iterator-p : | | Internal functions |
| Function, %vector-iterator-pos : | | Internal functions |
| Function, %vector-iterator-size : | | Internal functions |
| Function, %vector-iterator-vec : | | Internal functions |
| Function, (setf %indexable-iterator-idx) : | | Internal functions |
| Function, (setf %indexable-iterator-pos) : | | Internal functions |
| Function, (setf %indexable-iterator-size) : | | Internal functions |
| Function, (setf %seq-iterator-seq) : | | Internal functions |
| Function, (setf %vector-iterator-pos) : | | Internal functions |
| Function, (setf %vector-iterator-size) : | | Internal functions |
| Function, (setf %vector-iterator-vec) : | | Internal functions |
| Function, copy-%indexable-iterator : | | Internal functions |
| Function, copy-%seq-iterator : | | Internal functions |
| Function, copy-%vector-iterator : | | Internal functions |
| Function, iterator-p : | | Exported functions |
| Function, make-%indexable-iterator : | | Internal functions |
| Function, make-%seq-iterator : | | Internal functions |
| Function, make-%vector-iterator : | | Internal functions |
|
G | | |
| Generic Function, iterator : | | Exported generic functions |
| Generic Function, iterator-finish! : | | Exported generic functions |
| Generic Function, iterator-next! : | | Exported generic functions |
|
I | | |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator : | | Exported generic functions |
| iterator-finish! : | | Exported generic functions |
| iterator-finish! : | | Exported generic functions |
| iterator-finish! : | | Exported generic functions |
| iterator-finish! : | | Exported generic functions |
| iterator-finish! : | | Exported generic functions |
| iterator-next! : | | Exported generic functions |
| iterator-next! : | | Exported generic functions |
| iterator-next! : | | Exported generic functions |
| iterator-next! : | | Exported generic functions |
| iterator-next! : | | Exported generic functions |
| iterator-p : | | Exported functions |
|
M | | |
| Macro, do-iterator : | | Exported macros |
| make-%indexable-iterator : | | Internal functions |
| make-%seq-iterator : | | Internal functions |
| make-%vector-iterator : | | Internal functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator : | | Exported generic functions |
| Method, iterator-finish! : | | Exported generic functions |
| Method, iterator-finish! : | | Exported generic functions |
| Method, iterator-finish! : | | Exported generic functions |
| Method, iterator-finish! : | | Exported generic functions |
| Method, iterator-next! : | | Exported generic functions |
| Method, iterator-next! : | | Exported generic functions |
| Method, iterator-next! : | | Exported generic functions |
| Method, iterator-next! : | | Exported generic functions |
|
A.3 Variables
A.4 Data types