86
89
<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>
87
90
<pre class="verbatim"> <span class="s">{</span>
88
91
<a name="package-Foo"></a> package <span class="i">Foo</span><span class="sc">;</span>
89
<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="fields.html">fields</a> <span class="q">qw(foo bar _Foo_private)</span><span class="sc">;</span>
90
<a name="new"></a> sub <span class="m">new</span> <span class="s">{</span>
91
<a class="l_k" href="functions/my.html">my</a> Foo <span class="i">$self</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span>
92
unless <span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a> <span class="i">$self</span><span class="s">)</span> <span class="s">{</span>
93
<span class="i">$self</span> = <span class="i">fields::new</span><span class="s">(</span><span class="i">$self</span><span class="s">)</span><span class="sc">;</span>
94
<span class="i">$self</span>->{_Foo_private} = <span class="q">"this is Foo's secret"</span><span class="sc">;</span>
95
<span class="s">}</span>
96
<span class="i">$self</span>->{foo} = <span class="n">10</span><span class="sc">;</span>
97
<span class="i">$self</span>->{bar} = <span class="n">20</span><span class="sc">;</span>
98
<a class="l_k" href="functions/return.html">return</a> <span class="i">$self</span><span class="sc">;</span>
99
<span class="s">}</span>
92
<a class="l_k" href="functions/use.html">use</a> <span class="w">fields</span> <span class="q">qw(foo bar _Foo_private)</span><span class="sc">;</span>
93
<a name="new"></a> sub <span class="m">new</span> <span class="s">{</span>
94
<a class="l_k" href="functions/my.html">my</a> <span class="w">Foo</span> <span class="i">$self</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span>
95
unless <span class="s">(</span><a class="l_k" href="functions/ref.html">ref</a> <span class="i">$self</span><span class="s">)</span> <span class="s">{</span>
96
<span class="i">$self</span> = <span class="i">fields::new</span><span class="s">(</span><span class="i">$self</span><span class="s">)</span><span class="sc">;</span>
97
<span class="i">$self</span>->{<span class="w">_Foo_private</span>} = <span class="q">"this is Foo's secret"</span><span class="sc">;</span>
98
<span class="s">}</span>
99
<span class="i">$self</span>->{<span class="w">foo</span>} = <span class="n">10</span><span class="sc">;</span>
100
<span class="i">$self</span>->{<span class="w">bar</span>} = <span class="n">20</span><span class="sc">;</span>
101
<a class="l_k" href="functions/return.html">return</a> <span class="i">$self</span><span class="sc">;</span>
102
<span class="s">}</span>
100
103
<a name="package-main"></a> <span class="s">}</span></pre>
101
<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> <span class="i">$var</span> = Foo->new<span class="sc">;</span>
102
<span class="i">$var</span>->{foo} = <span class="n">42</span><span class="sc">;</span></pre>
104
<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> <span class="i">$var</span> = <span class="w">Foo</span><span class="w">->new</span><span class="sc">;</span>
105
<span class="i">$var</span>->{<span class="w">foo</span>} = <span class="n">42</span><span class="sc">;</span></pre>
103
106
<pre class="verbatim"> <span class="c"># this will generate an error</span>
104
<span class="i">$var</span>->{zap} = <span class="n">42</span><span class="sc">;</span></pre>
107
<span class="i">$var</span>->{<span class="w">zap</span>} = <span class="n">42</span><span class="sc">;</span></pre>
105
108
<pre class="verbatim"> <span class="c"># subclassing</span>
106
109
<span class="s">{</span>
107
110
<a name="package-Bar"></a> package <span class="i">Bar</span><span class="sc">;</span>
108
<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="base.html">base</a> <span class="q">'Foo'</span><span class="sc">;</span>
109
<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="fields.html">fields</a> <span class="q">qw(baz _Bar_private)</span><span class="sc">;</span> <span class="c"># not shared with Foo</span>
110
<a name="new"></a> sub <span class="m">new</span> <span class="s">{</span>
111
<a class="l_k" href="functions/my.html">my</a> <span class="i">$class</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span>
112
<a class="l_k" href="functions/my.html">my</a> <span class="i">$self</span> = <span class="i">fields::new</span><span class="s">(</span><span class="i">$class</span><span class="s">)</span><span class="sc">;</span>
113
<span class="i">$self</span><span class="i">->SUPER::new</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># init base fields</span>
114
<span class="i">$self</span>->{baz} = <span class="n">10</span><span class="sc">;</span> <span class="c"># init own fields</span>
115
<span class="i">$self</span>->{_Bar_private} = <span class="q">"this is Bar's secret"</span><span class="sc">;</span>
116
<a class="l_k" href="functions/return.html">return</a> <span class="i">$self</span><span class="sc">;</span>
117
<span class="s">}</span>
111
<a class="l_k" href="functions/use.html">use</a> <span class="w">base</span> <span class="q">'Foo'</span><span class="sc">;</span>
112
<a class="l_k" href="functions/use.html">use</a> <span class="w">fields</span> <span class="q">qw(baz _Bar_private)</span><span class="sc">;</span> <span class="c"># not shared with Foo</span>
113
<a name="new"></a> sub <span class="m">new</span> <span class="s">{</span>
114
<a class="l_k" href="functions/my.html">my</a> <span class="i">$class</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span>
115
<a class="l_k" href="functions/my.html">my</a> <span class="i">$self</span> = <span class="i">fields::new</span><span class="s">(</span><span class="i">$class</span><span class="s">)</span><span class="sc">;</span>
116
<span class="i">$self</span><span class="i">->SUPER::new</span><span class="s">(</span><span class="s">)</span><span class="sc">;</span> <span class="c"># init base fields</span>
117
<span class="i">$self</span>->{<span class="w">baz</span>} = <span class="n">10</span><span class="sc">;</span> <span class="c"># init own fields</span>
118
<span class="i">$self</span>->{<span class="w">_Bar_private</span>} = <span class="q">"this is Bar's secret"</span><span class="sc">;</span>
119
<a class="l_k" href="functions/return.html">return</a> <span class="i">$self</span><span class="sc">;</span>
120
<span class="s">}</span>
118
121
<a name="package-main"></a> <span class="s">}</span></pre>
119
122
<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>
120
<p>The <code class="inline"><a class="l_w" href="fields.html">fields</a></code> pragma enables compile-time verified class fields.</p>
123
<p>The <code class="inline"><span class="w">fields</span></code>
124
pragma enables compile-time verified class fields.</p>
121
125
<p>NOTE: The current implementation keeps the declared fields in the %FIELDS
122
126
hash of the calling package, but this may change in future versions.
123
127
Do <b>not</b> update the %FIELDS hash directly, because it must be created
127
131
hash element and a package with the same name as the type has
128
132
declared class fields using this pragma, then the operation is
129
133
turned into an array access at compile time.</p>
130
<p>The related <code class="inline"><a class="l_w" href="base.html">base</a></code> pragma will combine fields from base classes and any
131
fields declared using the <code class="inline"><a class="l_w" href="fields.html">fields</a></code> pragma. This enables field
134
<p>The related <code class="inline"><span class="w">base</span></code>
135
pragma will combine fields from base classes and any
136
fields declared using the <code class="inline"><span class="w">fields</span></code>
137
pragma. This enables field
132
138
inheritance to work properly.</p>
133
139
<p>Field names that start with an underscore character are made private to
134
140
the class and are not visible to subclasses. Inherited fields can be
146
152
<li><a name="new"></a><b>new</b>
147
153
<p><b> perl before 5.9.0: </b> fields::new() creates and blesses a
148
pseudo-hash comprised of the fields declared using the <code class="inline"><a class="l_w" href="fields.html">fields</a></code>
154
pseudo-hash comprised of the fields declared using the <code class="inline"><span class="w">fields</span></code>
149
156
pragma into the specified class.</p>
150
157
<p><b> perl 5.9.0 and higher: </b> fields::new() creates and blesses a
151
restricted-hash comprised of the fields declared using the <code class="inline"><a class="l_w" href="fields.html">fields</a></code>
158
restricted-hash comprised of the fields declared using the <code class="inline"><span class="w">fields</span></code>
152
160
pragma into the specified class.</p>
153
161
<p>This function is usable with or without pseudo-hashes. It is the
154
162
recommended way to construct a fields-based object.</p>
155
163
<p>This makes it possible to write a constructor like this:</p>
156
164
<pre class="verbatim"><a name="package-Critter::Sounds"></a> package <span class="i">Critter::Sounds</span><span class="sc">;</span>
157
<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="fields.html">fields</a> <span class="q">qw(cat dog bird)</span><span class="sc">;</span></pre>
165
<a class="l_k" href="functions/use.html">use</a> <span class="w">fields</span> <span class="q">qw(cat dog bird)</span><span class="sc">;</span></pre>
158
166
<pre class="verbatim"><a name="new"></a> sub <span class="m">new</span> <span class="s">{</span>
159
<a class="l_k" href="functions/my.html">my</a> <span class="i">$self</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span>
160
<span class="i">$self</span> = <span class="i">fields::new</span><span class="s">(</span><span class="i">$self</span><span class="s">)</span> unless <a class="l_k" href="functions/ref.html">ref</a> <span class="i">$self</span><span class="sc">;</span>
161
<span class="i">$self</span>->{cat} = <span class="q">'meow'</span><span class="sc">;</span> <span class="c"># scalar element</span>
162
<span class="i">@$self</span>{<span class="q">'dog'</span><span class="cm">,</span><span class="q">'bird'</span>} = <span class="s">(</span><span class="q">'bark'</span><span class="cm">,</span><span class="q">'tweet'</span><span class="s">)</span><span class="sc">;</span> <span class="c"># slice</span>
163
<a class="l_k" href="functions/return.html">return</a> <span class="i">$self</span><span class="sc">;</span>
167
<a class="l_k" href="functions/my.html">my</a> <span class="i">$self</span> = <a class="l_k" href="functions/shift.html">shift</a><span class="sc">;</span>
168
<span class="i">$self</span> = <span class="i">fields::new</span><span class="s">(</span><span class="i">$self</span><span class="s">)</span> unless <a class="l_k" href="functions/ref.html">ref</a> <span class="i">$self</span><span class="sc">;</span>
169
<span class="i">$self</span>->{<span class="w">cat</span>} = <span class="q">'meow'</span><span class="sc">;</span> <span class="c"># scalar element</span>
170
<span class="i">@$self</span>{<span class="q">'dog'</span><span class="cm">,</span><span class="q">'bird'</span>} = <span class="s">(</span><span class="q">'bark'</span><span class="cm">,</span><span class="q">'tweet'</span><span class="s">)</span><span class="sc">;</span> <span class="c"># slice</span>
171
<a class="l_k" href="functions/return.html">return</a> <span class="i">$self</span><span class="sc">;</span>
164
172
<span class="s">}</span></pre>
166
174
<li><a name="phash"></a><b>phash</b>
167
<p><b> before perl 5.9.0: </b> </p>
175
<p><b> before perl 5.9.0: </b></p>
168
176
<p>fields::phash() can be used to create and initialize a plain (unblessed)
169
177
pseudo-hash. This function should always be used instead of creating
170
178
pseudo-hashes directly.</p>
180
188
<span class="s">}</span></pre>
181
189
<p>fields::phash() also accepts a list of key-value pairs that will
182
190
be used to construct the pseudo hash. Examples:</p>
183
<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> <span class="i">$tag</span> = <span class="i">fields::phash</span><span class="s">(</span>name <span class="cm">=></span> <span class="q">"Joe"</span><span class="cm">,</span>
184
rank <span class="cm">=></span> <span class="q">"captain"</span><span class="cm">,</span>
185
ser_num <span class="cm">=></span> <span class="n">42</span><span class="s">)</span><span class="sc">;</span></pre>
191
<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> <span class="i">$tag</span> = <span class="i">fields::phash</span><span class="s">(</span><span class="w">name</span> <span class="cm">=></span> <span class="q">"Joe"</span><span class="cm">,</span>
192
<span class="w">rank</span> <span class="cm">=></span> <span class="q">"captain"</span><span class="cm">,</span>
193
<span class="w">ser_num</span> <span class="cm">=></span> <span class="n">42</span><span class="s">)</span><span class="sc">;</span></pre>
186
194
<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> <span class="i">$pseudohash</span> = <span class="i">fields::phash</span><span class="s">(</span><span class="i">%args</span><span class="s">)</span><span class="sc">;</span></pre>
187
195
<p><b> perl 5.9.0 and higher: </b></p>
188
196
<p>Pseudo-hashes have been removed from Perl as of 5.10. Consider using
added
removed
fields.html
