Debian Codegraph @

upstream/debian-unstable/man3/Term::Table::HashBase.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Term::Table::HashBase 3perl"
58 .TH Term::Table::HashBase 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Term::Table::HashBase \- Build hash based classes.
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 A class:
68 .PP
69 .Vb 3
70 \& package My::Class;
71 \& use strict;
72 \& use warnings;
73 \&
74 \& # Generate 3 accessors
75 \& use Term::Table::HashBase qw/foo \-bar ^baz <bat >ban +boo/;
76 \&
77 \& # Chance to initialize defaults
78 \& sub init {
79 \& my $self = shift; # No other args
80 \& $self\->{+FOO} ||= "foo";
81 \& $self\->{+BAR} ||= "bar";
82 \& $self\->{+BAZ} ||= "baz";
83 \& $self\->{+BAT} ||= "bat";
84 \& $self\->{+BAN} ||= "ban";
85 \& $self\->{+BOO} ||= "boo";
86 \& }
87 \&
88 \& sub print {
89 \& print join ", " => map { $self\->{$_} } FOO, BAR, BAZ, BAT, BAN, BOO;
90 \& }
91 .Ve
92 .PP
93 Subclass it
94 .PP
95 .Vb 3
96 \& package My::Subclass;
97 \& use strict;
98 \& use warnings;
99 \&
100 \& # Note, you should subclass before loading HashBase.
101 \& use base \*(AqMy::Class\*(Aq;
102 \& use Term::Table::HashBase qw/bub/;
103 \&
104 \& sub init {
105 \& my $self = shift;
106 \&
107 \& # We get the constants from the base class for free.
108 \& $self\->{+FOO} ||= \*(AqSubFoo\*(Aq;
109 \& $self\->{+BUB} ||= \*(Aqbub\*(Aq;
110 \&
111 \& $self\->SUPER::init();
112 \& }
113 .Ve
114 .PP
115 use it:
116 .PP
117 .Vb 4
118 \& package main;
119 \& use strict;
120 \& use warnings;
121 \& use My::Class;
122 \&
123 \& # These are all functionally identical
124 \& my $one = My::Class\->new(foo => \*(AqMyFoo\*(Aq, bar => \*(AqMyBar\*(Aq);
125 \& my $two = My::Class\->new({foo => \*(AqMyFoo\*(Aq, bar => \*(AqMyBar\*(Aq});
126 \& my $three = My::Class\->new([\*(AqMyFoo\*(Aq, \*(AqMyBar\*(Aq]);
127 \&
128 \& # Readers!
129 \& my $foo = $one\->foo; # \*(AqMyFoo\*(Aq
130 \& my $bar = $one\->bar; # \*(AqMyBar\*(Aq
131 \& my $baz = $one\->baz; # Defaulted to: \*(Aqbaz\*(Aq
132 \& my $bat = $one\->bat; # Defaulted to: \*(Aqbat\*(Aq
133 \& # \*(Aq>ban\*(Aq means setter only, no reader
134 \& # \*(Aq+boo\*(Aq means no setter or reader, just the BOO constant
135 \&
136 \& # Setters!
137 \& $one\->set_foo(\*(AqA Foo\*(Aq);
138 \&
139 \& #\*(Aq\-bar\*(Aq means read\-only, so the setter will throw an exception (but is defined).
140 \& $one\->set_bar(\*(AqA bar\*(Aq);
141 \&
142 \& # \*(Aq^baz\*(Aq means deprecated setter, this will warn about the setter being
143 \& # deprecated.
144 \& $one\->set_baz(\*(AqA Baz\*(Aq);
145 \&
146 \& # \*(Aq<bat\*(Aq means no setter defined at all
147 \& # \*(Aq+boo\*(Aq means no setter or reader, just the BOO constant
148 \&
149 \& $one\->{+FOO} = \*(Aqxxx\*(Aq;
150 .Ve
151 .SH DESCRIPTION
152 .IX Header "DESCRIPTION"
153 This package is used to generate classes based on hashrefs. Using this class
154 will give you a \f(CWnew()\fR method, as well as generating accessors you request.
155 Generated accessors will be getters, \f(CW\*(C`set_ACCESSOR\*(C'\fR setters will also be
156 generated for you. You also get constants for each accessor (all caps) which
157 return the key into the hash for that accessor. Single inheritance is also
158 supported.
159 .SH "THIS IS A BUNDLED COPY OF HASHBASE"
160 .IX Header "THIS IS A BUNDLED COPY OF HASHBASE"
161 This is a bundled copy of Object::HashBase. This file was generated using
162 the
163 \&\f(CW\*(C`/home/exodist/perl5/perlbrew/perls/main/bin/hashbase_inc.pl\*(C'\fR
164 script.
165 .SH METHODS
166 .IX Header "METHODS"
167 .SS "PROVIDED BY HASH BASE"
168 .IX Subsection "PROVIDED BY HASH BASE"
169 .ie n .IP "$it = $class\->new(%PAIRS)" 4
170 .el .IP "\f(CW$it\fR = \f(CW$class\fR\->new(%PAIRS)" 4
171 .IX Item "$it = $class->new(%PAIRS)"
172 .PD 0
173 .ie n .IP "$it = $class\->new(\e%PAIRS)" 4
174 .el .IP "\f(CW$it\fR = \f(CW$class\fR\->new(\e%PAIRS)" 4
175 .IX Item "$it = $class->new(%PAIRS)"
176 .ie n .IP "$it = $class\->new(\e@ORDERED_VALUES)" 4
177 .el .IP "\f(CW$it\fR = \f(CW$class\fR\->new(\e@ORDERED_VALUES)" 4
178 .IX Item "$it = $class->new(@ORDERED_VALUES)"
179 .PD
180 Create a new instance.
181 .Sp
182 HashBase will not export \f(CWnew()\fR if there is already a \f(CWnew()\fR method in your
183 packages inheritance chain.
184 .Sp
185 \&\fBIf you do not want this method you can define your own\fR you just have to
186 declare it before loading Term::Table::HashBase.
187 .Sp
188 .Vb 1
189 \& package My::Package;
190 \&
191 \& # predeclare new() so that HashBase does not give us one.
192 \& sub new;
193 \&
194 \& use Term::Table::HashBase qw/foo bar baz/;
195 \&
196 \& # Now we define our own new method.
197 \& sub new { ... }
198 .Ve
199 .Sp
200 This makes it so that HashBase sees that you have your own \f(CWnew()\fR method.
201 Alternatively you can define the method before loading HashBase instead of just
202 declaring it, but that scatters your use statements.
203 .Sp
204 The most common way to create an object is to pass in key/value pairs where
205 each key is an attribute and each value is what you want assigned to that
206 attribute. No checking is done to verify the attributes or values are valid,
207 you may do that in \f(CWinit()\fR if desired.
208 .Sp
209 If you would like, you can pass in a hashref instead of pairs. When you do so
210 the hashref will be copied, and the copy will be returned blessed as an object.
211 There is no way to ask HashBase to bless a specific hashref.
212 .Sp
213 In some cases an object may only have 1 or 2 attributes, in which case a
214 hashref may be too verbose for your liking. In these cases you can pass in an
215 arrayref with only values. The values will be assigned to attributes in the
216 order the attributes were listed. When there is inheritance involved the
217 attributes from parent classes will come before subclasses.
218 .SS HOOKS
219 .IX Subsection "HOOKS"
220 .ie n .IP $self\->\fBinit()\fR 4
221 .el .IP \f(CW$self\fR\->\fBinit()\fR 4
222 .IX Item "$self->init()"
223 This gives you the chance to set some default values to your fields. The only
224 argument is \f(CW$self\fR with its indexes already set from the constructor.
225 .Sp
226 \&\fBNote:\fR Term::Table::HashBase checks for an init using \f(CW\*(C`$class\->can(\*(Aqinit\*(Aq)\*(C'\fR
227 during construction. It DOES NOT call \f(CWcan()\fR on the created object. Also note
228 that the result of the check is cached, it is only ever checked once, the first
229 time an instance of your class is created. This means that adding an \f(CWinit()\fR
230 method AFTER the first construction will result in it being ignored.
231 .SH ACCESSORS
232 .IX Header "ACCESSORS"
233 .SS READ/WRITE
234 .IX Subsection "READ/WRITE"
235 To generate accessors you list them when using the module:
236 .PP
237 .Vb 1
238 \& use Term::Table::HashBase qw/foo/;
239 .Ve
240 .PP
241 This will generate the following subs in your namespace:
242 .IP \fBfoo()\fR 4
243 .IX Item "foo()"
244 Getter, used to get the value of the \f(CW\*(C`foo\*(C'\fR field.
245 .IP \fBset_foo()\fR 4
246 .IX Item "set_foo()"
247 Setter, used to set the value of the \f(CW\*(C`foo\*(C'\fR field.
248 .IP \fBFOO()\fR 4
249 .IX Item "FOO()"
250 Constant, returns the field \f(CW\*(C`foo\*(C'\fR's key into the class hashref. Subclasses will
251 also get this function as a constant, not simply a method, that means it is
252 copied into the subclass namespace.
253 .Sp
254 The main reason for using these constants is to help avoid spelling mistakes
255 and similar typos. It will not help you if you forget to prefix the '+' though.
256 .SS "READ ONLY"
257 .IX Subsection "READ ONLY"
258 .Vb 1
259 \& use Term::Table::HashBase qw/\-foo/;
260 .Ve
261 .IP \fBset_foo()\fR 4
262 .IX Item "set_foo()"
263 Throws an exception telling you the attribute is read-only. This is exported to
264 override any active setters for the attribute in a parent class.
265 .SS "DEPRECATED SETTER"
266 .IX Subsection "DEPRECATED SETTER"
267 .Vb 1
268 \& use Term::Table::HashBase qw/^foo/;
269 .Ve
270 .IP \fBset_foo()\fR 4
271 .IX Item "set_foo()"
272 This will set the value, but it will also warn you that the method is
273 deprecated.
274 .SS "NO SETTER"
275 .IX Subsection "NO SETTER"
276 .Vb 1
277 \& use Term::Table::HashBase qw/<foo/;
278 .Ve
279 .PP
280 Only gives you a reader, no \f(CW\*(C`set_foo\*(C'\fR method is defined at all.
281 .SS "NO READER"
282 .IX Subsection "NO READER"
283 .Vb 1
284 \& use Term::Table::HashBase qw/>foo/;
285 .Ve
286 .PP
287 Only gives you a write (\f(CW\*(C`set_foo\*(C'\fR), no \f(CW\*(C`foo\*(C'\fR method is defined at all.
288 .SS "CONSTANT ONLY"
289 .IX Subsection "CONSTANT ONLY"
290 .Vb 1
291 \& use Term::Table::HashBase qw/+foo/;
292 .Ve
293 .PP
294 This does not create any methods for you, it just adds the \f(CW\*(C`FOO\*(C'\fR constant.
295 .SH SUBCLASSING
296 .IX Header "SUBCLASSING"
297 You can subclass an existing HashBase class.
298 .PP
299 .Vb 2
300 \& use base \*(AqAnother::HashBase::Class\*(Aq;
301 \& use Term::Table::HashBase qw/foo bar baz/;
302 .Ve
303 .PP
304 The base class is added to \f(CW@ISA\fR for you, and all constants from base classes
305 are added to subclasses automatically.
306 .SH "GETTING A LIST OF ATTRIBUTES FOR A CLASS"
307 .IX Header "GETTING A LIST OF ATTRIBUTES FOR A CLASS"
308 Term::Table::HashBase provides a function for retrieving a list of attributes for an
309 Term::Table::HashBase class.
310 .ie n .IP "@list = Term::Table::HashBase::attr_list($class)" 4
311 .el .IP "\f(CW@list\fR = Term::Table::HashBase::attr_list($class)" 4
312 .IX Item "@list = Term::Table::HashBase::attr_list($class)"
313 .PD 0
314 .ie n .IP "@list = $class\->\fBTerm::Table::HashBase::attr_list()\fR" 4
315 .el .IP "\f(CW@list\fR = \f(CW$class\fR\->\fBTerm::Table::HashBase::attr_list()\fR" 4
316 .IX Item "@list = $class->Term::Table::HashBase::attr_list()"
317 .PD
318 Either form above will work. This will return a list of attributes defined on
319 the object. This list is returned in the attribute definition order, parent
320 class attributes are listed before subclass attributes. Duplicate attributes
321 will be removed before the list is returned.
322 .Sp
323 \&\fBNote:\fR This list is used in the \f(CW\*(C`$class\->new(\e@ARRAY)\*(C'\fR constructor to
324 determine the attribute to which each value will be paired.
325 .SH SOURCE
326 .IX Header "SOURCE"
327 The source code repository for HashBase can be found at
328 \&\fIhttp://github.com/Test\-More/HashBase/\fR.
329 .SH MAINTAINERS
330 .IX Header "MAINTAINERS"
331 .IP "Chad Granum <[email protected]>" 4
332 .IX Item "Chad Granum <[email protected]>"
333 .SH AUTHORS
334 .IX Header "AUTHORS"
335 .PD 0
336 .IP "Chad Granum <[email protected]>" 4
337 .IX Item "Chad Granum <[email protected]>"
338 .PD
339 .SH COPYRIGHT
340 .IX Header "COPYRIGHT"
341 Copyright 2017 Chad Granum <[email protected]>.
342 .PP
343 This program is free software; you can redistribute it and/or
344 modify it under the same terms as Perl itself.
345 .PP
346 See \fIhttp://dev.perl.org/licenses/\fR