1Object::HashBase(3) User Contributed Perl Documentation Object::HashBase(3)
2
6 Object::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 Object::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 Object::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 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
97 If you want to use HashBase, but do not want to depend on it, you can
98 include it in your distribution.
99 $ hashbase_inc.pl Prefix::For::Module
101 This will create 2 files:
103 lib/Prefix/For/Module/HashBase.pm
105 t/HashBase.t
106 You can then use the includes "Prefix::For::Module::HashBase" instead
108 of "Object::HashBase".
109 You can re-run this script to regenerate the files, or upgrade them to
111 newer versions.
112 If the script was not installed, it can be found in the "scripts/"
114 directory.
115
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 HashBase will not export new() if there is already a new() method
124 in your packages inheritance chain.
125 If you do not want this method you can define your own you just
127 have to declare it before loading Object::HashBase.
128 package My::Package;
130 # predeclare new() so that HashBase does not give us one.
132 sub new;
133 use Object::HashBase qw/foo bar baz/;
135 # Now we define our own new method.
137 sub new { ... }
138 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 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 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 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 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 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
176 READ/WRITE
177 To generate accessors you list them when using the module:
178 use Object::HashBase qw/foo/;
180 This will generate the following subs in your namespace:
182 foo()
184 Getter, used to get the value of the "foo" field.
185 set_foo()
187 Setter, used to set the value of the "foo" field.
188 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 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 READ ONLY
199 use Object::HashBase qw/-foo/;
200 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 DEPRECATED SETTER
207 use Object::HashBase qw/^foo/;
208 set_foo()
210 This will set the value, but it will also warn you that the method
211 is deprecated.
212 NO SETTER
214 use Object::HashBase qw/<foo/;
215 Only gives you a reader, no "set_foo" method is defined at all.
217 NO READER
219 use Object::HashBase qw/>foo/;
220 Only gives you a write ("set_foo"), no "foo" method is defined at all.
222 CONSTANT ONLY
224 use Object::HashBase qw/+foo/;
225 This does not create any methods for you, it just adds the "FOO"
227 constant.
228
230 You can subclass an existing HashBase class.
231 use base 'Another::HashBase::Class';
233 use Object::HashBase qw/foo bar baz/;
234 The base class is added to @ISA for you, and all constants from base
236 classes are added to subclasses automatically.
237
239 Object::HashBase provides a function for retrieving a list of
240 attributes for an Object::HashBase class.
241 @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 Note: This list is used in the "$class->new(\@ARRAY)" constructor
251 to determine the attribute to which each value will be paired.
252
254 The source code repository for HashBase can be found at
255 http://github.com/Test-More/HashBase/.
256
258 Chad Granum <exodist@cpan.org>
259
261 Chad Granum <exodist@cpan.org>
262
264 Copyright 2017 Chad Granum <exodist@cpan.org>.
265 This program is free software; you can redistribute it and/or modify it
267 under the same terms as Perl itself.
268 See http://dev.perl.org/licenses/
270perl v5.38.0 2023-10-23 Object::HashBase(3)