The trivial-extensible-sequences Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-extensible-sequences Reference Manual

This is the trivial-extensible-sequences Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 06:19:46 2022 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

## About
This package provides a portability layer for the extensible sequences standard extension to Common Lisp. Extensible sequences allow you to create your own sequence types that integrate with the rest of the functions and operations that interact with sequences.

The extensible sequences protocol is defined in 'User-extensible sequences in Common Lisp' by Christophe Rhodes[1]. Also see the "SBCL manual"( Please refer to the above documents as well as the sequence operations in the hyperspec for documentation.


## How To
The basic operation is rather simple. All the functionality is defined in the ``org.shirakumo.trivial-extensible-sequences`` package -- you may want to use a package-local-nickname to alias it to ``sequences``.

First, create a subclass of ``sequence``. This will be your new sequence type. For this how-to, we'll define a sequence type that can represent any value as a sequence of length 1.

::: lisp
(defclass value-as-sequence (sequences:sequence)
  ((value :initarg :value :initform (error "VALUE required.") :accessor value)))

Then you should add methods on ``length``, ``elt``, ``(setf elt)``, ``adjust-sequence`` and ``make-sequence-like``.

::: lisp
(defmethod sequences:length ((sequence value-as-sequence))

(defmethod sequences:elt ((sequence value-as-sequence) index)
  (check-type index (integer 0 0))
  (value sequence))

(defmethod (setf sequences:elt) (value (sequence value-as-sequence) index)
  (check-type index (integer 0 0))
  (setf (value sequence) value))

(defmethod sequences:adjust-sequence ((sequence value-as-sequence) length &key initial-contents initial-element)
  (check-type length (integer 1 1))
  (when initial-contents
    (setf (value sequence) (elt initial-contents 0)))

(defmethod sequences:make-sequence-like ((sequence value-as-sequence) length &key initial-contents initial-element)
  (check-type length (integer 1 1))
  (make-instance 'value-as-sequence
                 :value (or (elt initial-contents 0) initial-element (value sequence))))

If you leave out any of these functions, some of the sequence operators will not work and will instead signal a ``protocol-unimplemented`` error on use. If you do provide a method on each, then all the sequence operators should work out of the box using generic implementations. If you would like to speed up a particular operation for your sequence type, you can also define a specific implementation by adding a method to that function.

Also useful is to explicitly support the iterator protocol, which should allow most default operations to be performed much faster. To do so you only need to define a method on ``make-sequence-iterator``. This method should return 9 values:

1. An iteration state value.
2. A value describing the limit of iteration, if any.
3. The from-end value.
4. A step function of three arguments: the sequence, the state value, the from-end value. The function should return the new state value.
5. An end predicate of four arguments: the sequence, the state value, the limit value, the from-end value. The function should return a generalised boolean describing whether the iteration has reached the end of the sequence.
6. An element read function of two arguments: the sequence, the state value.
7. An element write function of three arguments: the new value to store, the sequence, the state value.
8. An index function of two arguments: the sequence, the state value. The function should return the current iteration index, starting from zero.
9. An iterator copy function of two arguments: the sequence, the state value. The function should return a "fresh" iteration value.

Here's what it might look like for our relatively useless example sequence type:

::: lisp
(defmethod sequences:make-sequence-iterator ((sequence value-as-sequence) &key start end from-end)
  (values 0 1 from-end
          (lambda (seq state from-end) (1+ state))
          (lambda (seq state limit from-end) (< state limit))
          (lambda (seq state) (value seq))
          (lambda (value seq state) (setf (value seq) value))
          (lambda (seq state) state)
          (lambda (seq state) state)))

Obviously for more complicated sequences the functions and state could be more interesting than this. Note that you can use iterators more easily using ``with-sequence-iterator``, ``with-sequence-iterator-funcntions``, and ``dosequence``.

## Implementation Support
The following implementations have native support for extensible sequences. On those implementations, this package will merely be an alias for the implementation's sequences package.

- Clasp

On any other implementation, this package provides a //fallback// implementation of the protocol. The protocol should work completely with the following caveats:

- You must use the functions provided by this package to handle your sequences, rather than the ones from the ``cl`` package.
- Custom sequences defined with a subclass will not actually be a subtype of ``cl:sequence``.
- The fallback protocol will be slower than what the implementation could provide.

Meaning you can still make things work most of the time, but with some heavy caveats. For this reason, **please contact your implementation maintainers and request for the protocol to be implemented natively**. The source code of the fallback implementation, as well as "SBCL's own implementation"( are licensed liberally and should serve as a good basis.

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

2.1 trivial-extensible-sequences


Nicolas Hafner <>


Nicolas Hafner <>

Home Page

Source Control

(:git "")

Bug Tracker




Portability library for the extensible sequences protocol.




required module extensible-sequences (for feature abcl)


trivial-extensible-sequences.asd (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

3.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 trivial-extensible-sequences.asd




trivial-extensible-sequences (system)

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 trivial-extensible-sequences/api.lisp


trivial-extensible-sequences (system)





Previous: , Up: Lisp files   [Contents][Index]

3.1.3 trivial-extensible-sequences/fallback.lisp

If Feature

(not (or sbcl abcl clasp))


api.lisp (file)


trivial-extensible-sequences (system)



Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

4.1 org.shirakumo.trivial-extensible-sequences


api.lisp (file)

Use List


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

File, Lisp, trivial-extensible-sequences.asd: The trivial-extensible-sequences․asd file
File, Lisp, trivial-extensible-sequences/api.lisp: The trivial-extensible-sequences/api․lisp file
File, Lisp, trivial-extensible-sequences/fallback.lisp: The trivial-extensible-sequences/fallback․lisp file

Lisp File, trivial-extensible-sequences.asd: The trivial-extensible-sequences․asd file
Lisp File, trivial-extensible-sequences/api.lisp: The trivial-extensible-sequences/api․lisp file
Lisp File, trivial-extensible-sequences/fallback.lisp: The trivial-extensible-sequences/fallback․lisp file

trivial-extensible-sequences.asd: The trivial-extensible-sequences․asd file
trivial-extensible-sequences/api.lisp: The trivial-extensible-sequences/api․lisp file
trivial-extensible-sequences/fallback.lisp: The trivial-extensible-sequences/fallback․lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   O   P   S   T  
Index Entry  Section

org.shirakumo.trivial-extensible-sequences: The org․shirakumo․trivial-extensible-sequences package

Package, org.shirakumo.trivial-extensible-sequences: The org․shirakumo․trivial-extensible-sequences package

System, trivial-extensible-sequences: The trivial-extensible-sequences system

trivial-extensible-sequences: The trivial-extensible-sequences system

Jump to:   O   P   S   T