-
-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
96 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| <!DOCTYPE html> <html lang="EN"> <head> <meta charset="utf-8"> <title>Trivial Extensible Sequences</title> <style>html body{margin:0 auto 0 auto;padding:20px;max-width:1024px;font-family:sans-serif;font-size:14pt;overflow-y:scroll;}html body a{text-decoration:none;}html body a[href]{color:#0055AA;}html body a[href]:hover{color:#0088EE;}html body pre{background:#FAFAFA;border:1px solid #DDDDDD;padding:0.75em;overflow-x:auto;}html body pre >code a[href]{color:#223388;}article.project h1,article.project h2,article.project h3,article.project h4,article.project h5,article.project h6{margin:0.2em 0 0.1em 0;text-indent:1em;}article.project >header{text-align:center;}article.project >header img.logo{display:block;margin:auto;max-height:170px;}article.project >header h1{display:inline-block;text-indent:0;font-size:2.5em;}article.project >header .version{vertical-align:bottom;}article.project >header .languages{margin-top:-0.5em;text-transform:capitalize;}article.project >header .description{margin:0;}article.project >header .pages{margin-top:0.5em;font-size:1.2em;text-transform:capitalize;}article.project >header .pages a{display:inline-block;padding:0 0.2em;}article.project >section{margin:1em 0 1em 0;}article.project #index >ul{list-style:none;margin:0;padding:0;}article.project .row label{display:inline-block;min-width:6em;}article.project #system .row{display:flex;}article.project #system #dependencies{display:inline;margin:0;padding:0;}article.project #system #dependencies li{display:inline;padding:0 0.2em;}article.definition{margin:1em 0 0 0;}article.definition >header h1,article.definition >header h2,article.definition >header h3,article.definition >header h4,article.definition >header h5,article.definition >header h6{text-indent:0;display:inline-block;}article.definition >header ul{display:inline-block;list-style:none;margin:0;padding:0;}article.definition >header ul li{display:inline-block;padding:0 0.2em 0 0;}article.definition >header .visibility{display:none;}article.definition >header .visibility,article.definition >header .type{text-transform:lowercase;}article.definition >header .source-link{visibility:hidden;float:right;}article.definition >header .source-link:after{visibility:visible;content:"[SRC]";}article.definition .docstring{margin:0 0 0 1em;}article.definition .docstring pre{font-size:0.8em;white-space:pre-wrap;}.definition.package >header ul.nicknames{display:inline-block;list-style:none;margin:0;padding:0 0 0 1em;}.definition.package >header ul.nicknames li{display:inline;}.definition.package >header ul.nicknames:before{content:"(";}.definition.package >header ul.nicknames:after{content:")";}.definition.package ul.definitions{margin:0;list-style:none;padding:0 0 0 0.5em;}.definition.callable >header .name:before,.definition.type >header .name:before{content:"(";font-weight:normal;}.definition.callable >header .arguments:after,.definition.type >header .arguments:after{content:")";}.definition.callable >header .arguments .arguments:before,.definition.type >header .arguments .arguments:before{content:"(";}.definition.callable >header .arguments .argument,.definition.type >header .arguments .argument{padding:0;}.definition.callable >header .arguments .argument.lambda-list-keyword,.definition.type >header .arguments .argument.lambda-list-keyword{color:#991155;}.definition li>mark{background:none;border-left:0.3em solid #0088EE;padding-left:0.3em;display:block;}</style> </head> <body> <article class="project"> <header> <h1>trivial extensible sequences</h1> <span class="version">1.0.0</span> <nav class="languages"> <a href="index.html">English</a> </nav> <p class="description">Portability library for the extensible sequences protocol.</p> <nav class="pages"> <a href="index.html">trivial extensible sequences</a> </nav> </header> <section id="documentation"><article><h2 id="About">About</h2><p>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.</p><p>The extensible sequences protocol is defined in 'User-extensible sequences in Common Lisp' by Christophe Rhodes<sup class="footnote-reference"><a href="#footnote-1">[1]</a></sup>. Also see the <a class="external-link" href="http://www.sbcl.org/manual/#Extensible-Sequences">SBCL manual</a>. Please refer to the above documents as well as the sequence operations in the hyperspec for documentation.</p><h2 id="How To">How To</h2><p>The basic operation is rather simple. All the functionality is defined in the <code>org.shirakumo.trivial-extensible-sequences</code> package – you may want to use a package-local-nickname to alias it to <code>sequences</code>.</p><p>First, create a subclass of <code><a href="#CLASS%20ORG.SHIRAKUMO.TRIVIAL-EXTENSIBLE-SEQUENCES.DOC%3ASEQUENCE" class="xref">sequence</a></code>. 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.</p><code style="display:block" class="code-block" data-language="lisp"><pre>(<a href="http://l1sp.org/cl/defclass" class="xref">defclass</a> value-as-sequence (sequences:sequence) | ||
| ((value :initarg :value :initform (<a href="http://l1sp.org/cl/error" class="xref">error</a> "VALUE required.") :accessor value)))</pre></code><p>Then you should add methods on <code><a href="#FUNCTION%20ORG.SHIRAKUMO.TRIVIAL-EXTENSIBLE-SEQUENCES.DOC%3ALENGTH" class="xref">length</a></code>, <code><a href="#FUNCTION%20ORG.SHIRAKUMO.TRIVIAL-EXTENSIBLE-SEQUENCES.DOC%3AELT" class="xref">elt</a></code>, <code>(setf elt)</code>, <code>adjust-sequence</code> and <code>make-sequence-like</code>.</p><code style="display:block" class="code-block" data-language="lisp"><pre>(<a href="http://l1sp.org/cl/defmethod" class="xref">defmethod</a> sequences:length ((sequence value-as-sequence)) | ||
| 1) | ||
|
|
||
| (<a href="http://l1sp.org/cl/defmethod" class="xref">defmethod</a> sequences:elt ((sequence value-as-sequence) index) | ||
| (<a href="http://l1sp.org/cl/check-type" class="xref">check-type</a> index (integer 0 0)) | ||
| (value sequence)) | ||
|
|
||
| (<a href="http://l1sp.org/cl/defmethod" class="xref">defmethod</a> (setf sequences:elt) (value (sequence value-as-sequence) index) | ||
| (<a href="http://l1sp.org/cl/check-type" class="xref">check-type</a> index (integer 0 0)) | ||
| (<a href="http://l1sp.org/cl/setf" class="xref">setf</a> (value sequence) value)) | ||
|
|
||
| (<a href="http://l1sp.org/cl/defmethod" class="xref">defmethod</a> sequences:adjust-sequence ((sequence value-as-sequence) length &key initial-contents initial-element) | ||
| (<a href="http://l1sp.org/cl/check-type" class="xref">check-type</a> length (integer 1 1)) | ||
| (<a href="http://l1sp.org/cl/when" class="xref">when</a> initial-contents | ||
| (<a href="http://l1sp.org/cl/setf" class="xref">setf</a> (value sequence) (<a href="http://l1sp.org/cl/elt" class="xref">elt</a> initial-contents 0))) | ||
| sequence) | ||
|
|
||
| (<a href="http://l1sp.org/cl/defmethod" class="xref">defmethod</a> sequences:make-sequence-like ((sequence value-as-sequence) length &key initial-contents initial-element) | ||
| (<a href="http://l1sp.org/cl/check-type" class="xref">check-type</a> length (integer 1 1)) | ||
| (<a href="http://l1sp.org/cl/make-instance" class="xref">make-instance</a> 'value-as-sequence | ||
| :value (<a href="http://l1sp.org/cl/or" class="xref">or</a> (<a href="http://l1sp.org/cl/elt" class="xref">elt</a> initial-contents 0) initial-element (value sequence))))</pre></code><p>If you leave out any of these functions, some of the sequence operators will not work and will instead signal a <code>protocol-unimplemented</code> 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.</p><p>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 <code>make-sequence-iterator</code>. This method should return 9 values:</p><ol><li value="1"><p>An iteration state value.</p></li><li value="2"><p>A value describing the limit of iteration, if any.</p></li><li value="3"><p>The from-end value.</p></li><li value="4"><p>A step function of three arguments: the sequence, the state value, the from-end value. The function should return the new state value.</p></li><li value="5"><p>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.</p></li><li value="6"><p>An element read function of two arguments: the sequence, the state value.</p></li><li value="7"><p>An element write function of three arguments: the new value to store, the sequence, the state value.</p></li><li value="8"><p>An index function of two arguments: the sequence, the state value. The function should return the current iteration index, starting from zero.</p></li><li value="9"><p>An iterator copy function of two arguments: the sequence, the state value. The function should return a "fresh" iteration value.</p></li></ol><p>Here's what it might look like for our relatively useless example sequence type:</p><code style="display:block" class="code-block" data-language="lisp"><pre>(<a href="http://l1sp.org/cl/defmethod" class="xref">defmethod</a> sequences:make-sequence-iterator ((sequence value-as-sequence) &key start end from-end) | ||
| (<a href="http://l1sp.org/cl/values" class="xref">values</a> 0 1 from-end | ||
| (lambda (seq state from-end) (<a href="http://l1sp.org/cl/1%2B" class="xref">1+</a> state)) | ||
| (lambda (seq state limit from-end) (<a href="http://l1sp.org/cl/%3C" class="xref"><</a> state limit)) | ||
| (lambda (seq state) (value seq)) | ||
| (lambda (value seq state) (<a href="http://l1sp.org/cl/setf" class="xref">setf</a> (value seq) value)) | ||
| (lambda (seq state) state) | ||
| (lambda (seq state) state)))</pre></code><p>Obviously for more complicated sequences the functions and state could be more interesting than this. Note that you can use iterators more easily using <code>with-sequence-iterator</code>, <code>with-sequence-iterator-funcntions</code>, and <code>dosequence</code>.</p><h2 id="Implementation Support">Implementation Support</h2><p>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.</p><ul><li><p>ABCL</p></li><li><p>SBCL</p></li></ul><p>On any other implementation, this package provides a <em>fallback</em> implementation of the protocol. The protocol should work completely with the following caveats:</p><ul><li><p>You must use the functions provided by this package to handle your sequences, rather than the ones from the <code>cl</code> package.</p></li><li><p>Custom sequences defined with a subclass will not actually be a subtype of <code><a href="http://l1sp.org/cl/sequence" class="xref">cl:sequence</a></code>.</p></li><li><p>The fallback protocol will be slower than what the implementation could provide.</p></li></ul><p>Meaning you can still make things work most of the time, but with some heavy caveats. For this reason, <strong>please contact your implementation maintainers and request for the protocol to be implemented natively</strong>. The source code of the fallback implementation, as well as <a class="external-link" href="https://github.com/sbcl/sbcl/blob/master/src/pcl/sequence.lisp">SBCL's own implementation</a> are licensed liberally and should serve as a good basis.</p><footer class="footnotes"><hr></hr><ol><li value="1" id="footnote-1"><a href="http://www.doc.gold.ac.uk/%7Emas01cr/papers/ilc2007/sequences-20070301.pdf">http://www.doc.gold.ac.uk/%7Emas01cr/papers/ilc2007/sequences-20070301.pdf</a></li></ol></footer></article></section> <section id="system"> <h2>System Information</h2> <div class="row"> <label for="version">Version:</label> <a id="version">1.0.0</a> </div> <div class="row"> <label for="author">Author:</label> <a id="author" href="mailto:shinmera@tymoon.eu">Nicolas Hafner</a> </div> <div class="row"> <label for="license">License:</label> <a id="license" href="https://github.com/shinmera/trivial-extensible-sequences/blob/master/LICENSE">zlib</a> </div> <div class="row"> <label for="homepage">Homepage:</label> <a id="homepage" href="https://shinmera.github.io/trivial-extensible-sequences/">https://shinmera.github.io/trivial-extensible-sequences/</a> </div> </section> <section id="index"> <h2>Definition Index</h2> <ul> <li> <article class="definition package" id="PACKAGE ORG.SHIRAKUMO.TRIVIAL-EXTENSIBLE-SEQUENCES.DOC"> <header> <h3> <a href="#PACKAGE%20ORG.SHIRAKUMO.TRIVIAL-EXTENSIBLE-SEQUENCES.DOC">ORG.SHIRAKUMO.TRIVIAL-EXTENSIBLE-SEQUENCES.DOC</a> </h3> <ul class="nicknames"></ul> </header> <div class="docstring"><i>No documentation provided.</i></div> <ul class="definitions"></ul> </article> </li> </ul> </section> </article> <script>window.addEventListener("DOMContentLoaded", function(){ | ||
| var unmarkElement = function(el){ | ||
| if(el.tagName === "mark" || el.tagName === "MARK"){ | ||
| [].forEach.call(el.childNodes, function(child){ | ||
| el.parentNode.insertBefore(child, el); | ||
| }); | ||
| el.parentNode.removeChild(el); | ||
| }else if(el.parentNode.tagName === "mark"){ | ||
| return unmarkElement(el.parentNode); | ||
| } | ||
| return null; | ||
| } | ||
|
|
||
| var unmarkAll = function(root){ | ||
| root = root || document; | ||
| [].forEach.call(root.querySelectorAll("mark"), unmarkElement); | ||
| } | ||
|
|
||
| var markElement = function(el){ | ||
| if(el.parentNode.tagName === "mark" || el.parentNode.tagName === "MARK"){ | ||
| return el.parentNode; | ||
| } else { | ||
| unmarkAll(); | ||
| var marked = document.createElement("mark"); | ||
| el.parentNode.insertBefore(marked, el); | ||
| marked.appendChild(el); | ||
| return marked; | ||
| } | ||
| } | ||
|
|
||
| var markFragmented = function(){ | ||
| if(window.location.hash){ | ||
| var el = document.getElementById(decodeURIComponent(window.location.hash.substr(1))); | ||
| if(el) markElement(el); | ||
| } | ||
| } | ||
|
|
||
| var registerXrefLink = function(link){ | ||
| var el = document.getElementById(decodeURIComponent(link.getAttribute("href").substr(1))); | ||
| if(el){ | ||
| link.addEventListener("click", function(){ | ||
| markElement(el); | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| var registerXrefLinks = function(root){ | ||
| root = root || document; | ||
| [].forEach.call(root.querySelectorAll("a.xref"), registerXrefLink); | ||
| } | ||
|
|
||
| markFragmented(); | ||
| registerXrefLinks(); | ||
| }); </script> </body> </html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| (asdf:load-system :staple-markless) | ||
|
|
||
| (defpackage #:org.shirakumo.trivial-extensible-sequences.doc | ||
| (:use #:cl) | ||
| (:local-nicknames (#:sequences #:org.shirakumo.trivial-extensible-sequences))) | ||
|
|
||
| (defmethod staple:packages ((_ (eql (asdf:find-system :trivial-extensible-sequences)))) | ||
| (list (find-package '#:org.shirakumo.trivial-extensible-sequences.doc))) | ||
|
|
||
| #+sbcl | ||
| (defmethod staple:definition-wanted-p ((_ definitions:source-transform) page) NIL) |