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 Mon Dec 02 11:32:43 2019 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"(http://www.sbcl.org/manual/#Extensible-Sequences). Please refer to the above documents as well as the sequence operations in the hyperspec for documentation.

[1] http://www.doc.gold.ac.uk/%7Emas01cr/papers/ilc2007/sequences-20070301.pdf

## 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))
  1)

(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)))
  sequence)

(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.

- ABCL
- SBCL

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"(https://github.com/sbcl/sbcl/blob/master/src/pcl/sequence.lisp) 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

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://shinmera.github.io/trivial-extensible-sequences/

Source Control

(:git "https://github.com/shinmera/trivial-extensible-sequences.git")

Bug Tracker

https://github.com/Shinmera/trivial-extensible-sequences/issues

License

zlib

Description

Portability library for the extensible sequences protocol.

Version

1.0.0

Dependency

required module extensible-sequences (for feature abcl)

Source

trivial-extensible-sequences.asd (file)

Components

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

Location

trivial-extensible-sequences.asd

Systems

trivial-extensible-sequences (system)


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

3.1.2 trivial-extensible-sequences/api.lisp

Parent

trivial-extensible-sequences (system)

Location

api.lisp

Packages

org.shirakumo.trivial-extensible-sequences


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

3.1.3 trivial-extensible-sequences/fallback.lisp

If Feature

(not (or sbcl abcl))

Dependency

api.lisp (file)

Parent

trivial-extensible-sequences (system)

Location

fallback.lisp


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

Source

api.lisp (file)

Use List

sb-sequence


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

F
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

L
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

T
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

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

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

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

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

Jump to:   O   P   S   T