/ 
fields-aliased-1.01
River stage zero No dependents
/ fields::aliased

NAME

fields::aliased - create aliases for object fields

SYNOPSIS

    package MyPackage;
    use strict;
    use fields::aliased;
    use fields qw($scalar @array %hash);

    sub new {
	my $class = shift;
	my $self = fields::aliased::new($class);
	use fields::aliased qw($self $scalar @array %hash);

	## Now access each field as a simple variable
	$scalar = 1;
	@array = (2 .. 4);
	%hash = ('one' => 1, 'two' => 2);
    }

    sub mymethod {
	my MyPackage $self = shift;
	use fields::aliased qw($self $scalar @array %hash);

	...
    }

DESCRIPTION

This module is a companion to the fields module, which allows efficient handling of instance variables with checking at compile time. It goes one step further and actually creates lexical aliases to the instance values, which can make code not only easier to type, but easier to read as well.

Declaring Variables

  • You declare them in the use fields pragma, as usual, except that you prefix each variable with its type sigil. (For backwards compatibility, anything without a sigil is considered to be a scalar.)

Object Construction

  • You must use fields::aliased with no import list prior to use fields. This sets the superclass of the class to fields::aliased::base so that the proper constructor is inherited.

  • In your object constructor, you call fields::aliased::new (or just $class->SUPER::new) rather than fields::new. This not only sets up the instance variables, but initializes them to suitable defaults: empty arrays for array variables, empty hashes for hash variables, and undef for scalars.

Using Variables

  • In each method that requires the use of instance variables, add the following line:

    use fields::aliased qw($self fields);

    $self is the name of the variable holding the object referent, and fields is the list of field names to be aliased in the method. Note that the field names and associated variable names can be different if, for example, the field name doesn't begin with a type sigil, or begins with an underscore (see "PRIVATE FIELDS").

That's it!

CONSTRUCTOR

new

$object = fields::aliased::new($class);

This is called as a subroutine, not a method, but it functions similarly to a class method. This calls fields::new to create an object of type $class, and then sets up its field variables to suitable defaults.

Note: you don't need to have fields::aliased in your class's ancestry provided that the constructor you do provide calls "new" in fields, and initializes all fields to suitable defaults.

PRIVATE FIELDS

Field names beginning with an underscore are considered private by fields. In order to make this work with fields::aliased, put the sigil after the underscore:

use fields qw(_$private);

Then, in each method, use

use fields::aliased qw($self _$private);

as well. But when accessing the alias, use $_private.

INTERNALS

Important Note: the C code for this module uses two items defined in perlintern and thus marked not for general conception: the CvDEPTH macro, and the Perl_find_runcv function. While it works on the versions of Perl I've tested it on (5.8.4 and 5.9.1), there's no guarantee it will work in the future. I will try to keep on top of this.

[The only people who need to read the rest of this section are those who are curious about how this is implemented, and me when I go back later to fix things.]

Compile Time

At compile time, the use fields::aliased lines causes the import method to be called.

  • If there is no import list, the import method assumes it was called from the outside of any method, and just adds the following line to the source program:

    use base qw(fields::aliased::base);

    This allows the constructor to be inherited. (The separate base class is so that the import method itself doesn't get inherited.)

  • If there is an import list, it consists of the name of the "self" variable and a list of field names. In this case, the import method adds two lines to the source program:

    my (variable-names);

    This defines the aliased variables so the compilation of the program can proceed successfully undef use strict (you are using strict, right?).

    fields::aliased::setup($self, qw/field-names/);

    This sets up the call to the setup function, which links the variables declared above to the actual fields at runtime.

Run Time

At runtime, the setup function is executed to create the actual aliases.

  • If $self is an array reference, it is assumed to be a pseudohash (see fields), where the first element of the array is a hash associating field names with field indices. setup uses the hash in the first element to find the field values in the rest of the elements.

  • If $self is a hash reference, setup just accesses that hash to get the field values.

SEE ALSO

fields, Perl6::Binding, Lexical::Alias

REQUIRED MODULES

Tie::IxHash, Filter::Util::Call, Test::More

COPYRIGHT AND LICENSE

Copyright 2004 Kevin Michael Vail

This program is free software. It may be copied and/or redistributed under the same terms as Perl itself.

AUTHOR

Kevin Michael Vail <kvail@cpan.org>