1Object::HashBase(3)   User Contributed Perl Documentation  Object::HashBase(3)
2
3
4

NAME

6       Object::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 Object::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 Object::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 you
91       request.  Generated accessors will be getters, "set_ACCESSOR" setters
92       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

INCLUDING IN YOUR DIST

97       If you want to use HashBase, but do not want to depend on it, you can
98       include it in your distribution.
99
100           $ hashbase_inc.pl Prefix::For::Module
101
102       This will create 2 files:
103
104           lib/Prefix/For/Module/HashBase.pm
105           t/HashBase.t
106
107       You can then use the includes "Prefix::For::Module::HashBase" instead
108       of "Object::HashBase".
109
110       You can re-run this script to regenerate the files, or upgrade them to
111       newer versions.
112
113       If the script was not installed, it can be found in the "scripts/"
114       directory.
115

METHODS

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

ACCESSORS

176   READ/WRITE
177       To generate accessors you list them when using the module:
178
179           use Object::HashBase qw/foo/;
180
181       This will generate the following subs in your namespace:
182
183       foo()
184           Getter, used to get the value of the "foo" field.
185
186       set_foo()
187           Setter, used to set the value of the "foo" field.
188
189       FOO()
190           Constant, returns the field "foo"'s key into the class hashref.
191           Subclasses will also get this function as a constant, not simply a
192           method, that means it is copied into the subclass namespace.
193
194           The main reason for using these constants is to help avoid spelling
195           mistakes and similar typos. It will not help you if you forget to
196           prefix the '+' though.
197
198   READ ONLY
199           use Object::HashBase qw/-foo/;
200
201       set_foo()
202           Throws an exception telling you the attribute is read-only. This is
203           exported to override any active setters for the attribute in a
204           parent class.
205
206   DEPRECATED SETTER
207           use Object::HashBase qw/^foo/;
208
209       set_foo()
210           This will set the value, but it will also warn you that the method
211           is deprecated.
212
213   NO SETTER
214           use Object::HashBase qw/<foo/;
215
216       Only gives you a reader, no "set_foo" method is defined at all.
217
218   NO READER
219           use Object::HashBase qw/>foo/;
220
221       Only gives you a write ("set_foo"), no "foo" method is defined at all.
222
223   CONSTANT ONLY
224           use Object::HashBase qw/+foo/;
225
226       This does not create any methods for you, it just adds the "FOO"
227       constant.
228

SUBCLASSING

230       You can subclass an existing HashBase class.
231
232           use base 'Another::HashBase::Class';
233           use Object::HashBase qw/foo bar baz/;
234
235       The base class is added to @ISA for you, and all constants from base
236       classes are added to subclasses automatically.
237

GETTING A LIST OF ATTRIBUTES FOR A CLASS

239       Object::HashBase provides a function for retrieving a list of
240       attributes for an Object::HashBase class.
241
242       @list = Object::HashBase::attr_list($class)
243       @list = $class->Object::HashBase::attr_list()
244           Either form above will work. This will return a list of attributes
245           defined on the object. This list is returned in the attribute
246           definition order, parent class attributes are listed before
247           subclass attributes. Duplicate attributes will be removed before
248           the list is returned.
249
250           Note: This list is used in the "$class->new(\@ARRAY)" constructor
251           to determine the attribute to which each value will be paired.
252

SOURCE

254       The source code repository for HashBase can be found at
255       http://github.com/Test-More/HashBase/.
256

MAINTAINERS

258       Chad Granum <exodist@cpan.org>
259

AUTHORS

261       Chad Granum <exodist@cpan.org>
262
264       Copyright 2017 Chad Granum <exodist@cpan.org>.
265
266       This program is free software; you can redistribute it and/or modify it
267       under the same terms as Perl itself.
268
269       See http://dev.perl.org/licenses/
270
271
272
273perl v5.38.0                      2023-10-23               Object::HashBase(3)
Impressum