package fields;
+require 5.005;
+use strict;
+no strict 'refs';
+unless( eval q{require warnings::register; warnings::register->import} ) {
+ *warnings::warnif = sub {
+ require Carp;
+ Carp::carp(@_);
+ }
+}
+use vars qw(%attr $VERSION);
+
+$VERSION = '2.03';
+
+# constant.pm is slow
+sub PUBLIC () { 2**0 }
+sub PRIVATE () { 2**1 }
+sub INHERITED () { 2**2 }
+sub PROTECTED () { 2**3 }
+
+
+# The %attr hash holds the attributes of the currently assigned fields
+# per class. The hash is indexed by class names and the hash value is
+# an array reference. The first element in the array is the lowest field
+# number not belonging to a base class. The remaining elements' indices
+# are the field numbers. The values are integer bit masks, or undef
+# in the case of base class private fields (which occupy a slot but are
+# otherwise irrelevant to the class).
+
+sub import {
+ my $class = shift;
+ return unless @_;
+ my $package = caller(0);
+ # avoid possible typo warnings
+ %{"$package\::FIELDS"} = () unless %{"$package\::FIELDS"};
+ my $fields = \%{"$package\::FIELDS"};
+ my $fattr = ($attr{$package} ||= [1]);
+ my $next = @$fattr;
+
+ # Quiet pseudo-hash deprecation warning for uses of fields::new.
+ bless \%{"$package\::FIELDS"}, 'pseudohash';
+
+ if ($next > $fattr->[0]
+ and ($fields->{$_[0]} || 0) >= $fattr->[0])
+ {
+ # There are already fields not belonging to base classes.
+ # Looks like a possible module reload...
+ $next = $fattr->[0];
+ }
+ foreach my $f (@_) {
+ my $fno = $fields->{$f};
+
+ # Allow the module to be reloaded so long as field positions
+ # have not changed.
+ if ($fno and $fno != $next) {
+ require Carp;
+ if ($fno < $fattr->[0]) {
+ if ($] < 5.006001) {
+ warn("Hides field '$f' in base class") if $^W;
+ } else {
+ warnings::warnif("Hides field '$f' in base class") ;
+ }
+ } else {
+ Carp::croak("Field name '$f' already in use");
+ }
+ }
+ $fields->{$f} = $next;
+ $fattr->[$next] = ($f =~ /^_/) ? PRIVATE : PUBLIC;
+ $next += 1;
+ }
+ if (@$fattr > $next) {
+ # Well, we gave them the benefit of the doubt by guessing the
+ # module was reloaded, but they appear to be declaring fields
+ # in more than one place. We can't be sure (without some extra
+ # bookkeeping) that the rest of the fields will be declared or
+ # have the same positions, so punt.
+ require Carp;
+ Carp::croak ("Reloaded module must declare all fields at once");
+ }
+}
+
+sub inherit {
+ require base;
+ goto &base::inherit_fields;
+}
+
+sub _dump # sometimes useful for debugging
+{
+ for my $pkg (sort keys %attr) {
+ print "\n$pkg";
+ if (@{"$pkg\::ISA"}) {
+ print " (", join(", ", @{"$pkg\::ISA"}), ")";
+ }
+ print "\n";
+ my $fields = \%{"$pkg\::FIELDS"};
+ for my $f (sort {$fields->{$a} <=> $fields->{$b}} keys %$fields) {
+ my $no = $fields->{$f};
+ print " $no: $f";
+ my $fattr = $attr{$pkg}[$no];
+ if (defined $fattr) {
+ my @a;
+ push(@a, "public") if $fattr & PUBLIC;
+ push(@a, "private") if $fattr & PRIVATE;
+ push(@a, "inherited") if $fattr & INHERITED;
+ print "\t(", join(", ", @a), ")";
+ }
+ print "\n";
+ }
+ }
+}
+
+if ($] < 5.009) {
+ *new = sub {
+ my $class = shift;
+ $class = ref $class if ref $class;
+ return bless [\%{$class . "::FIELDS"}], $class;
+ }
+} else {
+ *new = sub {
+ my $class = shift;
+ $class = ref $class if ref $class;
+ require Hash::Util;
+ my $self = bless {}, $class;
+
+ # The lock_keys() prototype won't work since we require Hash::Util :(
+ &Hash::Util::lock_keys(\%$self, keys %{$class.'::FIELDS'});
+ return $self;
+ }
+}
+
+sub phash {
+ die "Pseudo-hashes have been removed from Perl" if $] >= 5.009;
+ my $h;
+ my $v;
+ if (@_) {
+ if (ref $_[0] eq 'ARRAY') {
+ my $a = shift;
+ @$h{@$a} = 1 .. @$a;
+ if (@_) {
+ $v = shift;
+ unless (! @_ and ref $v eq 'ARRAY') {
+ require Carp;
+ Carp::croak ("Expected at most two array refs\n");
+ }
+ }
+ }
+ else {
+ if (@_ % 2) {
+ require Carp;
+ Carp::croak ("Odd number of elements initializing pseudo-hash\n");
+ }
+ my $i = 0;
+ @$h{grep ++$i % 2, @_} = 1 .. @_ / 2;
+ $i = 0;
+ $v = [grep $i++ % 2, @_];
+ }
+ }
+ else {
+ $h = {};
+ $v = [];
+ }
+ [ $h, @$v ];
+
+}
+
+1;
+
+__END__
+
=head1 NAME
fields - compile-time class fields
}
}
- my Foo $var = Foo::->new;
+ my $var = Foo->new;
$var->{foo} = 42;
- # this will generate a compile-time error
+ # this will generate an error
$var->{zap} = 42;
# subclassing
Do B<not> update the %FIELDS hash directly, because it must be created
at compile-time for it to be fully useful, as is done by this pragma.
+B<Only valid for perl before 5.9.0:>
+
If a typed lexical variable holding a reference is used to access a
-hash element and a package with the same name as the type has declared
-class fields using this pragma, then the operation is turned into an
-array access at compile time.
+hash element and a package with the same name as the type has
+declared class fields using this pragma, then the operation is
+turned into an array access at compile time.
+
The related C<base> pragma will combine fields from base classes and any
fields declared using the C<fields> pragma. This enables field
overridden but will generate a warning if used together with the C<-w>
switch.
-The effect of all this is that you can have objects with named fields
-which are as compact and as fast arrays to access. This only works
-as long as the objects are accessed through properly typed variables.
-If the objects are not typed, access is only checked at run time.
+B<Only valid for perls before 5.9.0:>
+
+The effect of all this is that you can have objects with named
+fields which are as compact and as fast arrays to access. This only
+works as long as the objects are accessed through properly typed
+variables. If the objects are not typed, access is only checked at
+run time.
+
The following functions are supported:
-=over 8
+=over 4
=item new
-fields::new() creates and blesses a pseudo-hash comprised of the fields
-declared using the C<fields> pragma into the specified class.
+B< perl before 5.9.0: > fields::new() creates and blesses a
+pseudo-hash comprised of the fields declared using the C<fields>
+pragma into the specified class.
+
+B< perl 5.9.0 and higher: > fields::new() creates and blesses a
+restricted-hash comprised of the fields declared using the C<fields>
+pragma into the specified class.
+
+This function is usable with or without pseudo-hashes. It is the
+recommended way to construct a fields-based object.
+
This makes it possible to write a constructor like this:
package Critter::Sounds;
use fields qw(cat dog bird);
sub new {
- my Critter::Sounds $self = shift;
+ my $self = shift;
$self = fields::new($self) unless ref $self;
$self->{cat} = 'meow'; # scalar element
@$self{'dog','bird'} = ('bark','tweet'); # slice
=item phash
+B< before perl 5.9.0: >
+
fields::phash() can be used to create and initialize a plain (unblessed)
pseudo-hash. This function should always be used instead of creating
pseudo-hashes directly.
subroutine arguments:
sub dogtag {
- my $tag = fields::phash([qw(name rank ser_num)], [@_]);
+ my $tag = fields::phash([qw(name rank ser_num)], [@_]);
}
fields::phash() also accepts a list of key-value pairs that will
be used to construct the pseudo hash. Examples:
my $tag = fields::phash(name => "Joe",
- rank => "captain",
- ser_num => 42);
+ rank => "captain",
+ ser_num => 42);
my $pseudohash = fields::phash(%args);
+B< perl 5.9.0 and higher: >
+
+Pseudo-hashes have been removed from Perl as of 5.10. Consider using
+restricted hashes or fields::new() instead. Using fields::phash()
+will cause an error.
+
=back
=head1 SEE ALSO
-L<base>,
-L<perlref/Pseudo-hashes: Using an array as a hash>
+L<base>
=cut
-
-use 5.005_64;
-use strict;
-no strict 'refs';
-use warnings::register;
-our(%attr, $VERSION);
-
-$VERSION = "1.01";
-
-# some constants
-sub _PUBLIC () { 1 }
-sub _PRIVATE () { 2 }
-
-# The %attr hash holds the attributes of the currently assigned fields
-# per class. The hash is indexed by class names and the hash value is
-# an array reference. The first element in the array is the lowest field
-# number not belonging to a base class. The remaining elements' indices
-# are the field numbers. The values are integer bit masks, or undef
-# in the case of base class private fields (which occupy a slot but are
-# otherwise irrelevant to the class).
-
-sub import {
- my $class = shift;
- return unless @_;
- my $package = caller(0);
- # avoid possible typo warnings
- %{"$package\::FIELDS"} = () unless %{"$package\::FIELDS"};
- my $fields = \%{"$package\::FIELDS"};
- my $fattr = ($attr{$package} ||= [1]);
- my $next = @$fattr;
-
- if ($next > $fattr->[0]
- and ($fields->{$_[0]} || 0) >= $fattr->[0])
- {
- # There are already fields not belonging to base classes.
- # Looks like a possible module reload...
- $next = $fattr->[0];
- }
- foreach my $f (@_) {
- my $fno = $fields->{$f};
-
- # Allow the module to be reloaded so long as field positions
- # have not changed.
- if ($fno and $fno != $next) {
- require Carp;
- if ($fno < $fattr->[0]) {
- warnings::warnif("Hides field '$f' in base class") ;
- } else {
- Carp::croak("Field name '$f' already in use");
- }
- }
- $fields->{$f} = $next;
- $fattr->[$next] = ($f =~ /^_/) ? _PRIVATE : _PUBLIC;
- $next += 1;
- }
- if (@$fattr > $next) {
- # Well, we gave them the benefit of the doubt by guessing the
- # module was reloaded, but they appear to be declaring fields
- # in more than one place. We can't be sure (without some extra
- # bookkeeping) that the rest of the fields will be declared or
- # have the same positions, so punt.
- require Carp;
- Carp::croak ("Reloaded module must declare all fields at once");
- }
-}
-
-sub inherit { # called by base.pm when $base_fields is nonempty
- my($derived, $base) = @_;
- my $base_attr = $attr{$base};
- my $derived_attr = $attr{$derived} ||= [];
- # avoid possible typo warnings
- %{"$base\::FIELDS"} = () unless %{"$base\::FIELDS"};
- %{"$derived\::FIELDS"} = () unless %{"$derived\::FIELDS"};
- my $base_fields = \%{"$base\::FIELDS"};
- my $derived_fields = \%{"$derived\::FIELDS"};
-
- $derived_attr->[0] = $base_attr ? scalar(@$base_attr) : 1;
- while (my($k,$v) = each %$base_fields) {
- my($fno);
- if ($fno = $derived_fields->{$k} and $fno != $v) {
- require Carp;
- Carp::croak ("Inherited %FIELDS can't override existing %FIELDS");
- }
- if ($base_attr->[$v] & _PRIVATE) {
- $derived_attr->[$v] = undef;
- } else {
- $derived_attr->[$v] = $base_attr->[$v];
- $derived_fields->{$k} = $v;
- }
- }
-}
-
-sub _dump # sometimes useful for debugging
-{
- for my $pkg (sort keys %attr) {
- print "\n$pkg";
- if (@{"$pkg\::ISA"}) {
- print " (", join(", ", @{"$pkg\::ISA"}), ")";
- }
- print "\n";
- my $fields = \%{"$pkg\::FIELDS"};
- for my $f (sort {$fields->{$a} <=> $fields->{$b}} keys %$fields) {
- my $no = $fields->{$f};
- print " $no: $f";
- my $fattr = $attr{$pkg}[$no];
- if (defined $fattr) {
- my @a;
- push(@a, "public") if $fattr & _PUBLIC;
- push(@a, "private") if $fattr & _PRIVATE;
- push(@a, "inherited") if $no < $attr{$pkg}[0];
- print "\t(", join(", ", @a), ")";
- }
- print "\n";
- }
- }
-}
-
-sub new {
- my $class = shift;
- $class = ref $class if ref $class;
- return bless [\%{$class . "::FIELDS"}], $class;
-}
-
-sub phash {
- my $h;
- my $v;
- if (@_) {
- if (ref $_[0] eq 'ARRAY') {
- my $a = shift;
- @$h{@$a} = 1 .. @$a;
- if (@_) {
- $v = shift;
- unless (! @_ and ref $v eq 'ARRAY') {
- require Carp;
- Carp::croak ("Expected at most two array refs\n");
- }
- }
- }
- else {
- if (@_ % 2) {
- require Carp;
- Carp::croak ("Odd number of elements initializing pseudo-hash\n");
- }
- my $i = 0;
- @$h{grep ++$i % 2, @_} = 1 .. @_ / 2;
- $i = 0;
- $v = [grep $i++ % 2, @_];
- }
- }
- else {
- $h = {};
- $v = [];
- }
- [ $h, @$v ];
-}
-
-1;
https://perl5.git.perl.org / perl5.git / blobdiff