Debian Codegraph @

upstream/opensuse-tumbleweed/man3/fields.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "fields 3pm"
61 .TH fields 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 fields \- compile\-time class fields
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 10
71 \& {
72 \& package Foo;
73 \& use fields qw(foo bar _Foo_private);
74 \& sub new {
75 \& my Foo $self = shift;
76 \& unless (ref $self) {
77 \& $self = fields::new($self);
78 \& $self\->{_Foo_private} = "this is Foo\*(Aqs secret";
79 \& }
80 \& $self\->{foo} = 10;
81 \& $self\->{bar} = 20;
82 \& return $self;
83 \& }
84 \& }
85 \&
86 \& my $var = Foo\->new;
87 \& $var\->{foo} = 42;
88 \&
89 \& # this will generate a run\-time error
90 \& $var\->{zap} = 42;
91 \&
92 \& # this will generate a compile\-time error
93 \& my Foo $foo = Foo\->new;
94 \& $foo\->{zap} = 24;
95 \&
96 \& # subclassing
97 \& {
98 \& package Bar;
99 \& use base \*(AqFoo\*(Aq;
100 \& use fields qw(baz _Bar_private); # not shared with Foo
101 \& sub new {
102 \& my $class = shift;
103 \& my $self = fields::new($class);
104 \& $self\->SUPER::new(); # init base fields
105 \& $self\->{baz} = 10; # init own fields
106 \& $self\->{_Bar_private} = "this is Bar\*(Aqs secret";
107 \& return $self;
108 \& }
109 \& }
110 .Ve
111 .SH DESCRIPTION
112 .IX Header "DESCRIPTION"
113 The \f(CW\*(C`fields\*(C'\fR pragma enables compile\-time and run\-time verified class
114 fields.
115 .PP
116 NOTE: The current implementation keeps the declared fields in the \f(CW%FIELDS\fR
117 hash of the calling package, but this may change in future versions.
118 Do \fBnot\fR update the \f(CW%FIELDS\fR hash directly, because it must be created
119 at compile\-time for it to be fully useful, as is done by this pragma.
120 .PP
121 If a typed lexical variable (\f(CWmy Class
122 $var\fR) holding a reference is used to access a
123 hash element and a package with the same name as the type has
124 declared class fields using this pragma, then the hash key is
125 verified at compile time. If the variables are not typed, access is
126 only checked at run time.
127 .PP
128 The related \f(CW\*(C`base\*(C'\fR pragma will combine fields from base classes and any
129 fields declared using the \f(CW\*(C`fields\*(C'\fR pragma. This enables field
130 inheritance to work properly. Inherited fields can be overridden but
131 will generate a warning if warnings are enabled.
132 .PP
133 \&\fBOnly valid for Perl 5.8.x and earlier:\fR Field names that start with an
134 underscore character are made private to the class and are not visible
135 to subclasses.
136 .PP
137 Also, \fBin Perl 5.8.x and earlier\fR, this pragma uses pseudo\-hashes, the
138 effect being that you can have objects with named fields which are as
139 compact and fast as arrays to access, as long as the objects are
140 accessed through properly typed variables.
141 .PP
142 The following functions are supported:
143 .IP new 4
144 .IX Item "new"
145 \&\fBfields::new()\fR creates and blesses a hash of the fields declared
146 using the \f(CW\*(C`fields\*(C'\fR pragma into the specified class. It is the
147 recommended way to construct a fields\-based object.
148 .Sp
149 This makes it possible to write a constructor like this:
150 .Sp
151 .Vb 2
152 \& package Critter::Sounds;
153 \& use fields qw(cat dog bird);
154 \&
155 \& sub new {
156 \& my $self = shift;
157 \& $self = fields::new($self) unless ref $self;
158 \& $self\->{cat} = \*(Aqmeow\*(Aq; # scalar element
159 \& @$self{\*(Aqdog\*(Aq,\*(Aqbird\*(Aq} = (\*(Aqbark\*(Aq,\*(Aqtweet\*(Aq); # slice
160 \& return $self;
161 \& }
162 .Ve
163 .IP phash 4
164 .IX Item "phash"
165 \&\fBThis function only works in Perl 5.8.x and earlier.\fR Pseudo\-hashes
166 were removed from Perl as of 5.10. Consider using restricted hashes or
167 \&\fBfields::new()\fR instead (which itself uses restricted hashes under 5.10+).
168 See Hash::Util. Using \fBfields::phash()\fR under 5.10 or higher will
169 cause an error.
170 .Sp
171 \&\fBfields::phash()\fR can be used to create and initialize a plain (unblessed)
172 pseudo\-hash. This function should always be used instead of creating
173 pseudo\-hashes directly.
174 .Sp
175 If the first argument is a reference to an array, the pseudo\-hash will
176 be created with keys from that array. If a second argument is supplied,
177 it must also be a reference to an array whose elements will be used as
178 the values. If the second array contains fewer elements than the first,
179 the trailing elements of the pseudo\-hash will not be initialized.
180 This makes it particularly useful for creating a pseudo\-hash from
181 subroutine arguments:
182 .Sp
183 .Vb 3
184 \& sub dogtag {
185 \& my $tag = fields::phash([qw(name rank ser_num)], [@_]);
186 \& }
187 .Ve
188 .Sp
189 \&\fBfields::phash()\fR also accepts a list of key\-value pairs that will
190 be used to construct the pseudo hash. Examples:
191 .Sp
192 .Vb 3
193 \& my $tag = fields::phash(name => "Joe",
194 \& rank => "captain",
195 \& ser_num => 42);
196 \&
197 \& my $pseudohash = fields::phash(%args);
198 .Ve
199 .SH "SEE ALSO"
200 .IX Header "SEE ALSO"
201 base, Hash::Util