The cl-netstring+ Reference Manual

Table of Contents

The cl-netstring+ Reference Manual

This is the cl-netstring+ Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:35:22 2020 GMT+0.

1 Introduction

* About
  CL-NETSTRING+ is a library for working with a modified form of
  [[http://cr.yp.to/proto/netstrings.txt][netstrings]].

* Netstring+ Format
  The Netstring+ format is identical to the [[http://cr.yp.to/proto/netstrings.txt][netstring]] format except
  for two details:
  1. The header is written in (printed) hexadecimal instead of
     decimal, and UTF-8 encoding is specified for non-data portions.
  2. The terminating character is =\n= (linefeed) instead of a comma.

  These two changes were made for readability and portability
  reasons. Separating messages with a linefeed is easier to read with
  long messages than a comma (particularly if commas may appear in the
  message). A hexadecimal header aligns well when the size of messages
  must be stored in a fixed-size type: determining whether a message
  length is too long is a matter of counting digits, rather than
  converting bases.

* API
  : (defun write-netstring-bytes (stream data))
  Netstring+-encode a byte-vector =data= and write it to
  =stream=. =stream= must be a byte-stream.

  : (defun read-netstring-data (stream))
  Return a byte-vector of Netstring+-decoded data from
  =stream=. =stream= must be a byte-stream.

  : (defun netstring-bytes (data))
  Return a byte-vector of the Netstring+-encoded =data=.

  : (defun netstring-data (bytes))
  Return the byte-vector encoded in the Netstring+ =bytes=.

  : (defmacro data (sequence))
  This macro is used to precompute static Netstring+ data at
  macroexpansion-time. =sequence= is a byte-vector of data to be
  encoded.

  : (defmacro str (string))
  Like =data=, this macro precomputes a static Netstring+ at
  macroexpansion-time, except that =string= will be UTF-8 encoded
  before the Netstring+ is produced.



* Future TODOs
  - Document conditions that may be signalled.
  - Consider using fast-io for some of the byte-vector stuff.
  - Add a resynchronizing restart when there is a read error.

2 Systems

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

2.1 cl-netstring+

Author

Matthew Stickney <mtstickney@gmail.com>

License

MIT

Description

A simple library for sending and receiving messages with a netstring-like encoding.

Dependencies

• trivial-utf-8
• flexi-streams

Source

cl-netstring+.asd (file)

Components

• package.lisp (file)
• netstring-plus.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 cl-netstring+.asd

Location

cl-netstring+.asd

Systems

cl-netstring+ (system)

3.1.2 cl-netstring+/package.lisp

Parent

cl-netstring+ (system)

Location

package.lisp

Packages

cl-netstring+

3.1.3 cl-netstring+/netstring-plus.lisp

Dependency

package.lisp (file)

Parent

cl-netstring+ (system)

Location

netstring-plus.lisp

Exported Definitions

• data (macro)
• make-decoder-state (function)
• netstring-bytes (function)
• netstring-bytes* (function)
• netstring-data (function)
• next-read-size (function)
• pump-byte! (function)
• pump-stream! (function)
• pump-vector! (function)
• read-netstring-data (function)
• str (macro)
• write-netstring-bytes (function)
• write-netstring-bytes* (function)

Internal Definitions

• add-data-byte! (function)
• add-header-digit! (function)
• ascii-hex-digit-p (function)
• decoder-state (class)
• empty-header (condition)
• expected-size (method)
• found-char (method)
• invalid-char (method)
• invalid-header-character (condition)
• msg-data (method)
• (setf msg-data) (method)
• netstring-parse-error (condition)
• size (method)
• (setf size) (method)
• state (method)
• (setf state) (method)
• too-much-data (condition)
• transition-state! (function)

4 Packages

Packages are listed by definition order.

4.1 cl-netstring+

Source

package.lisp (file)

Nickname

nsp

Use List

common-lisp

Exported Definitions

• data (macro)
• make-decoder-state (function)
• netstring-bytes (function)
• netstring-bytes* (function)
• netstring-data (function)
• next-read-size (function)
• pump-byte! (function)
• pump-stream! (function)
• pump-vector! (function)
• read-netstring-data (function)
• str (macro)
• write-netstring-bytes (function)
• write-netstring-bytes* (function)

Internal Definitions

• add-data-byte! (function)
• add-header-digit! (function)
• ascii-hex-digit-p (function)
• decoder-state (class)
• empty-header (condition)
• expected-size (generic function)
• expected-size (method)
• found-char (generic function)
• found-char (method)
• invalid-char (generic function)
• invalid-char (method)
• invalid-header-character (condition)
• msg-data (generic function)
• msg-data (method)
• (setf msg-data) (method)
• (setf msg-data) (generic function)
• netstring-parse-error (condition)
• size (generic function)
• size (method)
• (setf size) (method)
• (setf size) (generic function)
• state (generic function)
• state (method)
• (setf state) (method)
• (setf state) (generic function)
• too-much-data (condition)
• transition-state! (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: data SEQUENCE

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Macro: str STRING

Package

cl-netstring+

Source

netstring-plus.lisp (file)

5.1.2 Functions

Function: make-decoder-state &rest ARGS &key STATE SIZE DATA

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: netstring-bytes &rest DATA

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: netstring-bytes* DATAE

Return a netstring encoding for the concatenation of DATAE.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: netstring-data BYTES

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: next-read-size STATE

Return the size of the next chunk of data that STATE expects as an efficiency hint.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: pump-byte! STATE BYTE

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: pump-stream! STREAM STATE &key COUNT BYTES

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: pump-vector! VECTOR STATE &key START END COUNT

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: read-netstring-data STREAM

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: write-netstring-bytes STREAM &rest DATAE

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: write-netstring-bytes* STREAM DATAE

Package

cl-netstring+

Source

netstring-plus.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: add-data-byte! STATE BYTE

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: add-header-digit! STATE N

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: ascii-hex-digit-p CODE

Return T if CODE is the ASCII value for a hexadecimal digit, NIL otherwise.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Function: transition-state! STATE TO-STATE

Package

cl-netstring+

Source

netstring-plus.lisp (file)

5.2.2 Generic functions

Generic Function: expected-size CONDITION

Package

cl-netstring+

Methods

Method: expected-size (CONDITION too-much-data)

Source

netstring-plus.lisp (file)

Generic Function: found-char CONDITION

Package

cl-netstring+

Methods

Method: found-char (CONDITION too-much-data)

Source

netstring-plus.lisp (file)

Generic Function: invalid-char CONDITION

Package

cl-netstring+

Methods

Method: invalid-char (CONDITION invalid-header-character)

Source

netstring-plus.lisp (file)

Generic Function: msg-data OBJECT

Generic Function: (setf msg-data) NEW-VALUE OBJECT

Package

cl-netstring+

Methods

Method: msg-data (DECODER-STATE decoder-state)

automatically generated reader method

Source

netstring-plus.lisp (file)

Method: (setf msg-data) NEW-VALUE (DECODER-STATE decoder-state)

automatically generated writer method

Source

netstring-plus.lisp (file)

Generic Function: size OBJECT

Generic Function: (setf size) NEW-VALUE OBJECT

Package

cl-netstring+

Methods

Method: size (DECODER-STATE decoder-state)

automatically generated reader method

Source

netstring-plus.lisp (file)

Method: (setf size) NEW-VALUE (DECODER-STATE decoder-state)

automatically generated writer method

Source

netstring-plus.lisp (file)

Generic Function: state OBJECT

Generic Function: (setf state) NEW-VALUE OBJECT

Package

cl-netstring+

Methods

Method: state (DECODER-STATE decoder-state)

automatically generated reader method

Source

netstring-plus.lisp (file)

Method: (setf state) NEW-VALUE (DECODER-STATE decoder-state)

automatically generated writer method

Source

netstring-plus.lisp (file)

5.2.3 Conditions

Condition: empty-header ()

Condition representing a netstring header with no size digits.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Direct superclasses

netstring-parse-error (condition)

Condition: invalid-header-character ()

Condition representing an invalid character in a netstring header.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Direct superclasses

netstring-parse-error (condition)

Direct methods

invalid-char (method)

Direct slots

Slot: invalid-char

Initargs

:char

Readers

invalid-char (generic function)

Condition: netstring-parse-error ()

Generic condition representing all netstring parse errors.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• empty-header (condition)
• invalid-header-character (condition)
• too-much-data (condition)

Condition: too-much-data ()

Condition representing a missing terminator after the data bytes.

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Direct superclasses

netstring-parse-error (condition)

Direct methods

• found-char (method)
• expected-size (method)

Direct slots

Slot: expected-size

Initargs

:expected-size

Readers

expected-size (generic function)

Slot: found-char

Initargs

:found

Readers

found-char (generic function)

5.2.4 Classes

Class: decoder-state ()

Package

cl-netstring+

Source

netstring-plus.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• print-object (method)
• msg-data (method)
• msg-data (method)
• size (method)
• size (method)
• state (method)
• state (method)

Direct slots

Slot: state

Initargs

:state

Readers

state (generic function)

Writers

(setf state) (generic function)

Slot: data-size

Initargs

:size

Readers

size (generic function)

Writers

(setf size) (generic function)

Slot: message-data

Initargs

:data

Readers

msg-data (generic function)

Writers

(setf msg-data) (generic function)

Direct Default Initargs

Initarg	Value
:state	:initial
:size	0
:data	nil

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types