Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/leapmotion/leapserial
The Leap Motion cross-format, cross-platform declarative serialization library
https://github.com/leapmotion/leapserial
Last synced: 2 days ago
JSON representation
The Leap Motion cross-format, cross-platform declarative serialization library
- Host: GitHub
- URL: https://github.com/leapmotion/leapserial
- Owner: leapmotion
- License: apache-2.0
- Created: 2015-07-20T12:33:36.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-04-12T19:33:36.000Z (over 6 years ago)
- Last Synced: 2024-04-14T22:44:20.385Z (7 months ago)
- Language: C++
- Homepage:
- Size: 1010 KB
- Stars: 17
- Watchers: 47
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Introduction to LeapSerial
===
LeapSerial is a cross-format, declarative, serialization and deserialization library written and maintained by Leap Motion. This library is built with CMake, and makes heavy use of C++11.
LeapSerial is mainly intended to provide users with a way to describe how their types should be serialized without being too concerned about the wire format serialization should take. Users should be able to directly annotate and serialize/deserialize their business objects rather than having to convert to and from DTOs generated by tools like `protoc`.
The following four output formats are currently supported:
* JSON
* Protobuf
* Flatbuffers
* LeapSerial Proprietary
LeapSerial also provides a simple stream concept, some wrapper classes, and a few standard implementations. These streams may be composed with one another similarly to how it's done with Protobuf streams.
* Wrapper for `std::istream` and `std::ostream`
* AES-256 encryption
* Zlib compression
* BZip2 compression
* Memory stream
Users may also write their own.
Quick Start
===
Here's how you mark the fields to be serialized:
```C++
#include
class MyClass {
int my_member;
static leap::descriptor GetDescriptor() {
return {
&MyClass::my_member
};
}
};
```
Serialization one-liner:
```C++
MyClass myClass;
std::stringstream os;
leap::Serialize(os, myClass);
```
Deserialization is also a one-liner:
```C++
std::shared_ptr a = leap::Deserialize(ss, myClass);
```
If your type doesn't use native pointers (either directly or transitively), you can also deserialize in-place.
```C++
MyClass b;
leap::Deserialize(ss, b);
```
Alternative Archivers
---
LeapSerial has a few output formats that are well supported. The `leap::Serialize` call, by default, will use the internal LeapSerial archiver, which formats data in a custom bitstream format. You can use other formats, though, such as Protobuf, but this requires that your fields are numbered or named. The following sections all use the following numbered and named data structure:
```C++
class MyProtobufObject {
public:
int a = 949;
std::string b = "Hello world!";
std::vector c {4, 5, 6};
static leap::descriptor GetDescriptor(void) {
return{
"MyProtobufObject",
{
{ 424, "a", &MyProtobufObject::a },
{ 425, "b", &MyProtobufObject::b },
{ 426, "c", &MyProtobufObject::c }
}
};
}
};
```
Protobuf
===
Protobuf serialization can be done with `OArchiveProtobuf`:
```C++
#include
#include
void Foo() {
MyProtobufObject myobj;
std::stringstream ss;
leap::Serialize(ss, defaultPerson);
}
```
The resulting object can be parsed by Protobuf, if you have a schema for `MyProtobufObject`. You can also create the corresponding `proto` file by serializing the descriptor, like this:
```C++
std::stringstream ss;
leap::Serialize(
ss,
MyProtobufObject::GetDescriptor()
);
```
This is what you get:
```Protobuf
message MyProtobufObject {
required sint32 a = 424;
optional string b = 425;
repeated sint32 c = 426;
}
```
Right now, `leap::protobuf_v1` and `leap::protobuf_v2` are supported to ensure the generated `proto` file can be parsed by your chosen version of `protoc`.
JSON
===
JSON serialization is also supported. The protov3 specification's JSON mapping is used wherever possible. Currently, deserialization is not supported, but there is a `leap::IArchiveJSON` type which will provide deserialization once it's implemented.
```C++
#include
void Foo() {
MyProtobufObject obj;
std::stringstream ss;
leap::Serialize(ss, obj);
}
```
Here's the resulting JSON:
```Json
{
"a": 949,
"b": "Hello world!",
"c": [ 4, 5, 6 ]
}
```
Alternative Streams
===
You can also serialize to a memory buffer, if you don't like `std::stringstream`:
```C++
leap::MemoryStream ms;
MyClass b;
leap::Serialize(ms, b);
// In case you want to do something with the data
std::vector& data = ms.GetDatadata();
// Or you can just round trip right from here
std::shared_ptr c = leap::Deserialize(ms);
```
Maybe you have a buffer already that you want to deserialize
```C++
char buf[1024];
FillMyBuffer(buf, 1024);
leap::BufferedStream bs{buf, sizeof(buf), sizeof(buf)};
std::shared_ptr mc = leap::Deserialize(bs);
```
Encryption and compression are supported, too. Encrypting and compressing streams are declared as a filter. Protobuf's zero copy streams are similarly implemented. Here's how you might encrypt a file directly to disk with an `std::ofstream`. Make sure you fill `key` with a cryptographic function or you might be vulnerable to a related key attack.
```C++
std::array myKey;
std::ofstream of("myfile.dat");
leap::OutputStreamAdapter osa(of);
leap::CompressionStream cs { osa };
leap::AESEncryptionStream ecs { cs, myKey };
MyObject obj;
leap::Serialize(ecs, obj);
```
If you use encryption and compression, make sure the compression step happens before the encryption step, otherwise you will wind up making the file size larger.