NAME
BeePack - Primitive MsgPack based key value storage
VERSION
version 0.200
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.
true
my $true = BeePack->true;Returns the MsgPack true boolean singleton (from Data::MessagePack), for building booleans inside arrays and hashes passed to "set". See "set_bool" to force a single key to a boolean directly.
false
my $false = BeePack->false;Returns the MsgPack false boolean singleton, the counterpart to "true".
filename
The path to the .bee file on disk. Required, and read-only after construction. Used both to read the existing file on open and, on "save", as the destination CDB_File renames the rebuilt file onto.
tempfile
The path CDB_File uses to build the new file before atomically renaming it onto "filename" on "save". Its presence -- not a separate flag -- is what switches the pack to read/write mode: give a tempfile (to "open" or new) and "readonly" defaults to false; leave it out and the pack opens read-only. A pack that is not readonly but has no tempfile is rejected at construction ("Read/Write opening requires tempfile").
nil_exists
BeePack->open('my.bee', undef, nil_exists => 1);Controls whether a key holding a nil (undef) value counts as existing. Defaults to false, so by default "exists" (and therefore "get") treats a nil-valued key exactly like an absent one. Set it to true to make "exists" return true for a key that is present in the pack regardless of whether its value happens to be nil.
readonly
Whether the pack refuses writes: every setter and "save" croak on a readonly pack instead of mutating it. Lazily derives to true when no "tempfile" was given and false when one was -- so the normal way to control this is by giving or withholding tempfile, not by setting readonly directly. It can still be passed explicitly to the constructor (for example, to open a pack with a tempfile but keep it read-only); passing it as false without a tempfile is rejected at construction instead.
open
my $beepack = BeePack->open($filename); # read-only
my $beepack = BeePack->open($filename, $tempfile); # read/write
my $beepack = BeePack->open($filename, undef, nil_exists=>1); # read-only, nil_existsConstructor helper: turns the positional $filename/$tempfile pair into the matching named constructor arguments and calls new. $tempfile may be undef to open read-only while still passing further %attr (such as nil_exists) through to new.
keys
my @keys = $beepack->keys;Returns the keys currently in the pack, in whatever order the underlying hash buffer yields them -- unlike "save", this does not sort.
set
$beepack->set( $key => $value );MsgPack-packs $value exactly as given (however Perl and Data::MessagePack currently see its type) and stores it in the in-memory buffer under $key, overwriting any existing value for that key. Nothing reaches disk until "save". Croaks on a "readonly" pack. Use "set_integer", "set_bool", "set_string" or "set_nil" instead when the MsgPack type must be pinned regardless of how the Perl scalar happens to be flagged.
set_type
$beepack->set_type( $key => $type => $value );Alternate setter that dispatches on the first character of $type -- the same single-letter scheme the bee command line uses (see "DESCRIPTION" in bee): i integer ("set_integer"), b bool ("set_bool"), s string ("set_string"), n nil ("set_nil"; $value is ignored), a array ("set" with $value dereferenced as an arrayref), h hash ("set" with $value dereferenced as a hashref), or an empty/undefined $type for a plain "set". A new type letter is a paired change: add the branch here and the matching branch in bee's command-line dispatch.
set_integer
$beepack->set_integer( $key => $value );Forces $value to a MsgPack integer (Perl's 0 + $value) and "set"s it, regardless of how $value is currently represented.
set_bool
$beepack->set_bool( $key => $value );Forces $value to a MsgPack boolean -- "true" if $value is true in Perl terms, "false" otherwise -- and "set"s it.
set_string
$beepack->set_string( $key => $value );Forces $value to a MsgPack string (Perl's "$value") and "set"s it, regardless of how $value is currently represented.
set_nil
$beepack->set_nil( $key );Sets $key to a MsgPack nil (undef). See "nil_exists" for how a nil-valued key interacts with "exists".
exists
my $bool = $beepack->exists( $key );Returns false when $key is not in the buffer at all. Otherwise, returns true unconditionally when "nil_exists" is set; when it is not, unpacks the value and returns true only if that value is defined -- so by default a nil-valued key is reported as not existing.
get
my $value = $beepack->get( $key );Returns undef when "exists" says $key doesn't exist (which, by default, includes a key whose stored value is nil -- see "nil_exists"); otherwise unpacks and returns the stored value.
get_raw
my $bytes = $beepack->get_raw( $key );Returns the raw MsgPack-encoded bytes stored for $key, unchanged -- no unpack and no "exists" check -- or undef if the key is absent from the buffer. Useful for passing an opaque value (such as a gzipped blob) straight through without paying for an unpack/repack round trip.
save
$beepack->save;Rebuilds the on-disk .bee file from the in-memory buffer: since CDB_File has no in-place update, this creates a fresh CDB_File at "filename" via "tempfile", inserts every buffered key in sorted order (so the on-disk file is deterministic regardless of hash iteration order, though not necessarily byte-identical across cdb implementations), and finishes it, which atomically renames the tempfile onto filename. The in-memory buffer remains the source of truth afterwards, so the pack stays usable for further "get"/"set" calls without reopening. Croaks on a "readonly" pack.
SEE ALSO
bee
CDB_File
Data::MessagePack
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/cindustries/p5-beepack/issues.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudss.us>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014-2026 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.