NAME

BeePack - Primitive MsgPack based key value storage

VERSION

version 0.103

SYNOPSIS

  use BeePack;

  # read only opening, error if fail
  my $beepack_ro = BeePack->open('my.bee');
  # read/write opening (with temp file), create if missing
  my $beepack_rw = BeePack->open('my.bee', 'my.bee.'.$$);
  # read only opening with nil_exists set
  my $beepack_ro = BeePack->open('my.bee', undef, nil_exists => 1 );

  $beepack_rw->set( key => $value ); # overwrite value

  $beepack_rw->set_integer( key => $value );   # force integer
  $beepack_rw->set_type( key => i => $value ); # alternative way
  $beepack_rw->set_bool( key => $value );      # force bool
  $beepack_rw->set_type( key => b => $value ); # alternative way
  $beepack_rw->set_string( key => $value );    # force stringification
  $beepack_rw->set_type( key => s => $value ); # alternative way
  $beepack_rw->set_nil( 'key' );       # set nil value
  $beepack_rw->set_type( key => 'n' ); # alternative way

  # array of 2 true bool
  $beepack_rw->set( key => [
    BeePack->true, BeePack->true,
  ]);

  # hash with true and false bool
  $beepack_rw->set( key => {
    false => BeePack->false,
    true => BeePack->true,
  });

  $beepack_rw->save; # save changes and reopen

  my $value = $beepack_ro->get('key');

  # getting the raw msgpack bytes
  my $msgpack = $beepack_ro->get_raw('key');

DESCRIPTION

BeePack is made out of the requirement to encapsule small key values and giant binary blobs into a compact file format for exchange and easy update even with the low amount of microcontroller memory.

Technical BeePack is CDB with additionally using MsgPack for storing the values inside the CDB. We picked MsgPack for the inner storage, to not reinvent the wheel of storing interoperational values (like BeePack generated on a Linux machine with x86 while being read by a microcontroller with ARM).

For simplification we do NOT store several values for a key inside the CDB, which is a capability of CDB. By default BeePack is saying a key that has a nil value doesn't exist. You can deactivate this behaviour by setting the nil_exists attribute to 1 on open.

We also simplify the implementation of MsgPack inside the BeePack with not allowing specific types in there. Because of the usage of Data::MessagePack this implementation will still flawless read them, while all types we are excluding are also those you can't get out of Data::MessagePack, so the Perl implementation is anyway not capable of adding them to the BeePack. The C implementation will be getting strict on this.

This distribution includes bee, which is a little tool to read, generate and manipulate BeePack from the comandline.

SEE ALSO

bee

CDB::TinyCDB

Data::MessagePack

SUPPORT

IRC

  Join #hardware on irc.perl.org. Highlight Getty for fast reaction :).

Repository

  http://github.com/cindustries/perl-beepack
  Pull request and additional contributors are welcome

Issue Tracker

  http://github.com/cindustries/perl-beepack/issues

AUTHOR

Torsten Raudssus <torsten@raudss.us>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.