The cl-netstring-plus Reference Manual

Table of Contents

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

The cl-netstring-plus Reference Manual

This is the cl-netstring-plus Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 13:51:52 2018 GMT+0.


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

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.


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 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
Source

cl-netstring+.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 cl-netstring+.asd

Location

cl-netstring+.asd

Systems

cl-netstring+ (system)


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

3.1.2 cl-netstring+/package.lisp

Parent

cl-netstring+ (system)

Location

package.lisp

Packages

cl-netstring+


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

3.1.3 cl-netstring+/netstring-plus.lisp

Dependency

package.lisp (file)

Parent

cl-netstring+ (system)

Location

netstring-plus.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-netstring+

Source

package.lisp (file)

Nickname

nsp

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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
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
Direct slots
Slot: expected-size
Initargs

:expected-size

Readers

expected-size (generic function)

Slot: found-char
Initargs

:found

Readers

found-char (generic function)


Previous: , Up: Internal definitions   [Contents][Index]

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
InitargValue
:state:initial
:size0
:datanil

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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-netstring+.asd: The cl-netstring+<dot>asd file
cl-netstring+/netstring-plus.lisp: The cl-netstring+/netstring-plus<dot>lisp file
cl-netstring+/package.lisp: The cl-netstring+/package<dot>lisp file

F
File, Lisp, cl-netstring+.asd: The cl-netstring+<dot>asd file
File, Lisp, cl-netstring+/netstring-plus.lisp: The cl-netstring+/netstring-plus<dot>lisp file
File, Lisp, cl-netstring+/package.lisp: The cl-netstring+/package<dot>lisp file

L
Lisp File, cl-netstring+.asd: The cl-netstring+<dot>asd file
Lisp File, cl-netstring+/netstring-plus.lisp: The cl-netstring+/netstring-plus<dot>lisp file
Lisp File, cl-netstring+/package.lisp: The cl-netstring+/package<dot>lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   (  
A   D   E   F   G   I   M   N   P   R   S   T   W  
Index Entry  Section

(
(setf msg-data): Internal generic functions
(setf msg-data): Internal generic functions
(setf size): Internal generic functions
(setf size): Internal generic functions
(setf state): Internal generic functions
(setf state): Internal generic functions

A
add-data-byte!: Internal functions
add-header-digit!: Internal functions
ascii-hex-digit-p: Internal functions

D
data: Exported macros

E
expected-size: Internal generic functions
expected-size: Internal generic functions

F
found-char: Internal generic functions
found-char: Internal generic functions
Function, add-data-byte!: Internal functions
Function, add-header-digit!: Internal functions
Function, ascii-hex-digit-p: Internal functions
Function, make-decoder-state: Exported functions
Function, netstring-bytes: Exported functions
Function, netstring-bytes*: Exported functions
Function, netstring-data: Exported functions
Function, next-read-size: Exported functions
Function, pump-byte!: Exported functions
Function, pump-stream!: Exported functions
Function, pump-vector!: Exported functions
Function, read-netstring-data: Exported functions
Function, transition-state!: Internal functions
Function, write-netstring-bytes: Exported functions
Function, write-netstring-bytes*: Exported functions

G
Generic Function, (setf msg-data): Internal generic functions
Generic Function, (setf size): Internal generic functions
Generic Function, (setf state): Internal generic functions
Generic Function, expected-size: Internal generic functions
Generic Function, found-char: Internal generic functions
Generic Function, invalid-char: Internal generic functions
Generic Function, msg-data: Internal generic functions
Generic Function, size: Internal generic functions
Generic Function, state: Internal generic functions

I
invalid-char: Internal generic functions
invalid-char: Internal generic functions

M
Macro, data: Exported macros
Macro, str: Exported macros
make-decoder-state: Exported functions
Method, (setf msg-data): Internal generic functions
Method, (setf size): Internal generic functions
Method, (setf state): Internal generic functions
Method, expected-size: Internal generic functions
Method, found-char: Internal generic functions
Method, invalid-char: Internal generic functions
Method, msg-data: Internal generic functions
Method, size: Internal generic functions
Method, state: Internal generic functions
msg-data: Internal generic functions
msg-data: Internal generic functions

N
netstring-bytes: Exported functions
netstring-bytes*: Exported functions
netstring-data: Exported functions
next-read-size: Exported functions

P
pump-byte!: Exported functions
pump-stream!: Exported functions
pump-vector!: Exported functions

R
read-netstring-data: Exported functions

S
size: Internal generic functions
size: Internal generic functions
state: Internal generic functions
state: Internal generic functions
str: Exported macros

T
transition-state!: Internal functions

W
write-netstring-bytes: Exported functions
write-netstring-bytes*: Exported functions

Jump to:   (  
A   D   E   F   G   I   M   N   P   R   S   T   W  

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

A.3 Variables

Jump to:   D   E   F   I   M   S  
Index Entry  Section

D
data-size: Internal classes

E
expected-size: Internal conditions

F
found-char: Internal conditions

I
invalid-char: Internal conditions

M
message-data: Internal classes

S
Slot, data-size: Internal classes
Slot, expected-size: Internal conditions
Slot, found-char: Internal conditions
Slot, invalid-char: Internal conditions
Slot, message-data: Internal classes
Slot, state: Internal classes
state: Internal classes

Jump to:   D   E   F   I   M   S  

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

A.4 Data types

Jump to:   C   D   E   I   N   P   S   T  
Index Entry  Section

C
cl-netstring+: The cl-netstring+ system
cl-netstring+: The cl-netstring+ package
Class, decoder-state: Internal classes
Condition, empty-header: Internal conditions
Condition, invalid-header-character: Internal conditions
Condition, netstring-parse-error: Internal conditions
Condition, too-much-data: Internal conditions

D
decoder-state: Internal classes

E
empty-header: Internal conditions

I
invalid-header-character: Internal conditions

N
netstring-parse-error: Internal conditions

P
Package, cl-netstring+: The cl-netstring+ package

S
System, cl-netstring+: The cl-netstring+ system

T
too-much-data: Internal conditions

Jump to:   C   D   E   I   N   P   S   T