diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Test2::Util::HashBase.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Test2::Util::HashBase.3pm | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Test2::Util::HashBase.3pm b/upstream/mageia-cauldron/man3pm/Test2::Util::HashBase.3pm new file mode 100644 index 00000000..1ca63e49 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Test2::Util::HashBase.3pm @@ -0,0 +1,346 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Test2::Util::HashBase 3pm" +.TH Test2::Util::HashBase 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Test2::Util::HashBase \- Build hash based classes. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +A class: +.PP +.Vb 3 +\& package My::Class; +\& use strict; +\& use warnings; +\& +\& # Generate 3 accessors +\& use Test2::Util::HashBase qw/foo \-bar ^baz <bat >ban +boo/; +\& +\& # Chance to initialize defaults +\& sub init { +\& my $self = shift; # No other args +\& $self\->{+FOO} ||= "foo"; +\& $self\->{+BAR} ||= "bar"; +\& $self\->{+BAZ} ||= "baz"; +\& $self\->{+BAT} ||= "bat"; +\& $self\->{+BAN} ||= "ban"; +\& $self\->{+BOO} ||= "boo"; +\& } +\& +\& sub print { +\& print join ", " => map { $self\->{$_} } FOO, BAR, BAZ, BAT, BAN, BOO; +\& } +.Ve +.PP +Subclass it +.PP +.Vb 3 +\& package My::Subclass; +\& use strict; +\& use warnings; +\& +\& # Note, you should subclass before loading HashBase. +\& use base \*(AqMy::Class\*(Aq; +\& use Test2::Util::HashBase qw/bub/; +\& +\& sub init { +\& my $self = shift; +\& +\& # We get the constants from the base class for free. +\& $self\->{+FOO} ||= \*(AqSubFoo\*(Aq; +\& $self\->{+BUB} ||= \*(Aqbub\*(Aq; +\& +\& $self\->SUPER::init(); +\& } +.Ve +.PP +use it: +.PP +.Vb 4 +\& package main; +\& use strict; +\& use warnings; +\& use My::Class; +\& +\& # These are all functionally identical +\& my $one = My::Class\->new(foo => \*(AqMyFoo\*(Aq, bar => \*(AqMyBar\*(Aq); +\& my $two = My::Class\->new({foo => \*(AqMyFoo\*(Aq, bar => \*(AqMyBar\*(Aq}); +\& my $three = My::Class\->new([\*(AqMyFoo\*(Aq, \*(AqMyBar\*(Aq]); +\& +\& # Readers! +\& my $foo = $one\->foo; # \*(AqMyFoo\*(Aq +\& my $bar = $one\->bar; # \*(AqMyBar\*(Aq +\& my $baz = $one\->baz; # Defaulted to: \*(Aqbaz\*(Aq +\& my $bat = $one\->bat; # Defaulted to: \*(Aqbat\*(Aq +\& # \*(Aq>ban\*(Aq means setter only, no reader +\& # \*(Aq+boo\*(Aq means no setter or reader, just the BOO constant +\& +\& # Setters! +\& $one\->set_foo(\*(AqA Foo\*(Aq); +\& +\& #\*(Aq\-bar\*(Aq means read\-only, so the setter will throw an exception (but is defined). +\& $one\->set_bar(\*(AqA bar\*(Aq); +\& +\& # \*(Aq^baz\*(Aq means deprecated setter, this will warn about the setter being +\& # deprecated. +\& $one\->set_baz(\*(AqA Baz\*(Aq); +\& +\& # \*(Aq<bat\*(Aq means no setter defined at all +\& # \*(Aq+boo\*(Aq means no setter or reader, just the BOO constant +\& +\& $one\->{+FOO} = \*(Aqxxx\*(Aq; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This package is used to generate classes based on hashrefs. Using this class +will give you a \f(CWnew()\fR method, as well as generating accessors you request. +Generated accessors will be getters, \f(CW\*(C`set_ACCESSOR\*(C'\fR setters will also be +generated for you. You also get constants for each accessor (all caps) which +return the key into the hash for that accessor. Single inheritance is also +supported. +.SH "THIS IS A BUNDLED COPY OF HASHBASE" +.IX Header "THIS IS A BUNDLED COPY OF HASHBASE" +This is a bundled copy of Object::HashBase. This file was generated using +the +\&\f(CW\*(C`/home/exodist/perl5/perlbrew/perls/main/bin/hashbase_inc.pl\*(C'\fR +script. +.SH METHODS +.IX Header "METHODS" +.SS "PROVIDED BY HASH BASE" +.IX Subsection "PROVIDED BY HASH BASE" +.ie n .IP "$it = $class\->new(%PAIRS)" 4 +.el .IP "\f(CW$it\fR = \f(CW$class\fR\->new(%PAIRS)" 4 +.IX Item "$it = $class->new(%PAIRS)" +.PD 0 +.ie n .IP "$it = $class\->new(\e%PAIRS)" 4 +.el .IP "\f(CW$it\fR = \f(CW$class\fR\->new(\e%PAIRS)" 4 +.IX Item "$it = $class->new(%PAIRS)" +.ie n .IP "$it = $class\->new(\e@ORDERED_VALUES)" 4 +.el .IP "\f(CW$it\fR = \f(CW$class\fR\->new(\e@ORDERED_VALUES)" 4 +.IX Item "$it = $class->new(@ORDERED_VALUES)" +.PD +Create a new instance. +.Sp +HashBase will not export \f(CWnew()\fR if there is already a \f(CWnew()\fR method in your +packages inheritance chain. +.Sp +\&\fBIf you do not want this method you can define your own\fR you just have to +declare it before loading Test2::Util::HashBase. +.Sp +.Vb 1 +\& package My::Package; +\& +\& # predeclare new() so that HashBase does not give us one. +\& sub new; +\& +\& use Test2::Util::HashBase qw/foo bar baz/; +\& +\& # Now we define our own new method. +\& sub new { ... } +.Ve +.Sp +This makes it so that HashBase sees that you have your own \f(CWnew()\fR method. +Alternatively you can define the method before loading HashBase instead of just +declaring it, but that scatters your use statements. +.Sp +The most common way to create an object is to pass in key/value pairs where +each key is an attribute and each value is what you want assigned to that +attribute. No checking is done to verify the attributes or values are valid, +you may do that in \f(CWinit()\fR if desired. +.Sp +If you would like, you can pass in a hashref instead of pairs. When you do so +the hashref will be copied, and the copy will be returned blessed as an object. +There is no way to ask HashBase to bless a specific hashref. +.Sp +In some cases an object may only have 1 or 2 attributes, in which case a +hashref may be too verbose for your liking. In these cases you can pass in an +arrayref with only values. The values will be assigned to attributes in the +order the attributes were listed. When there is inheritance involved the +attributes from parent classes will come before subclasses. +.SS HOOKS +.IX Subsection "HOOKS" +.ie n .IP $self\->\fBinit()\fR 4 +.el .IP \f(CW$self\fR\->\fBinit()\fR 4 +.IX Item "$self->init()" +This gives you the chance to set some default values to your fields. The only +argument is \f(CW$self\fR with its indexes already set from the constructor. +.Sp +\&\fBNote:\fR Test2::Util::HashBase checks for an init using \f(CW\*(C`$class\->can(\*(Aqinit\*(Aq)\*(C'\fR +during construction. It DOES NOT call \f(CWcan()\fR on the created object. Also note +that the result of the check is cached, it is only ever checked once, the first +time an instance of your class is created. This means that adding an \f(CWinit()\fR +method AFTER the first construction will result in it being ignored. +.SH ACCESSORS +.IX Header "ACCESSORS" +.SS READ/WRITE +.IX Subsection "READ/WRITE" +To generate accessors you list them when using the module: +.PP +.Vb 1 +\& use Test2::Util::HashBase qw/foo/; +.Ve +.PP +This will generate the following subs in your namespace: +.IP \fBfoo()\fR 4 +.IX Item "foo()" +Getter, used to get the value of the \f(CW\*(C`foo\*(C'\fR field. +.IP \fBset_foo()\fR 4 +.IX Item "set_foo()" +Setter, used to set the value of the \f(CW\*(C`foo\*(C'\fR field. +.IP \fBFOO()\fR 4 +.IX Item "FOO()" +Constant, returns the field \f(CW\*(C`foo\*(C'\fR's key into the class hashref. Subclasses will +also get this function as a constant, not simply a method, that means it is +copied into the subclass namespace. +.Sp +The main reason for using these constants is to help avoid spelling mistakes +and similar typos. It will not help you if you forget to prefix the '+' though. +.SS "READ ONLY" +.IX Subsection "READ ONLY" +.Vb 1 +\& use Test2::Util::HashBase qw/\-foo/; +.Ve +.IP \fBset_foo()\fR 4 +.IX Item "set_foo()" +Throws an exception telling you the attribute is read-only. This is exported to +override any active setters for the attribute in a parent class. +.SS "DEPRECATED SETTER" +.IX Subsection "DEPRECATED SETTER" +.Vb 1 +\& use Test2::Util::HashBase qw/^foo/; +.Ve +.IP \fBset_foo()\fR 4 +.IX Item "set_foo()" +This will set the value, but it will also warn you that the method is +deprecated. +.SS "NO SETTER" +.IX Subsection "NO SETTER" +.Vb 1 +\& use Test2::Util::HashBase qw/<foo/; +.Ve +.PP +Only gives you a reader, no \f(CW\*(C`set_foo\*(C'\fR method is defined at all. +.SS "NO READER" +.IX Subsection "NO READER" +.Vb 1 +\& use Test2::Util::HashBase qw/>foo/; +.Ve +.PP +Only gives you a write (\f(CW\*(C`set_foo\*(C'\fR), no \f(CW\*(C`foo\*(C'\fR method is defined at all. +.SS "CONSTANT ONLY" +.IX Subsection "CONSTANT ONLY" +.Vb 1 +\& use Test2::Util::HashBase qw/+foo/; +.Ve +.PP +This does not create any methods for you, it just adds the \f(CW\*(C`FOO\*(C'\fR constant. +.SH SUBCLASSING +.IX Header "SUBCLASSING" +You can subclass an existing HashBase class. +.PP +.Vb 2 +\& use base \*(AqAnother::HashBase::Class\*(Aq; +\& use Test2::Util::HashBase qw/foo bar baz/; +.Ve +.PP +The base class is added to \f(CW@ISA\fR for you, and all constants from base classes +are added to subclasses automatically. +.SH "GETTING A LIST OF ATTRIBUTES FOR A CLASS" +.IX Header "GETTING A LIST OF ATTRIBUTES FOR A CLASS" +Test2::Util::HashBase provides a function for retrieving a list of attributes for an +Test2::Util::HashBase class. +.ie n .IP "@list = Test2::Util::HashBase::attr_list($class)" 4 +.el .IP "\f(CW@list\fR = Test2::Util::HashBase::attr_list($class)" 4 +.IX Item "@list = Test2::Util::HashBase::attr_list($class)" +.PD 0 +.ie n .IP "@list = $class\->\fBTest2::Util::HashBase::attr_list()\fR" 4 +.el .IP "\f(CW@list\fR = \f(CW$class\fR\->\fBTest2::Util::HashBase::attr_list()\fR" 4 +.IX Item "@list = $class->Test2::Util::HashBase::attr_list()" +.PD +Either form above will work. This will return a list of attributes defined on +the object. This list is returned in the attribute definition order, parent +class attributes are listed before subclass attributes. Duplicate attributes +will be removed before the list is returned. +.Sp +\&\fBNote:\fR This list is used in the \f(CW\*(C`$class\->new(\e@ARRAY)\*(C'\fR constructor to +determine the attribute to which each value will be paired. +.SH SOURCE +.IX Header "SOURCE" +The source code repository for HashBase can be found at +\&\fIhttp://github.com/Test\-More/HashBase/\fR. +.SH MAINTAINERS +.IX Header "MAINTAINERS" +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.SH AUTHORS +.IX Header "AUTHORS" +.PD 0 +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.PD +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017 Chad Granum <exodist@cpan.org>. +.PP +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.PP +See \fIhttp://dev.perl.org/licenses/\fR |