Debian Codegraph @

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