Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jonathanstowe/messagepack-class

Serialize/Deserialize Raku classes to/from MessagePack blobs
https://github.com/jonathanstowe/messagepack-class

deserialization messagepack raku

Last synced: 25 days ago
JSON representation

Serialize/Deserialize Raku classes to/from MessagePack blobs

Awesome Lists containing this project

README 

        
# MessagePack::Class



Serialize/Deserialize Raku classes to/from MessagePack blobs



![Build Status](https://github.com/jonathanstowe/Tinky/workflows/CI/badge.svg)



## Synopsis



```raku



use MessagePack::Class;



class MyClass does MessagePack::Class {

	has Str $.some-data;

}



my Blob $pack = MyClass.new(some-data => "whatever").to-messagepack;



# Then send $pack over the network, write it to a file or something



my MyClass $obj = MyClass.from-messagepack($pack);



```



## Description



[MessagePack](http://msgpack.org/) is a binary serialization format that

is particularly efficient for transmission over a network or file storage.



This module provides a role that allows for the direct serialization of

a Raku object to a MessagePack binary blob and the deserialization of

that blob back to a Raku object of the same type with the same attribute

values.



Under the hood it uses [Data::MessagePack](https://github.com/pierre-vigier/Perl6-Data-MessagePack)

to serialize and deserialize data structures representing the object in a very

similar manner to [JSON::Marshal](https://github.com/jonathanstowe/JSON-Marshal) and

[JSON::Unmarshal](https://github.com/tadzik/JSON-Unmarshal) (infact it borrows some

of the internal code of both of those to construct a suitable data structure.)



For a simple case this may work with your class unchanged apart from the addition of

the role composition, however for types that may not be properly constructed from

their public attributes there are provided the attribute traits ```packed-by``` and

```unpacked-by``` which allow you to provide either a subroutine or a method name

that will work with a representation that will round-trip properly.



A named method supplied to ```packed-by``` will be called on the object to be serialized

without any arguments and should return a value suitable for serialization, and a method

supplied to ```unpacked-by``` will be called on the type object with the value to be

deserialized as a single positional argument and should return an object of the type.



So for instance if one had a class with an attribute of type Version one might do:



```

class TraitTest does MessagePack::Class {

    has Version $.version is packed-by('Str') is unpacked-by('new');

}

```



Where the ```Str``` method returns a string that is suitable to be passed to ```new```

to create a new Version  object.



If a subroutine (or other Callable object) is passed to the traits then it should take

a single argument and return a value suitable for serialization (for ```packed-by```) or

an object of the appropriate type (for ```unpacked-by```) so the above example might

become:



```

class TraitTest does MessagePack::Class {

    has Version $.version is packed-by(-> Version $v { $v.Str }) is unpacked-by(-> Str $v { Version.new($v)});

}

```



You can of course make the subroutines as complex as is required for your types.



If you need your data to be interoperable with software written in another language

you may need to adjust the serialization accordingly to match the types available

in that language.



## Installation



Assuming you have a working Rakudo installation the you should be able to install this with ```zef``` :



    zef install MessagePack::Class



    # or from a local check-out:



    zef install .



Though I can't see any reason this shouldn't work with any other installer that may come along in the future.



If it reports that is having trouble installing the dependency, you can do:



    zef install -v --debug https://github.com/pierre-vigier/Perl6-Data-MessagePack.git



## Support



If you find a problem with this module or have a suggestion please report at

https://github.com/jonathanstowe/MessagePack-Class/issues - though I always

prefer a pull request with tests if you can do that.



## Licence and Copyright



This is free software. Please see the [LICENCE](LICENCE) file in this repository.



© Jonathan Stowe 2017 - 2021