cl-octet-streams

#+TITLE: cl-octet-streams

*cl-octet-streams* is a library implementing in-memory octet streams for Common Lisp.
It was inspired by the [[https://github.com/sharplispers/trivial-octet-streams][trivial-octet-streams]] and [[https://github.com/smithzvk/cl-plumbing][cl-plumbing]] libraries.

* Installation

The only dependency is the [[https://common-lisp.net/project/trivial-gray-streams][trivial-gray-streams]] library.

* API
** Input stream

#+BEGIN_SRC lisp
(make-octet-input-stream seq &optional (start 0) end) => stream
#+END_SRC

Return an input stream which will supply the bytes of /seq/ between /start/ and
/end/ in order.

#+BEGIN_SRC lisp
(with-octet-input-stream (var seq &optional (start 0) end) &body body)
#+END_SRC

Within /body/, /var/ is bound to an octet input stream defined by /seq/, /start/
and /end/. The result of the last form of /body/ is returned.

** Output stream

#+BEGIN_SRC lisp
(make-octet-output-stream) => stream
#+END_SRC

Return an output stream which will accumulate all the bytes written to it for
the benefit of the function /get-output-stream-octets/.

#+BEGIN_SRC lisp
(get-output-stream-octets stream) => bytes
#+END_SRC

Return the bytes that were written to an octet output /stream/.

#+BEGIN_SRC lisp
(with-octet-output-stream (var) &body body) => bytes
#+END_SRC

Within /body/, /var/ is bound to an octet output stream. After all the forms in
/body/ have been executed, the bytes that have been written to /var/ (and that
haven't been consumed by a call to /get-output-stream-octets/ within /body/) are
returned.

** Pipe

#+BEGIN_SRC lisp
(make-octet-pipe) => stream
#+END_SRC

Return a stream which will supply the bytes that have been written to it in
order.

#+BEGIN_SRC lisp
(with-octet-pipe (var) &body body)
#+END_SRC

Within /body/, /var/ is bound to an octet pipe. The result of the last form of
/body/ is returned.

** Connected streams

#+BEGIN_SRC lisp
(make-connected-octet-streams) => stream1, stream2
#+END_SRC

Return two streams connected to each other. The bytes written to the first
stream can be read from the second, and the bytes written to the second stream
can be read from the first.

#+BEGIN_SRC lisp
(with-connected-octet-streams (var1 var2) &body body)
#+END_SRC

Within /body/, /var1/ and /var2/ are bound to octet streams connected to each
other. The result of the last form of /body/ is returned.

** Extra functions

The following functions can be used on input streams, output streams and pipes.

#+BEGIN_SRC lisp
(octet-stream-length stream) => integer
#+END_SRC

Return the number of bytes available in /stream/.

#+BEGIN_SRC lisp
(octet-stream-ref stream index) => byte
#+END_SRC

Return the byte at /index/ in /stream/.

#+BEGIN_SRC lisp
(octet-stream-search stream pattern jump-table) => index or nil
#+END_SRC

Search /pattern/ in the bytes of /stream/ using the Boyer-Moore algorithm. The
/jump-table/ must be 256 bytes long. If there is a match, return the index of
the beginning of the /pattern/ in the /stream/, otherwise return ~nil~.

#+BEGIN_SRC lisp
(make-jump-table pattern) => array
#+END_SRC

Return a jump table for /pattern/ that can be used with /octet-stream-search/.

* Tests

The tests require the [[https://common-lisp.net/project/fiveam][fiveam]] library.

#+BEGIN_SRC lisp
(asdf:test-system "cl-octet-streams")
#+END_SRC


cl-octet-streams

Upstream URL

Author

License

cl-octet-streams

Version:

License:

Authors:

Dependencies:

cl-octet-streams/tests

Version:

License:

Authors:

Dependencies:

Dependencies (2)

Dependents (2)