Toby Ovod-Everett > Data-BitMask-0.91 > Data::BitMask

Download:
Data-BitMask-0.91.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.91   Source  

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:

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 precendence 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:

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:

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.

syntax highlighting: