GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CLASS::ACCESSOR::CONSTRUCTOR (3)

.ds Aq ’

NAME

Class::Accessor::Constructor - Constructor generator

CONTENTS

VERSION

version 1.111590

SYNOPSIS



  package MyClass;
  use base Class::Accessor::Constructor;
  __PACKAGE__->mk_constructor;



DESCRIPTION

This module generates accessors for your class in the same spirit as Class::Accessor does. While the latter deals with accessors for scalar values, this module provides accessor makers for rather flexible constructors.

The accessor generators also generate documentation ready to be used with Sub::Documentation.

METHODS

    mk_constructor

Takes an array of strings as its argument. If no argument is given, it uses new as the default. For each string it creates a class constructor which is quite powerful and flexible. It supports
customizable munging of arguments
customizable sorting of arguments
inherited default values
an optional init() method
The constructor accepts named arguments - that is, a hash - and will set the hash values on the accessor methods denoted by the keys. For example,



    package MyClass;
    use base Class::Accessor::Constructor;
    __PACKAGE__->mk_constructor;

    package main;
    use MyClass;

    my $o = MyClass->new(foo => 12, bar => [ 1..5 ]);



is the same as



    my $o = MyClass->new;
    $o->foo(12);
    $o->bar([1..5]);



The constructor will also call an init() method, if there is one.

The arguments are munged beforehand - if a single argument is a hashref is passed in, it is expanded out, the the key/value pairs - whether originally as a hash ref or a list - may be reordered as typically occurs with perl hashes.

For example:



    package Simple;
    use base Class::Accessor::Constructor;

    __PACKAGE__
        ->mk_constructor
        ->mk_accessors(qw(a b));

    use constant DEFAULTS => (a => 7, b => default) ;



Somewhere else:



    use Simple;
    my $test1 = Simple->new;                  # now a == 7, b == default
    my $test2 = Simple->new(a => 1);          # now a == 1, b == default
    my $test3 = Simple->new(a => 1, b => 2);  # now a == 1, b == 2



Defaults can be inherited per Data::Inherited’s every_hash(). Example:



    package A;
    use base Class::Accessor::Constructor;

    __PACKAGE__->mk_constructor->mk_accessors(qw(a b));

    use constant DEFAULTS => (a => 7, b => default);



and



    package B;
    use base A;
    use constant DEFAULTS => (a => 23);



then



    use A;
    use B;
    my $test1 = A->new;   # now a ==  7, b == default
    my $test2 = B->new;   # now a == 23, b == default



If a class wants to order some args first, it can define a FIRST_CONSTRUCTOR_ARGS() list, which will be cumulative over inheritance tree due to Data::Inherited. FIRST_CONSTRUCTOR_ARGS() should return a list of argument names that have to come first; if a constructor is called, those arguments are set first, whereas the other ones are set in an unspecified order.

Example:



    package Simple;
    use base Class::Accessor::Constructor;

    __PACKAGE__->mk_constructor->mk_accessors(qw(b));

    use constant FIRST_CONSTRUCTOR_ARGS => (b);

    # make a dependent on b
    sub a {
        return $_[0]->{a} if @_ == 1;
        $_[0]->{a} = $_[1] + $_[0]->b;
    }



then



    my $test = Simple->new(a => 1, b => 2);



will set b first, then set a (to 3).

As mentioned, arguments are munged beforehand automatically, but you can also customize the munging. By default,



    my $test = Simple->new(a => 1, b => 2)



is the same as



    my $test = Simple->new({ a => 1, b => 2 })



Suppose you have a class that has one preferred accessor, and you want to simplify its usage so that if the constructor is called with a single value, it is passed to that preferred accessor.

Given that the Simple class defines



    sub MUNGE_CONSTRUCTOR_ARGS {
        my $self = shift;
        return %{ $_[0] }    if @_ == 1 && ref($_[0]) eq HASH;
        return (b => @_) if @_ % 2;      # odd number of args
        return @_;
    }



then an object could be constructed like this



    my $test = Simple->new(blah);



which would be munged to be equivalent to



    my $test = Simple->new(b => blah);



If you define an init() method, the constructor calls it with the munged args as the very last thing.

    mk_constructor_with_dirty

Like mk_constructor(), but also keeps track of whether the object has been modified. This is useful, for example, when you have read the object from a storage and at the end you want to write it back if it has changed. This method generated saves you from having to update a dirty-flag in each accessor. It achieves its purpose by doing a tie() on the blessed hash that is the object, so there is some performance penalty. But it also works when someone tries to break encapsulation by accessing hash elements directly instead of going via the accessors. See Class::Accessor::Constructor::Base for details.

If you want that behaviour only in a part of your inheritance tree, redefine the constructor at the appropriate point. For example:



    package Foo;
    use base Class::Accessor::Constructor;

    __PACKAGE__->mk_constructor;

    package Bar;
    use base Foo;
    __PACKAGE__->mk_constructor_with_dirty;



Now objects of type Foo will not keep a dirty-flag, but objects of type Bar and its descendants will.

    mk_singleton_constructor

Like constructor but constructs a singleton object.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at <http://rt.cpan.org/Public/Dist/Display.html?Name=Class-Accessor-Constructor>.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you, or see <http://search.cpan.org/dist/Class-Accessor-Constructor/>.

The development version lives at <http://github.com/hanekomu/Class-Accessor-Constructor> and may be cloned from <git://github.com/hanekomu/Class-Accessor-Constructor.git>. Instead of sending patches, please fork this project using the standard git and github infrastructure.

AUTHOR

Marcel Gruenauer <marcel@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2007 by Marcel Gruenauer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CLASS::ACCESSOR::CONSTRUCTOR (3) 2011-06-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.