1Type::Tiny::Bitfield(3)User Contributed Perl DocumentatioTnype::Tiny::Bitfield(3)
2
3
4

NAME

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

SYNOPSIS

9       Using Type::Tiny::Bitfield's export feature:
10
11         package LightSource {
12           use Moo;
13
14           use Type::Tiny::Bitfield LedSet => {
15             RED   => 1,
16             GREEN => 2,
17             BLUE  => 4,
18           };
19
20           has leds => ( is => 'ro', isa => LedSet, default => 0, coerce => 1 );
21
22           sub new_red {
23             my $class = shift;
24             return $class->new( leds => LEDSET_RED );
25           }
26
27           sub new_green {
28             my $class = shift;
29             return $class->new( leds => LEDSET_GREEN );
30           }
31
32           sub new_yellow {
33             my $class = shift;
34             return $class->new( leds => LEDSET_RED | LEDSET_GREEN );
35           }
36         }
37
38       Using Type::Tiny::Bitfield's object-oriented interface:
39
40         package LightSource {
41           use Moo;
42           use Type::Tiny::Bitfield;
43
44           my $LedSet = Type::Tiny::Bitfield->new(
45             name   => 'LedSet',
46             values => {
47               RED   => 1,
48               GREEN => 2,
49               BLUE  => 4,
50             },
51             coercion => 1,
52           );
53
54           has leds => ( is => 'ro', isa => $LedSet, default => 0, coerce => 1 );
55
56           sub new_red {
57             my $class = shift;
58             return $class->new( leds => $LedSet->RED );
59           }
60
61           sub new_green {
62             my $class = shift;
63             return $class->new( leds => $LedSet->GREEN );
64           }
65
66           sub new_yellow {
67             my $class = shift;
68             return $class->new( leds => $LedSet->coerce('red|green') );
69           }
70         }
71

STATUS

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

DESCRIPTION

76       Bitfield type constraints.
77
78       This package inherits from Type::Tiny; see that for most documentation.
79       Major differences are listed below:
80
81   Attributes
82       "values"
83           Hashref of bits allowed in the bitfield. Keys must be
84           UPPER_SNAKE_CASE strings.  Values must be positive integers which
85           are powers of two. The same number cannot be used multiple times.
86
87       "constraint"
88           Unlike Type::Tiny, you cannot pass a constraint coderef to the
89           constructor.  Instead rely on the default.
90
91       "inlined"
92           Unlike Type::Tiny, you cannot pass an inlining coderef to the
93           constructor.  Instead rely on the default.
94
95       "parent"
96           Parent is always Types::Common::Numeric::PositiveOrZeroInt, and
97           cannot be passed to the constructor.
98
99       "coercion"
100           If "coercion => 1" is passed to the constructor, the type will have
101           an automatic coercion from Str. Types built by the "import" method
102           will always have "coercion => 1".
103
104           In the SYNOPSIS example, the coercion from Str will accept strings
105           like:
106
107             "RED"
108             "red"
109             "Red Green"
110             "Red+Blue"
111             "blue | GREEN"
112             "LEDSET_RED + LeDsEt_green"
113
114   Methods
115       This class uses "AUTOLOAD" to allow the names of each bit in the
116       bitfield to be used as methods. These method names will always be
117       UPPER_SNAKE_CASE.
118
119       For example, in the synopsis, "LedSet->GREEN" would return 2.
120
121       Other methods it provides:
122
123       from_string( $str )
124           Provides the standard coercion from a string, even if this type
125           constraint doesn't have a coercion.
126
127       to_string( $int )
128           Does the reverse coercion.
129
130       constant_names()
131           This is a convenience to allow for:
132
133             use base 'Exporter::Tiny';
134             push our @EXPORT_OK, LineStyle->constant_names;
135
136   Exports
137       Type::Tiny::Bitfield can be used as an exporter.
138
139         use Type::Tiny::Bitfield LedSet => {
140           RED    => 1,
141           GREEN  => 2,
142           BLUE   => 4,
143         };
144
145       This will export the following functions into your namespace:
146
147       "LedSet"
148       is_LedSet( $value )
149       assert_LedSet( $value )
150       to_LedSet( $string )
151       LedSet_to_Str( $value )
152       "LEDSET_RED"
153       "LEDSET_GREEN"
154       "LEDSET_BLUE"
155
156       Multiple bitfield types can be exported at once:
157
158         use Type::Tiny::Enum (
159           LedSet     => { RED => 1, GREEN => 2, BLUE => 4 },
160           LedPattern => { FLASHING => 1 },
161         );
162
163   Overloading
164       It is possible to combine two Bitfield types using the "+" operator.
165
166         use Type::Tiny::Enum (
167           LedSet     => { RED => 1, GREEN => 2, BLUE => 4 },
168           LedPattern => { FLASHING => 8 },
169         );
170
171         has leds => (
172           is      => 'ro',
173           isa     => LedSet + LedPattern,
174           default => 0,
175           coerce  => 1
176         );
177
178       This will allow values like "11"
179       (LEDSET_RED|LEDSET_GREEN|LEDPATTERN_FLASHING).
180
181       An exception will be thrown if any of the names in the two types being
182       combined conflict.
183

BUGS

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

SEE ALSO

189       Type::Tiny::Manual.
190
191       Type::Tiny.
192

AUTHOR

194       Toby Inkster <tobyink@cpan.org>.
195

197       This software is copyright (c) 2023 by Toby Inkster.
198
199       This is free software; you can redistribute it and/or modify it under
200       the same terms as the Perl 5 programming language system itself.
201

DISCLAIMER OF WARRANTIES

203       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
204       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
205       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
206
207
208
209perl v5.38.0                      2023-07-21           Type::Tiny::Bitfield(3)
Impressum