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