https://github.com/planetis-m/bingo

Binary serialization framework for Nim
https://github.com/planetis-m/bingo

binary deserialization macro marshal marshalling savedata serialization serialization-framework unmarshalling

Last synced: about 2 months ago
JSON representation

Binary serialization framework for Nim

• Host: GitHub
• URL: https://github.com/planetis-m/bingo
• Owner: planetis-m
• License: other
• Created: 2020-12-03T15:26:06.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2024-04-05T12:26:16.000Z (6 months ago)
• Last Synced: 2024-05-18T15:38:53.757Z (4 months ago)
• Topics: binary, deserialization, macro, marshal, marshalling, savedata, serialization, serialization-framework, unmarshalling
• Language: Nim
• Homepage:
• Size: 34.2 KB
• Stars: 20
• Watchers: 4
• Forks: 1
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-nim - bingo - Binary serialization framework for Nim. (Data / Serialization)

README

        
# bingo — Binary serialization framework for Nim

## About

This package provides the ``binTo``, ``loadBin`` procs which deserialize the specified

type from a ``Stream``. The `storeBin` procs are used to write the binary

representation of a location into a `Stream`. Low level `initFromBin` and `storeBin`

procs can be overloaded, in order to support arbitary container types, i.e.

[marshal_smartptrs.nim](bingo/marshal_smartptrs.nim).

## Usage

```nim

import std/streams, bingo

type

  Foo = ref object

    value: int

    next: Foo

let d = Foo(value: 1, next: Foo(value: 2, next: nil))

let s = newStringStream()

# Make a roundtrip

s.storeBin(d) # writes binary from a location

s.setPosition(0)

let a = s.binTo(Foo) # reads binary and transform to a type

# Alternatively load directly into a location

s.setPosition(0)

var b: Foo

s.loadBin(b)

```

## Features

- Serializing and deserializing directly into `Streams`. For common usage it is done automatically.

  Generally speaking intervation is needed when working with `ptr` types.

- Supports `options`, `sets` and `tables` by default.

- Overloading serialization procs.

## Limitations

- Limited support of object variants. The discriminant field is expected first.

  Also there can be no fields before and after the case section.

- Borrowing proc `initFromBin[T](dst: var T; s: Stream)` for distinct types isn't

  currently working. Blocked by a Nim bug. Use overloads for now. Or you can easily

  override this behaviour by copying these lines in your project:

  ```nim

  from typetraits import distinctBase

  proc storeBin[T: distinct](s: Stream; x: T) = storeToBin(s, x.distinctBase)

  proc initFromBin[T: distinct](dst: var T; s: Stream) = initFromBin(dst.distinctBase, p)

  ```

- Custom pragmas are not supported. Unless `hasCustomPragma` improves, this feature won't be added.

  You can currently substitute skipped fields by creating empty overloads.