txt: ## dist_zef-jonathanstowe-MessagePack-Class.md
  # MessagePack::Class
  
  Serialize/Deserialize Raku classes to/from MessagePack blobs
  
  ![Build Status](https://github.com/jonathanstowe/Tinky/workflows/CI/badge.svg)
  
  ## Synopsis
  
  ```
  
  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> file in this repository.
  
  © Jonathan Stowe 2017 - 2021
  