1Test2::Util::HashBase(3U)ser Contributed Perl DocumentatiToenst2::Util::HashBase(3)
2
3
4

NAME

6       Test2::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::Util::HashBase qw/foo -bar ^baz/;
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           }
25
26           sub print {
27               print join ", " => map { $self->{$_} } FOO, BAR, BAZ;
28           }
29
30       Subclass it
31
32           package My::Subclass;
33           use strict;
34           use warnings;
35
36           # Note, you should subclass before loading HashBase.
37           use base 'My::Class';
38           use Test2::Util::HashBase qw/bat/;
39
40           sub init {
41               my $self = shift;
42
43               # We get the constants from the base class for free.
44               $self->{+FOO} ||= 'SubFoo';
45               $self->{+BAT} ||= 'bat';
46
47               $self->SUPER::init();
48           }
49
50       use it:
51
52           package main;
53           use strict;
54           use warnings;
55           use My::Class;
56
57           # These are all functionally identical
58           my $one   = My::Class->new(foo => 'MyFoo', bar => 'MyBar');
59           my $two   = My::Class->new({foo => 'MyFoo', bar => 'MyBar'});
60           my $three = My::Class->new(['MyFoo', 'MyBar']);
61
62           # Accessors!
63           my $foo = $one->foo;    # 'MyFoo'
64           my $bar = $one->bar;    # 'MyBar'
65           my $baz = $one->baz;    # Defaulted to: 'baz'
66
67           # Setters!
68           $one->set_foo('A Foo');
69
70           #'-bar' means read-only, so the setter will throw an exception (but is defined).
71           $one->set_bar('A bar');
72
73           # '^baz' means deprecated setter, this will warn about the setter being
74           # deprecated.
75           $one->set_baz('A Baz');
76
77           $one->{+FOO} = 'xxx';
78

DESCRIPTION

80       This package is used to generate classes based on hashrefs. Using this
81       class will give you a "new()" method, as well as generating accessors
82       you request.  Generated accessors will be getters, "set_ACCESSOR"
83       setters will also be generated for you. You also get constants for each
84       accessor (all caps) which return the key into the hash for that
85       accessor. Single inheritance is also supported.
86

THIS IS A BUNDLED COPY OF HASHBASE

88       This is a bundled copy of Object::HashBase. This file was generated
89       using the "/home/exodist/perl5/perlbrew/perls/main/bin/hashbase_inc.pl"
90       script.
91

METHODS

93   PROVIDED BY HASH BASE
94       $it = $class->new(%PAIRS)
95       $it = $class->new(\%PAIRS)
96       $it = $class->new(\@ORDERED_VALUES)
97           Create a new instance.
98
99           HashBase will not export "new()" if there is already a "new()"
100           method in your packages inheritance chain.
101
102           If you do not want this method you can define your own you just
103           have to declare it before loading Test2::Util::HashBase.
104
105               package My::Package;
106
107               # predeclare new() so that HashBase does not give us one.
108               sub new;
109
110               use Test2::Util::HashBase qw/foo bar baz/;
111
112               # Now we define our own new method.
113               sub new { ... }
114
115           This makes it so that HashBase sees that you have your own "new()"
116           method.  Alternatively you can define the method before loading
117           HashBase instead of just declaring it, but that scatters your use
118           statements.
119
120           The most common way to create an object is to pass in key/value
121           pairs where each key is an attribute and each value is what you
122           want assigned to that attribute. No checking is done to verify the
123           attributes or values are valid, you may do that in "init()" if
124           desired.
125
126           If you would like, you can pass in a hashref instead of pairs. When
127           you do so the hashref will be copied, and the copy will be returned
128           blessed as an object.  There is no way to ask HashBase to bless a
129           specific hashref.
130
131           In some cases an object may only have 1 or 2 attributes, in which
132           case a hashref may be too verbose for your liking. In these cases
133           you can pass in an arrayref with only values. The values will be
134           assigned to attributes in the order the attributes were listed.
135           When there is inheritance involved the attributes from parent
136           classes will come before subclasses.
137
138   HOOKS
139       $self->init()
140           This gives you the chance to set some default values to your
141           fields. The only argument is $self with its indexes already set
142           from the constructor.
143
144           Note: Test2::Util::HashBase checks for an init using
145           "$class->can('init')" during construction. It DOES NOT call "can()"
146           on the created object. Also note that the result of the check is
147           cached, it is only ever checked once, the first time an instance of
148           your class is created. This means that adding an "init()" method
149           AFTER the first construction will result in it being ignored.
150

ACCESSORS

152   READ/WRITE
153       To generate accessors you list them when using the module:
154
155           use Test2::Util::HashBase qw/foo/;
156
157       This will generate the following subs in your namespace:
158
159       foo()
160           Getter, used to get the value of the "foo" field.
161
162       set_foo()
163           Setter, used to set the value of the "foo" field.
164
165       FOO()
166           Constant, returns the field "foo"'s key into the class hashref.
167           Subclasses will also get this function as a constant, not simply a
168           method, that means it is copied into the subclass namespace.
169
170           The main reason for using these constants is to help avoid spelling
171           mistakes and similar typos. It will not help you if you forget to
172           prefix the '+' though.
173
174   READ ONLY
175           use Test2::Util::HashBase qw/-foo/;
176
177       set_foo()
178           Throws an exception telling you the attribute is read-only. This is
179           exported to override any active setters for the attribute in a
180           parent class.
181
182   DEPRECATED SETTER
183           use Test2::Util::HashBase qw/^foo/;
184
185       set_foo()
186           This will set the value, but it will also warn you that the method
187           is deprecated.
188

SUBCLASSING

190       You can subclass an existing HashBase class.
191
192           use base 'Another::HashBase::Class';
193           use Test2::Util::HashBase qw/foo bar baz/;
194
195       The base class is added to @ISA for you, and all constants from base
196       classes are added to subclasses automatically.
197

GETTING A LIST OF ATTRIBUTES FOR A CLASS

199       Test2::Util::HashBase provides a function for retrieving a list of
200       attributes for an Test2::Util::HashBase class.
201
202       @list = Test2::Util::HashBase::attr_list($class)
203       @list = $class->Test2::Util::HashBase::attr_list()
204           Either form above will work. This will return a list of attributes
205           defined on the object. This list is returned in the attribute
206           definition order, parent class attributes are listed before
207           subclass attributes. Duplicate attributes will be removed before
208           the list is returned.
209
210           Note: This list is used in the "$class->new(\@ARRAY)" constructor
211           to determine the attribute to which each value will be paired.
212

SOURCE

214       The source code repository for HashBase can be found at
215       http://github.com/Test-More/HashBase/.
216

MAINTAINERS

218       Chad Granum <exodist@cpan.org>
219

AUTHORS

221       Chad Granum <exodist@cpan.org>
222

COPYRIGHT

224       Copyright 2018 Chad Granum <exodist@cpan.org>.
225
226       This program is free software; you can redistribute it and/or modify it
227       under the same terms as Perl itself.
228
229       See http://dev.perl.org/licenses/
230
231
232
233perl v5.26.3                      2018-03-30          Test2::Util::HashBase(3)