The darts.lib.message-pack Reference Manual

This is the darts.lib.message-pack Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:56:57 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 darts.lib.message-pack

Implementation of the message pack exchange format

Maintainer

Dirk Esser

Author

Dirk Esser

License

MIT

Long Description
Version

0.1

Dependencies
  • ieee-floats (system).
  • babel (system).
Source

darts.lib.message-pack.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 darts.lib.message-pack/darts.lib.message-pack.asd

Source

darts.lib.message-pack.asd.

Parent Component

darts.lib.message-pack (system).

ASDF Systems

darts.lib.message-pack.


3.1.2 darts.lib.message-pack/package.lisp

Source

darts.lib.message-pack.asd.

Parent Component

darts.lib.message-pack (system).

Packages

darts.lib.message-pack.


3.1.3 darts.lib.message-pack/msgpack.lisp

Dependency

package.lisp (file).

Source

darts.lib.message-pack.asd.

Parent Component

darts.lib.message-pack (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 darts.lib.message-pack

A simple implementation of the message pack binary data encoding format. All value families are supported.

Source

package.lisp.

Use List
  • babel.
  • common-lisp.
  • ieee-floats.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: protocol-error-stream (object)
Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: read-packed-octet-array-data (length stream)

The function reads the next ‘length’ bytes from ‘stream’ and
returns the result as an ‘(array octet (length))’. It makes sure,
that all required data is available, and signals a ‘premature-end-of-input-error’, if the end of the stream is reached before all data could be read.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: read-packed-string-data (length stream &key encoding)

Reads the next ‘length’ bytes from ‘stream’, and decodes it into a proper string, assuming, that the data was encoded using the given ‘encoding’ (which defaults to ‘*default-character-encoding*’). The length of the string returned by this function depends on the encoding and the actual string data.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: read-packed-value (stream &key map-reader array-reader extension-reader accept-eof default encoding)

Reads the next available value from ‘stream’, and returns two value, namely ‘object’ and ‘type’, where ‘object’ is the value read, and ‘type’ is a symbol indicating the value family of ‘object’ (so that the caller can distiguish between ‘null’ and ‘boolean’, for example).

Strings are assumed to be encoded using ‘encoding’, which defaults to the value of ‘*default-character-encoding*’.

The value of ‘map-reader’ determines, how map objects are read. Possible values are:

- ‘:alist’ (read maps as association lists, this is the default)
- ‘:plist’ (read maps as property lists)
- ‘:hash’ (read maps as hash tables with test ‘equal’)
- a function (lambda (length stream) ...), which is called in order to decode the actual map contents.

The value of ‘array-reader’ determines, how general arrays are read. Possible values are:

- ‘:vector’ (read into a newly allocated simple vector, default)
- ‘:list’ (read into a list)
- a function (lambda (length stream) ...), which is called in order to decode the actual array contents.

The value of ‘extension-reader’ determines, how extension records are read. Possible values are:

- ‘:buffer’ (read the data into a byte array, and yield a pair of type tag and the buffered data; this is the default)
- a function (lambda (type length stream) ...), which is called in order to decode the actual record contents.

If ‘accept-eof’, the function explicitly checks for EOF before the first read operation, and if the end of ‘stream’ has indeed been reached, it returns the values ‘default’ as ‘object’ and nil as ‘type’. Note, that this applies only to the first read operation; subsequent read operations (if they are necessary), will not be guarded this way.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: read-packed-value-or-header (stream)

Reads the next available value from ‘stream’. This function returns three values: ‘data’, ‘type’, ‘info’.

The value of ‘type’ is always a symbol, which represents the type
of object. It may be one of:

- nil, if the end of the input stream has been reached; ‘data’ is nil in this case, and ‘info’ is nil, too.

- :integer, if the value read was an integer number; ‘data’ is the numeric value, and ‘info’ is nil in this case.

- :number, if the value read was a floating point number; ‘data’ is the numeric value in this case, and ‘info’ is nil.

- :boolean, if the value read was a boolean value; ‘data’ is the actual truth value (t or nil), and ‘info’ is nil in this case.

- :null, if the null value marker has been read; ‘data’ is nil in this case, and so is ‘info’.

- :string-header, if the beginning of a string was detected. The value of ‘data’ is the length in bytes of the encoded string, and ‘info’ is nil. The caller is responsible for extracting the actual contents of the string from ‘stream’.

- :map-header, if the beginning of a map was detected. The value of ‘data’ is the length of the map (i.e., the number of key/value pairs). The value of ‘info’ is nil. The caller is responsible for extracting the actual contents of the map from ‘stream’.

- :array-header, if the beginning of a general array was detected; the value of ‘data’ is the length of the array (i.e., the number of elements). The value of ‘info’ is nil. The caller is responsible for extracting the contents from ‘stream’.

- :octet-array-header, if the beginning of a byte array was detected; the value of ‘data’ is the length of the array (i.e., the number of bytes). The value of ‘info’ is nil. The caller is responsible for extracting the contents from ‘stream’.

- :extension-header, if the beginning of an extension record was detected; the value of ‘data’ is the length (in bytes) of the record, and ‘info’ is the type tag (a small integer).

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: unencodable-object-error (datum &optional reason control &rest arguments)
Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-array-header (length stream)

Encodes the start of a general array of the given ‘length’ and writes
the result into ‘stream’. The caller is responsible for writing the actual data immediately after the header written by this function.

This function returns ‘length’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-boolean (value stream)

Encodes ‘value’ as a boolean value, writing the result into ‘stream’. This function returns ‘value’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-double-float (value stream)

Encodes the floating point number ‘value’ as IEEE 745 double-precision (64 bit) number, and writes the result into ‘stream’. It returns ‘value’. Note, that if a conversion of ‘value’ is necessary, this encoder may lose information.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-extension-header (type length stream)

Encodes the start of an extension section with a payload size of ‘length’ and a type tag value of ‘type’, and writes the result into ‘stream’. The caller is responsible for writing the actual data immediately after the header written by this function.

This function returns ‘type’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-integer (value stream)

Encodes the integer number ‘value’ and writes the result into ‘stream’. Note, that ‘value’ must either be of type ‘(signed-byte 64)’ or ‘(unsigned-byte 64)’; this is a restriction of the message pack protocol. The function returns ‘value’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-map-header (length stream)

Encodes the start of a map containing ‘length’ pairs and writes
the result into ‘stream’. The caller is responsible for writing the actual data immediately after the header written by this function.

This function returns ‘length’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-null (stream)

Writes a placeholder value representing ‘null’ into the given ‘stream’. This function returns nil.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-octet-array (value stream &key start end)

Encodes the array of bytes ‘value’, and writes the result into the given ‘stream’.

If ‘start’ is supplied, it represents the index of the first element in ‘value’, which should be included in the result (defaults to 0). If ‘end’ is supplied, it represents the end of the portion of ‘value’ to encode; if omitted or nil, it defaults to the length of ‘value’.

This function returns ‘value’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-octet-array-header (length stream)

Encodes the start of an array of bytes of the given ‘length’ and writes the result into ‘stream’. The caller is responsible for writing the actual data immediately after the header written by this function.

This function returns ‘length’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-single-float (value stream)

Encodes the floating point number ‘value’ as IEEE 745 single-precision (32 bit) number, and writes the result into ‘stream’. It returns ‘value’. Note, that if a conversion of ‘value’ is necessary, this encoder may lose information.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Function: write-packed-string (value stream &key start end encoding)

Encodes the string ‘value’ and writes the result into ‘stream’. The characters are transformed into bytes using the given ‘encoding’, which defaults to the value of ‘*default-character-encoding*’.

If ‘start’ is supplied, it represents the index of the first character in ‘value’, which should be included in the result (defaults to 0). If ‘end’ is supplied, it represents the end of the portion of ‘value’ to encode; if omitted or nil, it defaults to the length of ‘value’.

This function returns ‘value’.

Package

darts.lib.message-pack.

Source

msgpack.lisp.


5.1.2 Generic functions

Generic Reader: protocol-error-byte (condition)
Package

darts.lib.message-pack.

Methods
Reader Method: protocol-error-byte ((condition invalid-tag-byte-error))
Source

msgpack.lisp.

Target Slot

byte.

Generic Reader: unencodable-object-error-datum (condition)
Package

darts.lib.message-pack.

Methods
Reader Method: unencodable-object-error-datum ((condition unencodable-object-error))
Source

msgpack.lisp.

Target Slot

datum.

Generic Reader: unencodable-object-error-message (condition)
Package

darts.lib.message-pack.

Methods
Reader Method: unencodable-object-error-message ((condition unencodable-object-error))
Source

msgpack.lisp.

Target Slot

message.

Generic Reader: unencodable-object-error-reason (condition)
Package

darts.lib.message-pack.

Methods
Reader Method: unencodable-object-error-reason ((condition unencodable-object-error))
Source

msgpack.lisp.

Target Slot

reason.


5.1.3 Conditions

Condition: invalid-tag-byte-error
Package

darts.lib.message-pack.

Source

msgpack.lisp.

Direct superclasses
Direct methods

protocol-error-byte.

Direct slots
Slot: byte
Package

common-lisp.

Initform

(quote nil)

Initargs

:value

Readers

protocol-error-byte.

Writers

This slot is read-only.

Condition: premature-end-of-input-error
Package

darts.lib.message-pack.

Source

msgpack.lisp.

Direct superclasses
Condition: protocol-error

Base class for conditions related to violations of the message pack protocol.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Direct superclasses

error.

Direct subclasses
Condition: unencodable-object-error

A condition of this type is signalled, if a given value cannot be encoded in the msgpack format.

Package

darts.lib.message-pack.

Source

msgpack.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: datum
Initform

(quote nil)

Initargs

:datum

Readers

unencodable-object-error-datum.

Writers

This slot is read-only.

Slot: reason
Initform

(quote nil)

Initargs

:reason

Readers

unencodable-object-error-reason.

Writers

This slot is read-only.

Slot: message
Initform

(quote nil)

Initargs

:message

Readers

unencodable-object-error-message.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Macros

Macro: define-encoder (conc-name (value stream &rest args) &body body)
Package

darts.lib.message-pack.

Source

msgpack.lisp.


5.2.2 Types

Type: octet ()
Package

darts.lib.message-pack.

Source

msgpack.lisp.

Type: octet-buffer (&optional length)
Package

darts.lib.message-pack.

Source

msgpack.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   D   F   G   M   P   R   U   W  
Index Entry  Section

D
define-encoder: Private macros

F
Function, protocol-error-stream: Public ordinary functions
Function, read-packed-octet-array-data: Public ordinary functions
Function, read-packed-string-data: Public ordinary functions
Function, read-packed-value: Public ordinary functions
Function, read-packed-value-or-header: Public ordinary functions
Function, unencodable-object-error: Public ordinary functions
Function, write-packed-array-header: Public ordinary functions
Function, write-packed-boolean: Public ordinary functions
Function, write-packed-double-float: Public ordinary functions
Function, write-packed-extension-header: Public ordinary functions
Function, write-packed-integer: Public ordinary functions
Function, write-packed-map-header: Public ordinary functions
Function, write-packed-null: Public ordinary functions
Function, write-packed-octet-array: Public ordinary functions
Function, write-packed-octet-array-header: Public ordinary functions
Function, write-packed-single-float: Public ordinary functions
Function, write-packed-string: Public ordinary functions

G
Generic Function, protocol-error-byte: Public generic functions
Generic Function, unencodable-object-error-datum: Public generic functions
Generic Function, unencodable-object-error-message: Public generic functions
Generic Function, unencodable-object-error-reason: Public generic functions

M
Macro, define-encoder: Private macros
Method, protocol-error-byte: Public generic functions
Method, unencodable-object-error-datum: Public generic functions
Method, unencodable-object-error-message: Public generic functions
Method, unencodable-object-error-reason: Public generic functions

P
protocol-error-byte: Public generic functions
protocol-error-byte: Public generic functions
protocol-error-stream: Public ordinary functions

R
read-packed-octet-array-data: Public ordinary functions
read-packed-string-data: Public ordinary functions
read-packed-value: Public ordinary functions
read-packed-value-or-header: Public ordinary functions

U
unencodable-object-error: Public ordinary functions
unencodable-object-error-datum: Public generic functions
unencodable-object-error-datum: Public generic functions
unencodable-object-error-message: Public generic functions
unencodable-object-error-message: Public generic functions
unencodable-object-error-reason: Public generic functions
unencodable-object-error-reason: Public generic functions

W
write-packed-array-header: Public ordinary functions
write-packed-boolean: Public ordinary functions
write-packed-double-float: Public ordinary functions
write-packed-extension-header: Public ordinary functions
write-packed-integer: Public ordinary functions
write-packed-map-header: Public ordinary functions
write-packed-null: Public ordinary functions
write-packed-octet-array: Public ordinary functions
write-packed-octet-array-header: Public ordinary functions
write-packed-single-float: Public ordinary functions
write-packed-string: Public ordinary functions


A.3 Variables