.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::BitMask 3pm"
.TH Data::BitMask 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::BitMask \- bitmask manipulation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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(\*(AqREAD|WRITE\*(Aq);
\&  print Data::Dumper\->Dump([
\&      $FileMask\->explain_mask($mask),
\&      $FileMask\->break_mask($mask)
\&    ]);
\&  
\&  my $mask2 = $FileMask\->build_mask({FULL => 1, WRITE => 0});
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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).
.PP
The module expends a modest amount of overhead in creating the \f(CW\*(C`Data::BitMask\*(C'\fR 
object so as to speed up future mask manipulations.
.SS "Installation instructions"
.IX Subsection "Installation instructions"
This module requires \f(CW\*(C`Module::Build 0.24\*(C'\fR to use the automated installation 
procedures.  With \f(CW\*(C`Module::Build\*(C'\fR installed:
.PP
.Vb 3
\&  Build.PL
\&  perl build test
\&  perl build install
.Ve
.PP
It can also be installed manually by copying \f(CW\*(C`lib/Data/Bitmask.pm\*(C'\fR to 
\&\f(CW\*(C`perl/site/lib/Data/Bitmask.pm\*(C'\fR.
.SH "Suggest Module Implementation"
.IX Header "Suggest Module Implementation"
Here is one suggested approach to using bitmask manipulators in a module.
.PP
.Vb 11
\&  {
\&  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,
\&      );
\&  }
\&  }
.Ve
.PP
The bitmask manipulator can then be accessed as:
.PP
.Vb 1
\&  &SECURITY_INFORMATION\->build_mask(\*(AqDACL_SECURITY_INFORMATION\*(Aq);
.Ve
.PP
Or, if you are outside of the module, as:
.PP
.Vb 1
\&  &Win32::Security::SECURITY_INFORMATION\->build_mask(\*(AqDACL_SECURITY_INFORMATION\*(Aq);
.Ve
.PP
This has several advantages:
.IP "\(bu" 4
Demand creation of the \f(CW\*(C`Data::Bitmask\*(C'\fR 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.
.IP "\(bu" 4
Easy access from within in the module, reasonably easy access from outside the 
module.
.IP "\(bu" 4
If the user wants even easier access from outside the module, you can support 
Exporter and let the sub be exported.
.SH "Method Reference"
.IX Header "Method Reference"
.SS "new"
.IX Subsection "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 
\&\f(CW\*(C`explain_mask\*(C'\fR or \f(CW\*(C`explain_const\*(C'\fR, 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.
.PP
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 
\&\f(CW\*(C`full_match\*(C'\fR, which implies that the constant should only be returned from 
\&\f(CW\*(C`break_mask\*(C'\fR or \f(CW\*(C`explain_mask\*(C'\fR if it perfectly matches the mask being 
explained.  For example:
.PP
.Vb 1
\&      [qw(FILES_ONLY_NO_INHERIT full_match 1)] =>    1,
.Ve
.SS "add_constants"
.IX Subsection "add_constants"
Adds constants to an existing bitmask manipulator.  Pass a list of constant and
value pairs as for \f(CW\*(C`new\*(C'\fR.  Constants will be added to the end of the list (see
\&\f(CW\*(C`new\*(C'\fR for an explanation of ordering concerns).
.PP
The main use for \f(CW\*(C`add_constants\*(C'\fR is adding aggregate constants created by using 
\&\f(CW\*(C`build_mask\*(C'\fR.
.SS "build_mask"
.IX Subsection "build_mask"
This takes one of three things as a parameter:
.IP "\(bu" 4
scalar \- string is split on '\f(CW\*(C`|\*(C'\fR' and/or whitespace to generate a list of 
constants
.IP "\(bu" 4
\&\s-1ARRAY\s0 ref \- elements are the list of constants
.IP "\(bu" 4
\&\s-1HASH\s0 ref \- keys with true values are the list of constants; keys with false 
values are subtracted from the resultant mask
.PP
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.
.SS "break_mask"
.IX Subsection "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 \f(CW\*(C`build_mask\*(C'\fR.
.PP
Commonly used for operations like:
.PP
.Vb 1
\&        if ($MaskManipulator\->break_mask($my_mask_value)\->{CONSTANT}) {
.Ve
.PP
Note that \f(CW\*(C`break_mask\*(C'\fR accepts
.PP
To eliminate a constant from explain_mask or break_mask unless it perfectly 
matches, use \f(CW\*(C`full_match\*(C'\fR constants.
.SS "explain_mask"
.IX Subsection "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 \f(CW\*(C`build_mask\*(C'\fR.  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).
.PP
The algorithm used by \f(CW\*(C`explain_mask\*(C'\fR 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, \f(CW\*(C`break_mask\*(C'\fR 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, \s-1AB\s0 => 3, \s-1BC\s0 => 
6, and \s-1AC\s0 => 5, \f(CW\*(C`explain_mask\*(C'\fR would return all three when passed the value 7 
because no one constant is a subset of any single one of the others.
.PP
To eliminate a constant from explain_mask or break_mask unless it perfectly 
matches, use \f(CW\*(C`full_match\*(C'\fR constants.
.SS "build_const"
.IX Subsection "build_const"
This takes one of two things as a parameter:
.IP "\(bu" 4
scalar integer \- if a scalar integer is passed, then the value is simply 
returned, after adding 2**32 to any negative integers
.IP "\(bu" 4
scalar \- string is looked up in the list of constants
.SS "explain_const"
.IX Subsection "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 \f(CW\*(C`build_mask\*(C'\fR.  If one is not found, it 
croaks.
.SS "get_constants"
.IX Subsection "get_constants"
Returns all constants passed either to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`add_constants\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Ovod-Everett, toby@ovod\-everett.org
.SH "LICENSE"
.IX Header "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.