Type::Tiny::Bitfield(3pm) User Contributed Perl Documentation Type::Tiny::Bitfield(3pm)

Type::Tiny::Bitfield - bitfield/bitflag type constraints

Using Type::Tiny::Bitfield's export feature:

  package LightSource {
    use Moo;
    
    use Type::Tiny::Bitfield LedSet => {
      RED   => 1,
      GREEN => 2,
      BLUE  => 4,
    };
    
    has leds => ( is => 'ro', isa => LedSet, default => 0, coerce => 1 );
    
    sub new_red {
      my $class = shift;
      return $class->new( leds => LEDSET_RED );
    }
    
    sub new_green {
      my $class = shift;
      return $class->new( leds => LEDSET_GREEN );
    }
    
    sub new_yellow {
      my $class = shift;
      return $class->new( leds => LEDSET_RED | LEDSET_GREEN );
    }
  }

Using Type::Tiny::Bitfield's object-oriented interface:

  package LightSource {
    use Moo;
    use Type::Tiny::Bitfield;
    
    my $LedSet = Type::Tiny::Bitfield->new(
      name   => 'LedSet',
      values => {
        RED   => 1,
        GREEN => 2,
        BLUE  => 4,
      },
      coercion => 1,
    );
    
    has leds => ( is => 'ro', isa => $LedSet, default => 0, coerce => 1 );
    
    sub new_red {
      my $class = shift;
      return $class->new( leds => $LedSet->RED );
    }
    
    sub new_green {
      my $class = shift;
      return $class->new( leds => $LedSet->GREEN );
    }
    
    sub new_yellow {
      my $class = shift;
      return $class->new( leds => $LedSet->coerce('red|green') );
    }
  }

This module is covered by the Type-Tiny stability policy.

Bitfield type constraints.

This package inherits from Type::Tiny; see that for most documentation. Major differences are listed below:

"values"
Hashref of bits allowed in the bitfield. Keys must be UPPER_SNAKE_CASE strings. Values must be positive integers which are powers of two. The same number cannot be used multiple times.
"constraint"
Unlike Type::Tiny, you cannot pass a constraint coderef to the constructor. Instead rely on the default.
"inlined"
Unlike Type::Tiny, you cannot pass an inlining coderef to the constructor. Instead rely on the default.
"parent"
Parent is always Types::Common::Numeric::PositiveOrZeroInt, and cannot be passed to the constructor.
"coercion"
If "coercion => 1" is passed to the constructor, the type will have an automatic coercion from Str. Types built by the "import" method will always have "coercion => 1".

In the SYNOPSIS example, the coercion from Str will accept strings like:

  "RED"
  "red"
  "Red Green"
  "Red+Blue"
  "blue | GREEN"
  "LEDSET_RED + LeDsEt_green"

This class uses "AUTOLOAD" to allow the names of each bit in the bitfield to be used as methods. These method names will always be UPPER_SNAKE_CASE.

For example, in the synopsis, "LedSet->GREEN" would return 2.

Other methods it provides:

"from_string( $str )"
Provides the standard coercion from a string, even if this type constraint doesn't have a coercion.
"to_string( $int )"
Does the reverse coercion.
"constant_names()"
This is a convenience to allow for: 

  use base 'Exporter::Tiny';
  push our @EXPORT_OK, LineStyle->constant_names;

Type::Tiny::Bitfield can be used as an exporter.

  use Type::Tiny::Bitfield LedSet => {
    RED    => 1,
    GREEN  => 2,
    BLUE   => 4,
  };

This will export the following functions into your namespace:

"LedSet"
"is_LedSet( $value )"
"assert_LedSet( $value )"
"to_LedSet( $string )"
"LedSet_to_Str( $value )"
"LEDSET_RED"
"LEDSET_GREEN"
"LEDSET_BLUE"

Multiple bitfield types can be exported at once:

  use Type::Tiny::Enum (
    LedSet     => { RED => 1, GREEN => 2, BLUE => 4 },
    LedPattern => { FLASHING => 1 },
  );

It is possible to combine two Bitfield types using the "+" operator.

  use Type::Tiny::Enum (
    LedSet     => { RED => 1, GREEN => 2, BLUE => 4 },
    LedPattern => { FLASHING => 8 },
  );
  
  has leds => (
    is      => 'ro',
    isa     => LedSet + LedPattern,
    default => 0,
    coerce  => 1
  );

This will allow values like "11" (LEDSET_RED|LEDSET_GREEN|LEDPATTERN_FLASHING).

An exception will be thrown if any of the names in the two types being combined conflict.

Please report any bugs to <https://github.com/tobyink/p5-type-tiny/issues>.

Type::Tiny::Manual.

Type::Tiny.

Toby Inkster <tobyink@cpan.org>.

This software is copyright (c) 2023 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

2023-07-21 perl v5.36.0