NAME

       Data::BitMask - bitmask manipulation

SYNOPSIS

         use Data::BitMask;

         my $FileMask = Data::BitMask->new(
             READ =>    1,
             WRITE =>   2,
             EXECUTE => 4,
             RX =>      5,
             RWX =>     7,
             FULL =>    7,
           );

         my $mask = $FileMask->build_mask('READ|WRITE');
         print Data::Dumper->Dump([
             $FileMask->explain_mask($mask),
             $FileMask->break_mask($mask)
           ]);

         my $mask2 = $FileMask->build_mask({FULL => 1, WRITE => 0});

DESCRIPTION

       This module allows one to create bitmask manipulator objects that can be used to create
       bitmask values based on a list of constants, as well as to break apart masks using those
       constants.  The advantages are that you don't have to pollute namespaces to use constants,
       you can ensure that only appropriate constants are used for specific masks, you can easily
       break apart and explain masks, and in general it is much easier for the user to interact
       with masks.

       The module only interacts with masks that fit in Perl integers.  In some places, it
       presumes that you are using 32 bit integers (i.e. canonicalizing negative values).

       The module expends a modest amount of overhead in creating the "Data::BitMask" object so
       as to speed up future mask manipulations.

   Installation instructions
       This module requires "Module::Build 0.24" to use the automated installation procedures.
       With "Module::Build" installed:

         Build.PL
         perl build test
         perl build install

       It can also be installed manually by copying "lib/Data/Bitmask.pm" to
       "perl/site/lib/Data/Bitmask.pm".

Suggest Module Implementation

       Here is one suggested approach to using bitmask manipulators in a module.

         {
         my $cache;
         sub SECURITY_INFORMATION {
           $cache ||= Data::BitMask->new(
               OWNER_SECURITY_INFORMATION => 0x1,
               GROUP_SECURITY_INFORMATION => 0x2,
               DACL_SECURITY_INFORMATION  => 0x4,
               SACL_SECURITY_INFORMATION  => 0x8,
             );
         }
         }

       The bitmask manipulator can then be accessed as:

         &SECURITY_INFORMATION->build_mask('DACL_SECURITY_INFORMATION');

       Or, if you are outside of the module, as:

         &Win32::Security::SECURITY_INFORMATION->build_mask('DACL_SECURITY_INFORMATION');

       This has several advantages:

       •   Demand creation of the "Data::Bitmask" object.  Creating objects with huge numbers of
           constants (i.e. hundreds or thousands) can be a bit time consuming, so this delays
           creation until the object actually gets used.  At the same time, the created object is
           cached.

       •   Easy access from within in the module, reasonably easy access from outside the module.

       •   If the user wants even easier access from outside the module, you can support Exporter
           and let the sub be exported.

Method Reference

   new
       Creates a new bitmask manipulator.  Pass a list of constant and value pairs. The constants
       do not have to be disjoint, but order does matter.  When executing "explain_mask" or
       "explain_const", constants that are earlier in the list take precedence over those later
       in the list.  Constant names are not allowed to have space or pipes in them, and constant
       values have to be integers. Constant names are case insensitive but preserving.

       If the passed value for the constant name is an anonymous array, then it is presumed that
       the name is the first value and that the remainder consists of name-value pairs of
       parameters.  The only currently supported parameter is "full_match", which implies that
       the constant should only be returned from "break_mask" or "explain_mask" if it perfectly
       matches the mask being explained.  For example:

             [qw(FILES_ONLY_NO_INHERIT full_match 1)] =>    1,

   add_constants
       Adds constants to an existing bitmask manipulator.  Pass a list of constant and value
       pairs as for "new".  Constants will be added to the end of the list (see "new" for an
       explanation of ordering concerns).

       The main use for "add_constants" is adding aggregate constants created by using
       "build_mask".

   build_mask
       This takes one of three things as a parameter:

       •   scalar - string is split on '"|"' and/or whitespace to generate a list of constants

       •   ARRAY ref - elements are the list of constants

       •   HASH ref - keys with true values are the list of constants; keys with false values are
           subtracted from the resultant mask

       In all situations, integers are legal in place of constant names and are treated as the
       value, after adding 2**32 to any negative integers.

   break_mask
       Breaks a mask apart.  Pass a mask value as an integer.  Returns a hash of all constants
       whose values are subsets of the passed mask.  Values are set to 1 so the result can safely
       be passed to "build_mask".

       Commonly used for operations like:

               if ($MaskManipulator->break_mask($my_mask_value)->{CONSTANT}) {

       Note that "break_mask" accepts

       To eliminate a constant from explain_mask or break_mask unless it perfectly matches, use
       "full_match" constants.

   explain_mask
       Explains a mask in terms of a relatively minimal set of constants.  Pass either a mask
       value as an integer or any valid parameter for "build_mask".  Returns a hash of constants
       that will recreate the mask. Many times, this will be the minimum number of constants
       necessary to describe the mask.  Note that creating the true minimum set of constants is
       somewhat painful (see Knapsack problem).

       The algorithm used by "explain_mask" is to first test for a constant that perfectly
       matches the mask.  If one is found, this is the obvious answer.  In the absence of a
       perfect match, "break_mask" is used to generate a maximal solution.  All simply occluded
       constants are then eliminated (that is to say, all constants in the list whose values are
       subsets of another single constant).  This means, for instance, that if you had only three
       constants, AB => 3, BC => 6, and AC => 5, "explain_mask" would return all three when
       passed the value 7 because no one constant is a subset of any single one of the others.

       To eliminate a constant from explain_mask or break_mask unless it perfectly matches, use
       "full_match" constants.

   build_const
       This takes one of two things as a parameter:

       •   scalar integer - if a scalar integer is passed, then the value is simply returned,
           after adding 2**32 to any negative integers

       •   scalar - string is looked up in the list of constants

   explain_const
       Looks for a perfect match for the passed mask value.  Pass either a mask value as an
       integer or any valid parameter for "build_mask".  If one is not found, it croaks.

   get_constants
       Returns all constants passed either to "new" or "add_constants".

AUTHOR

       Toby Ovod-Everett, toby@ovod-everett.org

LICENSE

       Copyright 2003, 2004 Toby Ovod-Everett.  All rights reserved.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.