NAME
    bitflags - Simplify export of bitflag names

SYNOPSIS
    "package SomeModule;"
            use bitflags qw(V1 V2 ...);

        Series of constants "V1,V2,V3 ..." now available with values
        "1,2,4,.."

            do  something with constants V1, V3|~V4 and the like ;
            sub anyFunc
            {
                $v = getmask @_;
                ...
            }

    "package AnotherModule;"
            use SomeModule;
            SomeModule::anyFunc(qw(V3 V5 V11 ...))

        Inside "SomeModule::anyFunc" with assignment "$v=getmask(@_)" these
        arguments arrive as "V3|V5|V11"

DESCRIPTION
   Core Features
    "use bitflags qw(V1 V2 ...)" defines a series of constants which denote
    different bitflags in the calling module, say "package SomeModule". The
    constants are used as ordinary names, usually making up boolean
    expressions by bitwise operation-combinations. If "AnotherModule" calls
    "SomeModule" and refers to the flagnames, export of the names would be
    demanded. Yet unlike in "SomeModule" the binary 'or' will be the only
    opreation needed to combine the flags. E.g., if "alfa, beta, gamma,
    delta, fi" are names for "1,2,4,8,16", a choice term "beta|delta|fi"
    could be used in "AnotherModule". Pragma "bitflag" makes the export of
    the flagnames dispensable, as it represents the choice term as
    "getmask(qw(beta delta fi))". "getmask()" converts a list of strings
    containing names of flags into the boolean union of those flags. Thus
    the export of a lot of symbols is reduced to the export of a sole
    subname, "getmask()", which is defined in "package bitflags" and
    exported by default to "SomeModule". Coupling of packages is diminished
    this way.

   Special Features
    Multiple uses of ""bitflags"" may occur in a package. "use bitflags
    @thislist" and "use bitflags @thatlist", regardless whether adjacent or
    separated in code, do the same as "use bitflags @thislist,@thatlist".
    However, a second statement could also determine values of a separate
    range. If, in contrast to above specifications, the first argument of
    "use bitflags" is a hash and not a string, it represents a collection of
    options that can

    1.  override the value of the starting flag -- apply option "sm=>$m"

    2.  allow deviation of the case of characters in arguments of "getmask"
        -- with option "ic=>1".

    One can write, e.g., "use bitflags {sm=>128, ic=>1}..."

    Furthermore, "use bitflags {sm=>$m}..." can be abbreviated to "use
    bitflags $m...".

   Multiple uses
    By option "sm=>$number" one can define another name for a value already
    assigned by a prior "use bitflags".

    Furthermore "use bitflags" could be called from different packages in
    one application run. If so, the module loaded later shall continue
    counting where the earlier module stopped, i.e. if "ModuleA::LASTFLAG"
    is 256, calling "use bitflags FIRSTFLAG, ..." in "ModuleB" makes
    "ModuleB::FIRSTFLAG" being 512. If "ModuleB" use other names
    independently to "ModuleA" it makes sense to restart with value 1 by
    using "{sm=>1}" as first parameter.

AUTHOR
    Josef Schnbrunner <j.schoenbrunner@schule.at>

COPYRIGHT AND LICENSE
    Copyright (c) 2008 by Josef Schnbrunner This library is free software;
    you can redistribute it and/or modify it under the same terms as Perl
    itself, either Perl version 5.8.7 or, at your option, any later version
    of Perl 5 you may have available.
