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 Mon Apr 19 15:43:29 2021 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

• package.lisp (file)
• com.clearly-useful.iterator-protocol.lisp (file)

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

• do-iterator (macro)
• iterator (generic function)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (type)
• iterator-finish! (generic function)
• iterator-finish! (method)
• iterator-finish! (method)
• iterator-finish! (method)
• iterator-finish! (method)
• iterator-next! (generic function)
• iterator-next! (method)
• iterator-next! (method)
• iterator-next! (method)
• iterator-next! (method)
• iterator-p (function)

Internal Definitions

• %advance (function)
• %has-value (function)
• %indexable-iterator (structure)
• %indexable-iterator-idx (function)
• (setf %indexable-iterator-idx) (function)
• %indexable-iterator-p (function)
• %indexable-iterator-pos (function)
• (setf %indexable-iterator-pos) (function)
• %indexable-iterator-size (function)
• (setf %indexable-iterator-size) (function)
• %seq-iterator (structure)
• %seq-iterator-p (function)
• %seq-iterator-seq (function)
• (setf %seq-iterator-seq) (function)
• %value (function)
• %vector-iterator (structure)
• %vector-iterator-p (function)
• %vector-iterator-pos (function)
• (setf %vector-iterator-pos) (function)
• %vector-iterator-size (function)
• (setf %vector-iterator-size) (function)
• %vector-iterator-vec (function)
• (setf %vector-iterator-vec) (function)
• copy-%indexable-iterator (function)
• copy-%seq-iterator (function)
• copy-%vector-iterator (function)
• make-%indexable-iterator (function)
• make-%seq-iterator (function)
• make-%vector-iterator (function)

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

• do-iterator (macro)
• iterator (generic function)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (method)
• iterator (type)
• iterator-finish! (generic function)
• iterator-finish! (method)
• iterator-finish! (method)
• iterator-finish! (method)
• iterator-finish! (method)
• iterator-next! (generic function)
• iterator-next! (method)
• iterator-next! (method)
• iterator-next! (method)
• iterator-next! (method)
• iterator-p (function)

Internal Definitions

• %advance (function)
• %has-value (function)
• %indexable-iterator (structure)
• %indexable-iterator-idx (function)
• (setf %indexable-iterator-idx) (function)
• %indexable-iterator-p (function)
• %indexable-iterator-pos (function)
• (setf %indexable-iterator-pos) (function)
• %indexable-iterator-size (function)
• (setf %indexable-iterator-size) (function)
• %seq-iterator (structure)
• %seq-iterator-p (function)
• %seq-iterator-seq (function)
• (setf %seq-iterator-seq) (function)
• %value (function)
• %vector-iterator (structure)
• %vector-iterator-p (function)
• %vector-iterator-pos (function)
• (setf %vector-iterator-pos) (function)
• %vector-iterator-size (function)
• (setf %vector-iterator-size) (function)
• %vector-iterator-vec (function)
• (setf %vector-iterator-vec) (function)
• copy-%indexable-iterator (function)
• copy-%seq-iterator (function)
• copy-%vector-iterator (function)
• make-%indexable-iterator (function)
• make-%seq-iterator (function)
• make-%vector-iterator (function)

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

• implements-protocol? (method)
• iterator (method)
• iterator-next! (method)
• iterator-finish! (method)

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

• implements-protocol? (method)
• iterator (method)
• iterator-next! (method)
• iterator-finish! (method)

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

• implements-protocol? (method)
• iterator (method)
• iterator-next! (method)
• iterator-finish! (method)

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

A.3 Variables

A.4 Data types