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.

    Calls to "build_mask", "break_mask", and "explain_mask" are memoized to
    speed up repeated calls with the same parameters.

  Installation instructions
    There are four options for installing this module:

    *   Using "Module::Build 0.24" or later:

          Build.PL
          perl build test
          perl build install

    *   Using "ExtUtils::MakeMaker" (part of the Perl core):

          Makefile.PL
          make test
          make install

    *   Using the PPM (the file has the extension ".ppm.zip") on CPAN and
        installing under ActivePerl for Win32 by unzipping the ".ppm.zip"
        file and then:

          ppm install Data-BitMask.ppd

    *   Installing manually by copying "lib/Data/Bitmask.pm" to
        "perl/site/lib/Data/Bitmask.pm".

Suggested 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.

