1Test2::Util::HashBase(3U)ser Contributed Perl DocumentatiToenst2::Util::HashBase(3)
2
6 Test2::Util::HashBase - Build hash based classes.
7
9 A class:
10 package My::Class;
12 use strict;
13 use warnings;
14 # Generate 3 accessors
16 use Test2::Util::HashBase qw/foo -bar ^baz <bat >ban +boo/;
17 # Chance to initialize defaults
19 sub init {
20 my $self = shift; # No other args
21 $self->{+FOO} ||= "foo";
22 $self->{+BAR} ||= "bar";
23 $self->{+BAZ} ||= "baz";
24 $self->{+BAT} ||= "bat";
25 $self->{+BAN} ||= "ban";
26 $self->{+BOO} ||= "boo";
27 }
28 sub print {
30 print join ", " => map { $self->{$_} } FOO, BAR, BAZ, BAT, BAN, BOO;
31 }
32 Subclass it
34 package My::Subclass;
36 use strict;
37 use warnings;
38 # Note, you should subclass before loading HashBase.
40 use base 'My::Class';
41 use Test2::Util::HashBase qw/bub/;
42 sub init {
44 my $self = shift;
45 # We get the constants from the base class for free.
47 $self->{+FOO} ||= 'SubFoo';
48 $self->{+BUB} ||= 'bub';
49 $self->SUPER::init();
51 }
52 use it:
54 package main;
56 use strict;
57 use warnings;
58 use My::Class;
59 # These are all functionally identical
61 my $one = My::Class->new(foo => 'MyFoo', bar => 'MyBar');
62 my $two = My::Class->new({foo => 'MyFoo', bar => 'MyBar'});
63 my $three = My::Class->new(['MyFoo', 'MyBar']);
64 # Readers!
66 my $foo = $one->foo; # 'MyFoo'
67 my $bar = $one->bar; # 'MyBar'
68 my $baz = $one->baz; # Defaulted to: 'baz'
69 my $bat = $one->bat; # Defaulted to: 'bat'
70 # '>ban' means setter only, no reader
71 # '+boo' means no setter or reader, just the BOO constant
72 # Setters!
74 $one->set_foo('A Foo');
75 #'-bar' means read-only, so the setter will throw an exception (but is defined).
77 $one->set_bar('A bar');
78 # '^baz' means deprecated setter, this will warn about the setter being
80 # deprecated.
81 $one->set_baz('A Baz');
82 # '<bat' means no setter defined at all
84 # '+boo' means no setter or reader, just the BOO constant
85 $one->{+FOO} = 'xxx';
87
89 This package is used to generate classes based on hashrefs. Using this
90 class will give you a "new()" method, as well as generating accessors
91 you request. Generated accessors will be getters, "set_ACCESSOR"
92 setters will also be generated for you. You also get constants for each
93 accessor (all caps) which return the key into the hash for that
94 accessor. Single inheritance is also supported.
95
97 This is a bundled copy of Object::HashBase. This file was generated
98 using the "/home/exodist/perl5/perlbrew/perls/main/bin/hashbase_inc.pl"
99 script.
100
102 PROVIDED BY HASH BASE
103 $it = $class->new(%PAIRS)
104 $it = $class->new(\%PAIRS)
105 $it = $class->new(\@ORDERED_VALUES)
106 Create a new instance.
107 HashBase will not export "new()" if there is already a "new()"
109 method in your packages inheritance chain.
110 If you do not want this method you can define your own you just
112 have to declare it before loading Test2::Util::HashBase.
113 package My::Package;
115 # predeclare new() so that HashBase does not give us one.
117 sub new;
118 use Test2::Util::HashBase qw/foo bar baz/;
120 # Now we define our own new method.
122 sub new { ... }
123 This makes it so that HashBase sees that you have your own "new()"
125 method. Alternatively you can define the method before loading
126 HashBase instead of just declaring it, but that scatters your use
127 statements.
128 The most common way to create an object is to pass in key/value
130 pairs where each key is an attribute and each value is what you
131 want assigned to that attribute. No checking is done to verify the
132 attributes or values are valid, you may do that in "init()" if
133 desired.
134 If you would like, you can pass in a hashref instead of pairs. When
136 you do so the hashref will be copied, and the copy will be returned
137 blessed as an object. There is no way to ask HashBase to bless a
138 specific hashref.
139 In some cases an object may only have 1 or 2 attributes, in which
141 case a hashref may be too verbose for your liking. In these cases
142 you can pass in an arrayref with only values. The values will be
143 assigned to attributes in the order the attributes were listed.
144 When there is inheritance involved the attributes from parent
145 classes will come before subclasses.
146 HOOKS
148 $self->init()
149 This gives you the chance to set some default values to your
150 fields. The only argument is $self with its indexes already set
151 from the constructor.
152 Note: Test2::Util::HashBase checks for an init using
154 "$class->can('init')" during construction. It DOES NOT call "can()"
155 on the created object. Also note that the result of the check is
156 cached, it is only ever checked once, the first time an instance of
157 your class is created. This means that adding an "init()" method
158 AFTER the first construction will result in it being ignored.
159
161 READ/WRITE
162 To generate accessors you list them when using the module:
163 use Test2::Util::HashBase qw/foo/;
165 This will generate the following subs in your namespace:
167 foo()
169 Getter, used to get the value of the "foo" field.
170 set_foo()
172 Setter, used to set the value of the "foo" field.
173 FOO()
175 Constant, returns the field "foo"'s key into the class hashref.
176 Subclasses will also get this function as a constant, not simply a
177 method, that means it is copied into the subclass namespace.
178 The main reason for using these constants is to help avoid spelling
180 mistakes and similar typos. It will not help you if you forget to
181 prefix the '+' though.
182 READ ONLY
184 use Test2::Util::HashBase qw/-foo/;
185 set_foo()
187 Throws an exception telling you the attribute is read-only. This is
188 exported to override any active setters for the attribute in a
189 parent class.
190 DEPRECATED SETTER
192 use Test2::Util::HashBase qw/^foo/;
193 set_foo()
195 This will set the value, but it will also warn you that the method
196 is deprecated.
197 NO SETTER
199 use Test2::Util::HashBase qw/<foo/;
200 Only gives you a reader, no "set_foo" method is defined at all.
202 NO READER
204 use Test2::Util::HashBase qw/>foo/;
205 Only gives you a write ("set_foo"), no "foo" method is defined at all.
207 CONSTANT ONLY
209 use Test2::Util::HashBase qw/+foo/;
210 This does not create any methods for you, it just adds the "FOO"
212 constant.
213
215 You can subclass an existing HashBase class.
216 use base 'Another::HashBase::Class';
218 use Test2::Util::HashBase qw/foo bar baz/;
219 The base class is added to @ISA for you, and all constants from base
221 classes are added to subclasses automatically.
222
224 Test2::Util::HashBase provides a function for retrieving a list of
225 attributes for an Test2::Util::HashBase class.
226 @list = Test2::Util::HashBase::attr_list($class)
228 @list = $class->Test2::Util::HashBase::attr_list()
229 Either form above will work. This will return a list of attributes
230 defined on the object. This list is returned in the attribute
231 definition order, parent class attributes are listed before
232 subclass attributes. Duplicate attributes will be removed before
233 the list is returned.
234 Note: This list is used in the "$class->new(\@ARRAY)" constructor
236 to determine the attribute to which each value will be paired.
237
239 The source code repository for HashBase can be found at
240 http://github.com/Test-More/HashBase/.
241
243 Chad Granum <exodist@cpan.org>
244
246 Chad Granum <exodist@cpan.org>
247
249 Copyright 2017 Chad Granum <exodist@cpan.org>.
250 This program is free software; you can redistribute it and/or modify it
252 under the same terms as Perl itself.
253 See http://dev.perl.org/licenses/
255perl v5.34.0 2022-03-05 Test2::Util::HashBase(3)