README

msgpack - A pure Tcl implementation of the MessagePack object serialization library
Generated from file 'msgpack.man' by tcllib/doctools with format 'text'
msgpack(n) 2.0.0  "A pure Tcl implementation of the MessagePack object serialization library"

NAME
====

msgpack - msgpack Package Reference

SYNOPSIS
========

package require Tcl 8.6
package require msgpack ?2.0.0?

msgpack::packer new
packerObject data
packerObject destroy
packerObject pack args
packerObject reset
msgpack::unpacker new
unpackerObject destroy
unpackerObject set_ext_unpacker ?type? ?script?
unpackerObject unpack_stream istream callback
unpackerObject unpack_string istring ?callback?
msgpack array2list 
msgpack map2array 
msgpack map2dict 
msgpack pack args
msgpack unpack string

DESCRIPTION
===========

The _msgpack_ package is a pure Tcl implementation of the MessagePack object
serialization library. You can find the code at GitHub:
<URL:https://github.com/jdc8/msgpack>. MessagePack can be found at
<URL:http://msgpack.org/>.

Use this documentation in combination with the MessagePack documentation for
more details.

Packer class
============

    msgpack::packer new

        _oo::class_ <URL:http://www.tcl.tk/man/tcl8.6/TclCmd/class.htm>
        implementing the MessagePack packing.

    packerObject data

        Return the packed data.

    packerObject destroy

        Destroy the packer object.

    packerObject pack args

        Pack the specified value and store it internally. More information on
        how to specify values to be packed can be found in section -> Pack
        options. To get the packed data, use the data method.

    packerObject reset

        Reset the packer.

Unpacker class
==============

    msgpack::unpacker new

        _oo::class_ <URL:http://www.tcl.tk/man/tcl8.6/TclCmd/class.htm>
        implementing the MessagePack unpacking.

    unpackerObject destroy

        Destroy the unpacker object.

    unpackerObject set_ext_unpacker ?type? ?script?

        Set the handler for an extension type. When the unpacker encounters
        extension type type, it will call script with the type and the data as
        its arguments. Omit script or script and type to get handlers. Set the
        handler for a type to an empty string to disable it.

    unpackerObject unpack_stream istream callback

        Unpack data read from the istream argument. The callback command is
        called when a MessagePack object is unpacked. Before calling the
        callback command, the word _data_ and the unpacked MessagePack object is
        _lappend_-ed to the command. When the stream is closed (_eof_ detected),
        the callback command is called with the word _eof_ and the stream handle
        _lappend_-ed.

        The istream is configure like this:

        *   Non blocking

        *   Unbuffered

        *   Translation _binary_

        *   Encoding _binary_

        Opening and closing the istream is the responsability of the script
        calling the unpack_stream method.

    unpackerObject unpack_string istring ?callback?

        Unpack the specified data. If no callback command is specified, a list
        with unpacked type (see below) and value pairs is returned. If a
        callback command is specified, this command is called when a MessagePack
        object is unpacked. Before calling the callback command, the word _data_
        and the unpacked MessagePack object is _lappend_-ed to the command.

Type information found in the unpacked MessagePack objects can be one of the
following:

    array

    bin

    boolean

    ext

    float32

    float64

    integer

    map

    nil

    str

    timestamp

Values can be nested type/value list.

Utilities
=========

    msgpack array2list

        Convert a MessagePack array as retuned by the unpack command or method
        into a Tcl list.

    msgpack map2array

        Convert a MessagePack map as retuned by the unpack command or method
        into a Tcl array.

    msgpack map2dict

        Convert a MessagePack map as retuned by the unpack command or method
        into a Tcl dict.

    msgpack pack args

        Pack the specified value. The packed value is returned. More information
        on how to specify values to be packed can be found in section -> Pack
        options.

    msgpack unpack string

        Unpack the specified data. A list with unpacked type (see -> Unpacker
        class) and value pairs is returned.

Pack options
============

