1Test2::Harness::Util::HUassehrBaCsoen(t3r)ibuted Perl DoTceusmte2n:t:aHtaironness::Util::HashBase(3)
2
3
4

NAME

6       Test2::Harness::Util::HashBase - Build hash based classes.
7

SYNOPSIS

9       A class:
10
11           package My::Class;
12           use strict;
13           use warnings;
14
15           # Generate 3 accessors
16           use Test2::Harness::Util::HashBase qw/foo -bar ^baz <bat >ban +boo/;
17
18           # 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
29           sub print {
30               print join ", " => map { $self->{$_} } FOO, BAR, BAZ, BAT, BAN, BOO;
31           }
32
33       Subclass it
34
35           package My::Subclass;
36           use strict;
37           use warnings;
38
39           # Note, you should subclass before loading HashBase.
40           use base 'My::Class';
41           use Test2::Harness::Util::HashBase qw/bub/;
42
43           sub init {
44               my $self = shift;
45
46               # We get the constants from the base class for free.
47               $self->{+FOO} ||= 'SubFoo';
48               $self->{+BUB} ||= 'bub';
49
50               $self->SUPER::init();
51           }
52
53       use it:
54
55           package main;
56           use strict;
57           use warnings;
58           use My::Class;
59
60           # 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
65           # 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
73           # Setters!
74           $one->set_foo('A Foo');
75
76           #'-bar' means read-only, so the setter will throw an exception (but is defined).
77           $one->set_bar('A bar');
78
79           # '^baz' means deprecated setter, this will warn about the setter being
80           # deprecated.
81           $one->set_baz('A Baz');
82
83           # '<bat' means no setter defined at all
84           # '+boo' means no setter or reader, just the BOO constant
85
86           $one->{+FOO} = 'xxx';
87

DESCRIPTION

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

THIS IS A BUNDLED COPY OF HASHBASE

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

METHODS

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
108           HashBase will not export "new()" if there is already a "new()"
109           method in your packages inheritance chain.
110
111           If you do not want this method you can define your own you just
112           have to declare it before loading Test2::Harness::Util::HashBase.
113
114               package My::Package;
115
116               # predeclare new() so that HashBase does not give us one.
117               sub new;
118
119               use Test2::Harness::Util::HashBase qw/foo bar baz/;
120
121               # Now we define our own new method.
122               sub new { ... }
123
124           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
129           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
135           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
140           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
147   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
153           Note: Test2::Harness::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

ACCESSORS

161   READ/WRITE
162       To generate accessors you list them when using the module:
163
164           use Test2::Harness::Util::HashBase qw/foo/;
165
166       This will generate the following subs in your namespace:
167
168       foo()
169           Getter, used to get the value of the "foo" field.
170
171       set_foo()
172           Setter, used to set the value of the "foo" field.
173
174       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
179           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
183   READ ONLY
184           use Test2::Harness::Util::HashBase qw/-foo/;
185
186       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
191   DEPRECATED SETTER
192           use Test2::Harness::Util::HashBase qw/^foo/;
193
194       set_foo()
195           This will set the value, but it will also warn you that the method
196           is deprecated.
197
198   NO SETTER
199           use Test2::Harness::Util::HashBase qw/<foo/;
200
201       Only gives you a reader, no "set_foo" method is defined at all.
202
203   NO READER
204           use Test2::Harness::Util::HashBase qw/>foo/;
205
206       Only gives you a write ("set_foo"), no "foo" method is defined at all.
207
208   CONSTANT ONLY
209           use Test2::Harness::Util::HashBase qw/+foo/;
210
211       This does not create any methods for you, it just adds the "FOO"
212       constant.
213

SUBCLASSING

215       You can subclass an existing HashBase class.
216
217           use base 'Another::HashBase::Class';
218           use Test2::Harness::Util::HashBase qw/foo bar baz/;
219
220       The base class is added to @ISA for you, and all constants from base
221       classes are added to subclasses automatically.
222

GETTING A LIST OF ATTRIBUTES FOR A CLASS

224       Test2::Harness::Util::HashBase provides a function for retrieving a
225       list of attributes for an Test2::Harness::Util::HashBase class.
226
227       @list = Test2::Harness::Util::HashBase::attr_list($class)
228       @list = $class->Test2::Harness::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
235           Note: This list is used in the "$class->new(\@ARRAY)" constructor
236           to determine the attribute to which each value will be paired.
237

SOURCE

239       The source code repository for HashBase can be found at
240       http://github.com/Test-More/HashBase/.
241

MAINTAINERS

243       Chad Granum <exodist@cpan.org>
244

AUTHORS

246       Chad Granum <exodist@cpan.org>
247
249       Copyright 2017 Chad Granum <exodist@cpan.org>.
250
251       This program is free software; you can redistribute it and/or modify it
252       under the same terms as Perl itself.
253
254       See http://dev.perl.org/licenses/
255
256
257
258perl v5.34.1                      2022-07-11 Test2::Harness::Util::HashBase(3)
Impressum