NAME
Badger::Class::Method - metaprogramming module for adding methods to a class
SYNOPSIS
package My::Module;
# using the module directly
use Badger::Class::Methods
accessors => 'foo bar',
mutators => 'wiz bang';
# or via Badger::Class
use Badger::Class
accessors => 'foo bar',
mutators => 'wiz bang';DESCRIPTION
This module can be used to generate methods for a class. It can be used directly, or via the accessors, accessors and slots export hooks in Badger::Class.
METHODS
generate($class,$type,$methods)
This method is a central dispatcher to other methods.
Badger::Class::Methods->generate(
accessors => 'foo bar',
);accessors($class,$methods) / get($class,$methods)
This method can be used to generate accessor (read-only) methods for a class (Badger::Class object) or package name. You can pass a list, reference to a list, or a whitespace delimited string of method names as arguments.
# these all do the same thing
Badger::Class::Methods->accessors('My::Module', 'foo bar');
Badger::Class::Methods->accessors('My::Module', 'foo', 'bar');
Badger::Class::Methods->accessors('My::Module', ['foo', 'bar']);A method will be generated in the target class for each that returns the object member data of the same name. The code generated for each method is equivalent to this:
sub foo {
$_[0]->{ foo };
}mutators($class,$methods) / set($class,$methods)
This method can be used to generate mutator (read/write) methods for a class (Badger::Class object) or package name. You can pass a list, reference to a list, or a whitespace delimited string of method names as arguments.
# these all do the same thing
Badger::Class::Methods->mutators('My::Module', 'foo bar');
Badger::Class::Methods->mutators('My::Module', 'foo', 'bar');
Badger::Class::Methods->mutators('My::Module', ['foo', 'bar']);A method will be generated in the target class for each that returns the object member data of the same name. If an argument is passed then the member data is updated and the new value returned.
The code generated is equivalent to this:
sub foo {
@_ == 2
? ($_[0]->{ foo } = $_[1])
: $_[0]->{ foo };
}Ugly isn't it? But of course you wouldn't ever write it like that, being a conscientious Perl programmer concerned about the future readability and maintainability of your code. Instead you might write it something like this:
sub foo {
my $self = shift;
if (@_) {
# an argument implies a set
return ($self->{ foo } = shift);
}
else {
# no argument implies a get
return $self->{ foo };
}
}Or perhaps like this:
sub foo {
my $self = shift;
# update value if an argument was passed
$self->{ foo } = shift if @_;
return $self->{ foo };
}Or even like this (my personal favourite):
sub foo {
my $self = shift;
return @_
? ($self->{ foo } = shift)
: $self->{ foo };
}Whichever way you do it is a waste of time, both for you and anyone who has to read your code at a later. Seriously, give it up! Let us generate the methods for you. We'll not only save you the effort of typing pages of code that no-one will ever read (or want to read), but we'll also generate the most efficient code for you. The kind that you wouldn't normally want to handle by yourself.
So in summary, using this method will keep your code clean, your code efficient, and will free up the rest of the afternoon so you can go out skateboarding. Tell your boss I said it was OK.
hash($class, $methods)
This method generates methods for accessing or updating items in a hash reference stored in an object. In the following example we create a users() method for accessing the internal users hash reference.
package Your::Module;
use base 'Badger::Base';
use Badger::Class::Methods
hash => 'users';
sub init {
my ($self, $config) = @_;
$self->{ users } = $config->{ users } || { };
return $self;
}The init() method copies any users passed as a configuration parameter or creates an empty hash reference.
my $object = Your::Module->new(
users => {
tom => 'tom@badgerpower.com',
}
);When called without any arguments, the generated users() method returns a reference to the users hash array.
print $object->users->{ tom }; # tom@badgerpower.comWhen called with a single non-reference argument, it returns the entry in the hash corresponding to that key.
print $object->users('tom'); # tom@badgerpower.comWhen called with a single reference to a hash array, or a list of named parameters, the method will add the new items to the internal hash array. A reference to the hash array is returned.
$object->users({ # single hash ref
dick => 'richard@badgerpower.com',
harry => 'harold@badgerpower.com',
});
$object->users( # list of amed parameters
dick => 'richard@badgerpower.com',
harry => 'harold@badgerpower.com',
);slots($class,$methods)
This method can be used to define methods for list-based object classes. A list, reference to a list, or string of whitespace delimited method names should be passed an argument(s). A method will be generated for each item specified. The first method will reference the first (0th) item in the list, the second method will reference the second (1st), and so on.
Badger::Class::Methods->slots('My::Module', 'foo bar');
Badger::Class::Methods->slots('My::Module', 'foo', 'bar');
Badger::Class::Methods->slots('My::Module', ['foo', 'bar']);It is usually called indirectly via the slots export hook in Badger::Class.
package Badger::Example;
use Badger::Class
slots => 'size colour object';
sub new {
my ($class, @stuff) = @_;
bless \@stuff, $class;
}The above example defines a simple list-based object class with three slots: size, colour and object. You can use it like this:
my $bus = Badger::Test::Slots->new(qw( big red bus ));
print $bus->size; # big
print $bus->colour; # red
print $bus->object; # busThe methods generated are mutators. That is, you can pass an argument to update the slot value.
$bus->size('large');INTERNAL METHODS
args(@args)
This methods inspect the arguments and performs the necessary validation for the accessors(), mutators() and slots() methods.
AUTHOR
Andy Wardley http://wardley.org/
COPYRIGHT
Copyright (C) 2008 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.