The arguments for the pack command or method are always one or more type
specifiers and if needed a value. The list below shows the supported types:

    array size

        Add array size to packed data. Must be followed by size calls to method
        pack to add the array elements to the packed data.

    bin bytes

        Add a byte array (a binary string) to the packed data.

    boolean data

        Add a boolean to the packed data. Is equivalent calling methods pack
        true or pack false.

    dict keyType valueType dictionaryValue

        Add a dict to the packed data. This is equivalent to calling method pack
        map with the dict size as argument, followed by calling method pack
        keyType and method pack valueType for each key/value pair in the dict.

    ext type bytes

        Add a byte array of a chosen extension type to the packed data.

    false

        Add a boolean with value false to the packed data.

    fix_ext1 type byte

        Add 1 byte of a chosen extension type to the packed data.

    fix_ext2 type bytes

        Add 2 bytes of a chosen extension type to the packed data.

    fix_ext4 type bytes

        Add 4 bytes of a chosen extension type to the packed data.

    fix_ext8 type bytes

        Add 8 bytes of a chosen extension type to the packed data.

    fix_ext16 type bytes

        Add 16 bytes of a chosen extension type to the packed data.

    fix_int8 data

        Add an 8 bit integer to the packed data.

    fix_int16 data

        Add a 16 bit integer to the packed data.

    fix_int32 data

        Add a 32 bit integer to the packed data.

    fix_int64 data

        Add a 64 bit integer to the packed data.

    fix_uint8 data

        Add an 8 bit unsigned integer to the packed data.

    fix_uint16 data

        Add a 16 bit unsigned integer to the packed data.

    fix_uint32 data

        Add a 32 bit unsigned integer to the packed data.

    fix_uint64 data

        Add a 64 bit unsigned integer to the packed data.

    float32 data

        Add a 32-bit float to the packed data.

    float64 data

        Add a 64-bit (double precision) float to the packed data.

    int data

        Add an integer to the packed data, let the packer choose the best
        packing.

    int8 data

        Add an 8 bit integer to the packed data, let the packer choose the best
        packing.

    int16 data

        Add a 16 bit integer to the packed data, let the packer choose the best
        packing.

    int32 data

        Add a 32 bit integer to the packed data, let the packer choose the best
        packing.

    int64 data

        Add a 64 bit integer to the packed data, let the packer choose the best
        packing.

    list elemenType list

        Add a Tcl list to the packed data. This is equivalent to calling method
        pack array with the list length as argument followed by calls to method
        pack elementType for each list element.

    long data

        Add a long integer to the packed data.

    long_long data

        Add a long long integer to the packed data.

    map size

        Add the map size to the packed data. Must be followed by size pairs of
        calls to method pack to add the keys and values to the packed data.

    microseconds micros

        Add a microsecond timestamp to the packed data as a timestamp96.

    milliseconds millis

        Add a millisecond timestamp to the packed data as a timestamp96.

    nil

        Add a nil to the packed data.

    short data

        Add a short integer to the packed data.

    str string

        Add a string to the packed data.

    tcl_array keyType valueType arrayName

        Add a Tcl array to the packed data. This is equivalent to calling method
        pack map with the array size as argument, followed by calling method
        pack keyType and method pack valueType for each key/value pair in the
        array.

    timestamp32 seconds

        Add a 32-bit unsigned timestamp to the packed data.

    timestamp64 seconds nanoseconds

        Add a 64-bit timestamp (34 bits for seconds, 30 bits for nanoseconds,
        both unsigned) to the packed data. Nanoseconds must not exceed
        999999999.

    timestamp96 seconds nanoseconds

        Add a 96-bit timestamp (64 bits for seconds, signed, and 32 bits for
        nanoseconds, unsigned) to the packed data. Nanoseconds must not exceed
        999999999.

    true

        Add a boolean with value true to the packed data.

    uint8 data

        Add an 8 bit unsigned integer to the packed data, let the packer choose
        the best packing.

    uint16 data

        Add a 16 bit unsigned integer to the packed data, let the packer choose
        the best packing.

    uint32 data

        Add a 32 bit unsigned integer to the packed data, let the packer choose
        the best packing.

    uint64 data

        Add a 64 bit unsigned integer to the packed data, let the packer choose
        the best packing.

    unsigned_int data

        Add an unsigned integer to the packed data.

    unsigned_long data

        Add a unsigned long integer to the packed data.

    unsigned_long_long data

        Add an unsigned long long integer to the packed data.

    unsigned_short data

        Add an unsigned short integer to the packed data.

Examples
========

Creating a *msgpack::packer* object and packing some data:

| package require msgpack

| set p [msgpack::packer new]

| $p pack int 123456789
| $p pack str "A MessagePack example"
| $p pack dict int str {1 one 2 two}
| set packed_data [$p data]
| $p destroy

Now unpack the packed data using a *msgpack::packer* object:

| package require msgpack

| set u [msgpack::unpacker new]
| $u unpack_string $packed_data

| $u destroy

After unpacking, the following list of type/value pairs is returned by the
unpack_string method:

| {integer 123456789} {str {A MessagePack example}} {map {{integer 1} {str one} {integer 2} {str two}}}

The same example using the pack utility function for packing the data:

| set packed_data ""
| append packed_data [msgpack pack int 0xFFFFFFFF]
| append packed_data [msgpack pack bin "A Utility example"]
| append packed_data [msgpack pack dict int str {3 three 4 four}]

An using the unpack utility function to unpack the data:

| puts [msgpack unpack $packed_data]

After unpacking, the following list of type/value pairs is returned by the
unpack utility function:

| {integer 4294967295} {bin {A Utility example}} {map {{integer 3} {str three} {integer 4} {str four}}}

With set_ext_unpacker you can register a handler to unpack custom extension
types.

| set up [msgpack::unpacker new]

| proc xor {n type data} {
|     set res {}
|     foreach b [split $data {}] {
|         set code [scan $b %c]
|         append res [format %c [expr { $code ^ $n }]]
|     }

|     return [list encrypted $res]
| }

| $up set_ext_unpacker 100 {xor 5}
| # Prints "{encrypted Hello!}".
| puts [$up unpack_string [msgpack pack ext 100 M`iij$]]
| $up destroy

Bugs, ideas, feedback
=====================

This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such at the _Github tracker_
<URL:https://github.com/jdc8/msgpack/issues>. Please also report any ideas for
enhancements you may have for either package and/or documentation.

License
=======

The code is released under the BSD license (specifically Modified BSD aka New
BSD aka 3-clause BSD). Check COPYING.BSD for more info about the license.

KEYWORDS
========

MessagePack, msgpack, serialization

CATEGORY
========

Serialization

COPYRIGHT
=========

Copyright (c) 2013 Jos Decoster <jos.decoster@gmail.com>
Copyright (c) 2020 D. Bohdan <https://dbohdan.com/>