The darts.lib.message-pack Reference Manual

Table of Contents

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

The darts.lib.message-pack Reference Manual

This is the darts.lib.message-pack Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:40:10 2018 GMT+0.


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

1 Introduction

DartsCLMessagePack

This library implements a simple encoder/decoder for the MsgPack binary format (see http://msgpack.org/) All opcodes of the specification are supported.

Unlike cl-messagepack, this library does not use the Ext family of opcodes. Also, this library is on a slightly lower level compared to cl-messagepack. The advantage is, that this library refuses to guess the type of objects being encoded, and also allows the application to choose a suitable representation for the values read on a case-by-case basis.

Application Interface

Writing

Reading


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 darts.lib.message-pack

Maintainer

Dirk Esser

Author

Dirk Esser

License

MIT

Description

Implementation of the message pack exchange format

Long Description
Version

0.1

Dependencies
Source

darts.lib.message-pack.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 darts.lib.message-pack.asd

Location

darts.lib.message-pack.asd

Systems

darts.lib.message-pack (system)


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

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

Parent

darts.lib.message-pack (system)

Location

package.lisp

Packages

darts.lib.message-pack


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

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

Dependency

package.lisp (file)

Parent

darts.lib.message-pack (system)

Location

msgpack.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 darts.lib.message-pack

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

Source

package.lisp (file)

Use List
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 Functions

Function: protocol-error-stream OBJECT
Package

darts.lib.message-pack

Source

msgpack.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

Function: unencodable-object-error DATUM &optional REASON CONTROL &rest ARGUMENTS
Package

darts.lib.message-pack

Source

msgpack.lisp (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)


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

5.1.2 Generic functions

Generic Function: protocol-error-byte CONDITION
Package

darts.lib.message-pack

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

msgpack.lisp (file)

Generic Function: unencodable-object-error-datum CONDITION
Package

darts.lib.message-pack

Methods
Method: unencodable-object-error-datum (CONDITION unencodable-object-error)
Source

msgpack.lisp (file)

Generic Function: unencodable-object-error-message CONDITION
Package

darts.lib.message-pack

Methods
Method: unencodable-object-error-message (CONDITION unencodable-object-error)
Source

msgpack.lisp (file)

Generic Function: unencodable-object-error-reason CONDITION
Package

darts.lib.message-pack

Methods
Method: unencodable-object-error-reason (CONDITION unencodable-object-error)
Source

msgpack.lisp (file)


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

5.1.3 Conditions

Condition: invalid-tag-byte-error ()
Package

darts.lib.message-pack

Source

msgpack.lisp (file)

Direct superclasses
Direct methods

protocol-error-byte (method)

Direct slots
Slot: byte
Initargs

:value

Initform

(quote nil)

Readers

protocol-error-byte (generic function)

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

darts.lib.message-pack

Source

msgpack.lisp (file)

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 (file)

Direct superclasses

error (condition)

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 (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: datum
Initargs

:datum

Initform

(quote nil)

Readers

unencodable-object-error-datum (generic function)

Slot: reason
Initargs

:reason

Initform

(quote nil)

Readers

unencodable-object-error-reason (generic function)

Slot: message
Initargs

:message

Initform

(quote nil)

Readers

unencodable-object-error-message (generic function)


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

5.2 Internal definitions


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

5.2.1 Macros

Macro: define-encoder CONC-NAME (VALUE STREAM &rest ARGS) &body BODY
Package

darts.lib.message-pack

Source

msgpack.lisp (file)


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

5.2.2 Types

Type: octet ()
Package

darts.lib.message-pack

Source

msgpack.lisp (file)

Type: octet-buffer &optional LENGTH
Package

darts.lib.message-pack

Source

msgpack.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
darts.lib.message-pack.asd: The darts<dot>lib<dot>message-pack<dot>asd file
darts.lib.message-pack/msgpack.lisp: The darts<dot>lib<dot>message-pack/msgpack<dot>lisp file
darts.lib.message-pack/package.lisp: The darts<dot>lib<dot>message-pack/package<dot>lisp file

F
File, Lisp, darts.lib.message-pack.asd: The darts<dot>lib<dot>message-pack<dot>asd file
File, Lisp, darts.lib.message-pack/msgpack.lisp: The darts<dot>lib<dot>message-pack/msgpack<dot>lisp file
File, Lisp, darts.lib.message-pack/package.lisp: The darts<dot>lib<dot>message-pack/package<dot>lisp file

L
Lisp File, darts.lib.message-pack.asd: The darts<dot>lib<dot>message-pack<dot>asd file
Lisp File, darts.lib.message-pack/msgpack.lisp: The darts<dot>lib<dot>message-pack/msgpack<dot>lisp file
Lisp File, darts.lib.message-pack/package.lisp: The darts<dot>lib<dot>message-pack/package<dot>lisp file

Jump to:   D   F   L  

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

A.2 Functions

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

D
define-encoder: Internal macros

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

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

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

P
protocol-error-byte: Exported generic functions
protocol-error-byte: Exported generic functions
protocol-error-stream: Exported functions

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

U
unencodable-object-error: Exported functions
unencodable-object-error-datum: Exported generic functions
unencodable-object-error-datum: Exported generic functions
unencodable-object-error-message: Exported generic functions
unencodable-object-error-message: Exported generic functions
unencodable-object-error-reason: Exported generic functions
unencodable-object-error-reason: Exported generic functions

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

Jump to:   D   F   G   M   P   R   U   W  

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

A.3 Variables

Jump to:   B   D   M   R   S  
Index Entry  Section

B
byte: Exported conditions

D
datum: Exported conditions

M
message: Exported conditions

R
reason: Exported conditions

S
Slot, byte: Exported conditions
Slot, datum: Exported conditions
Slot, message: Exported conditions
Slot, reason: Exported conditions

Jump to:   B   D   M   R   S  

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

A.4 Data types

Jump to:   C   D   I   O   P   S   T   U  
Index Entry  Section

C
Condition, invalid-tag-byte-error: Exported conditions
Condition, premature-end-of-input-error: Exported conditions
Condition, protocol-error: Exported conditions
Condition, unencodable-object-error: Exported conditions

D
darts.lib.message-pack: The darts<dot>lib<dot>message-pack system
darts.lib.message-pack: The darts<dot>lib<dot>message-pack package

I
invalid-tag-byte-error: Exported conditions

O
octet: Internal types
octet-buffer: Internal types

P
Package, darts.lib.message-pack: The darts<dot>lib<dot>message-pack package
premature-end-of-input-error: Exported conditions
protocol-error: Exported conditions

S
System, darts.lib.message-pack: The darts<dot>lib<dot>message-pack system

T
Type, octet: Internal types
Type, octet-buffer: Internal types

U
unencodable-object-error: Exported conditions

Jump to:   C   D   I   O   P   S   T   U