NAME
Data::Bitfield - manage integers containing multiple bit fields
DESCRIPTION
This module provides a single primary function, bitfield, which creates
helper functions in the package that calls it, to assist in managing
integers that encode sets of bits, called bitfields. This may be useful
when interacting with a low-level networking protocol, binary file
format, hardware devices, or similar purposes.
bitfield
bitfield $name, %fields
Creates two new functions in the calling package whose names are
derived from the string $name passed here. These functions will be
symmetric opposites, which convert between a key/value list of field
values, and their packed integer or binary byte-string representation.
$packed_value = pack_$name( %field_values )
%field_values = unpack_$name( $packed_value )
These two functions will work to a set of field names that match those
field definitions given to the bitfield function that declared them.
Each field has a name and a definition. Its definition comes from one
of the following field-declaration functions.
Additional options may be passed by giving a HASH reference as the
first argument, before the structure name.
bitfield { %options }, $name, %fields
Recognised options are:
format => "bytes-LE" | "bytes-BE" | "integer"
Defines the format that the pack_NAME function will return and the
unpack_NAME function will expect to receive as input. The two bytes-*
formats describe a packed binary string in either little- or
big-endian direction, and integer describes an integer numerical
value.
Note that currently the bytes-* formats are limited to values 32bits
wide or smaller.
Optional; will default to integer if not supplied. This default may
change in a later version - make sure to always specify it for now.
unrecognised_ok => BOOL
If true, the pack_ function will not complain about unrecognised
field names; they will simply be ignored.
FIELD TYPES
boolfield
boolfield( $bitnum )
Declares a single bit-wide field at the given bit index, whose value is
a simple boolean truth.
intfield
intfield( $bitnum, $width )
Declares a field of $width bits wide, starting at the given bit index,
whose value is an integer. It will be shifted appropriately.
enumfield
enumfield( $bitnum, @values )
Declares a field some number of bits wide, sufficient to store an
integer big enough to act as an index into the list of values, starting
at the given bit index. Its value will be automatically converted to or
from one of the values given, which should act sensibly as strings for
comparison purposes. Holes can be placed in the range of supported
values by using undef.
constfield
constfield( $bitnum, $width, $value )
Declares a field some number of bits wide that stores a constant value.
This value will be packed automatically.
Unlike other field definitions, this field is not named. It returns a
2-element list directly for use in the bitfield list.
TODO
* More flexible error-handling - missing/extra values to pack_, extra
bits to unpack_.
* Allow truely-custom field handling, including code to support
discontiguous fields.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>