mingw/html/lib/fields.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>fields - compile-time class fields</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;fields - compile-time class fields</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#see_also">SEE ALSO</a></li>
  26 </ul>
  27 <!-- INDEX END -->
  28
  29 <hr />
  30 <p>
  31 </p>
  32 <h1><a name="name">NAME</a></h1>
  33 <p>fields - compile-time class fields</p>
  34 <p>
  35 </p>
  36 <hr />
  37 <h1><a name="synopsis">SYNOPSIS</a></h1>
  38 <pre>
  39     {
  40         package Foo;
  41         use fields qw(foo bar _Foo_private);
  42         sub new {
  43             my Foo $self = shift;
  44             unless (ref $self) {
  45                 $self = fields::new($self);
  46                 $self-&gt;{_Foo_private} = &quot;this is Foo's secret&quot;;
  47             }
  48             $self-&gt;{foo} = 10;
  49             $self-&gt;{bar} = 20;
  50             return $self;
  51         }
  52     }</pre>
  53 <pre>
  54     my $var = Foo-&gt;new;
  55     $var-&gt;{foo} = 42;</pre>
  56 <pre>
  57     # this will generate an error
  58     $var-&gt;{zap} = 42;</pre>
  59 <pre>
  60     # subclassing
  61     {
  62         package Bar;
  63         use base 'Foo';
  64         use fields qw(baz _Bar_private);        # not shared with Foo
  65         sub new {
  66             my $class = shift;
  67             my $self = fields::new($class);
  68             $self-&gt;SUPER::new();                # init base fields
  69             $self-&gt;{baz} = 10;                  # init own fields
  70             $self-&gt;{_Bar_private} = &quot;this is Bar's secret&quot;;
  71             return $self;
  72         }
  73     }</pre>
  74 <p>
  75 </p>
  76 <hr />
  77 <h1><a name="description">DESCRIPTION</a></h1>
  78 <p>The <code>fields</code> pragma enables compile-time verified class fields.</p>
  79 <p>NOTE: The current implementation keeps the declared fields in the %FIELDS
  80 hash of the calling package, but this may change in future versions.
  81 Do <strong>not</strong> update the %FIELDS hash directly, because it must be created
  82 at compile-time for it to be fully useful, as is done by this pragma.</p>
  83 <p><strong>Only valid for perl before 5.9.0:</strong></p>
  84 <p>If a typed lexical variable holding a reference is used to access a
  85 hash element and a package with the same name as the type has
  86 declared class fields using this pragma, then the operation is
  87 turned into an array access at compile time.</p>
  88 <p>The related <code>base</code> pragma will combine fields from base classes and any
  89 fields declared using the <code>fields</code> pragma.  This enables field
  90 inheritance to work properly.</p>
  91 <p>Field names that start with an underscore character are made private to
  92 the class and are not visible to subclasses.  Inherited fields can be
  93 overridden but will generate a warning if used together with the <code>-w</code>
  94 switch.</p>
  95 <p><strong>Only valid for perls before 5.9.0:</strong></p>
  96 <p>The effect of all this is that you can have objects with named
  97 fields which are as compact and as fast arrays to access. This only
  98 works as long as the objects are accessed through properly typed
  99 variables. If the objects are not typed, access is only checked at
 100 run time.</p>
 101 <p>The following functions are supported:</p>
 102 <dl>
 103 <dt><strong><a name="item_new">new</a></strong>
 104
 105 <dd>
 106 <p><strong> perl before 5.9.0: </strong> fields::new() creates and blesses a
 107 pseudo-hash comprised of the fields declared using the <code>fields</code>
 108 pragma into the specified class.</p>
 109 </dd>
 110 <dd>
 111 <p><strong> perl 5.9.0 and higher: </strong> fields::new() creates and blesses a
 112 restricted-hash comprised of the fields declared using the <code>fields</code>
 113 pragma into the specified class.</p>
 114 </dd>
 115 <dd>
 116 <p>This function is usable with or without pseudo-hashes.  It is the
 117 recommended way to construct a fields-based object.</p>
 118 </dd>
 119 <dd>
 120 <p>This makes it possible to write a constructor like this:</p>
 121 </dd>
 122 <dd>
 123 <pre>
 124     package Critter::Sounds;
 125     use fields qw(cat dog bird);</pre>
 126 </dd>
 127 <dd>
 128 <pre>
 129     sub new {
 130         my $self = shift;
 131         $self = fields::new($self) unless ref $self;
 132         $self-&gt;{cat} = 'meow';                          # scalar element
 133         @$self{'dog','bird'} = ('bark','tweet');        # slice
 134         return $self;
 135     }</pre>
 136 </dd>
 137 </li>
 138 <dt><strong><a name="item_phash">phash</a></strong>
 139
 140 <dd>
 141 <p><strong> before perl 5.9.0: </strong></p>
 142 </dd>
 143 <dd>
 144 <p>fields::phash() can be used to create and initialize a plain (unblessed)
 145 pseudo-hash.  This function should always be used instead of creating
 146 pseudo-hashes directly.</p>
 147 </dd>
 148 <dd>
 149 <p>If the first argument is a reference to an array, the pseudo-hash will
 150 be created with keys from that array.  If a second argument is supplied,
 151 it must also be a reference to an array whose elements will be used as
 152 the values.  If the second array contains less elements than the first,
 153 the trailing elements of the pseudo-hash will not be initialized.
 154 This makes it particularly useful for creating a pseudo-hash from
 155 subroutine arguments:</p>
 156 </dd>
 157 <dd>
 158 <pre>
 159     sub dogtag {
 160        my $tag = fields::phash([qw(name rank ser_num)], [@_]);
 161     }</pre>
 162 </dd>
 163 <dd>
 164 <p>fields::phash() also accepts a list of key-value pairs that will
 165 be used to construct the pseudo hash.  Examples:</p>
 166 </dd>
 167 <dd>
 168 <pre>
 169     my $tag = fields::phash(name =&gt; &quot;Joe&quot;,
 170                             rank =&gt; &quot;captain&quot;,
 171                             ser_num =&gt; 42);</pre>
 172 </dd>
 173 <dd>
 174 <pre>
 175     my $pseudohash = fields::phash(%args);</pre>
 176 </dd>
 177 <dd>
 178 <p><strong> perl 5.9.0 and higher: </strong></p>
 179 </dd>
 180 <dd>
 181 <p>Pseudo-hashes have been removed from Perl as of 5.10.  Consider using
 182 restricted hashes or fields::new() instead.  Using fields::phash()
 183 will cause an error.</p>
 184 </dd>
 185 </li>
 186 </dl>
 187 <p>
 188 </p>
 189 <hr />
 190 <h1><a name="see_also">SEE ALSO</a></h1>
 191 <p><a href="file://C|\msysgit\mingw\html/lib/base.html">the base manpage</a></p>
 192 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 193 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 194 <big><strong><span class="block">&nbsp;fields - compile-time class fields</span></strong></big>
 195 </td></tr>
 196 </table>
 197
 198 </body>
 199
 200 </html>