Type-Tiny — Type::Tiny::Bitfield

Synopsis

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') );
    }
  }

Status

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

Description

Bitfield type constraints.

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

Attributes

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"

Methods

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;

Exports

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 },
  );

Overloading

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.

Type::Tiny::Bitfield