NAME
Orignal - Very simple properties/attributes/fields for Perl
head1 SYNOPSIS
package house;
use parent qw(Orignal);
house->attributes({SCALARS =>[qw(address style type)],
ORDERED_HASHES =>[qw(owners)],
HASHES =>[qw(rooms)],
ARRAYS =>[qw(occupants pets)]});
1;
use house;
my $big_house = house->new({address=>'1313 Mockingbird',
type =>'Mansion'
style =>'Gothic'
owners =>{present=>'Lily Munster',past=>'Sam Dracula',builder=>'V. Frankenstein'}
rooms =>{bathrooms=>0,bedrooms=>5,playroom=>1, dungeon=>1, lab=>1},
occupants=>[qw(Herman Lilly Grandpa Eddie Marilyn)]},
pets =>[qw(Spot Kitty)]);
my $address = $big_house->address();
my @people = $big_house->occupants();
my %rooms = $big_house->rooms();
DESCRIPTION
When I said simple I meant very simple. It basically just gives you a very easy way to create class level attributes that encapsulate class data, enforcing unique field names and has the added bonus of an ordered hash.
Simply think of it as the base class for other classes and you got the concept. Still unclear well if you are like me and hate writing setters and getters then this is the mod for you, as this is all it does.
The main goal of Orignal is to be light and easy to use, the code is less than 20k and has no dependencies on other modules. I created it out of frustration of liking perl 5.14 attributes but being stuck with coding in perl 5.6.
Usage
Orignal should always be used as part of a larger class or module never on its own. Simply use Orignal and then call the 'attributes' method directly on your package with an attributes hash that contains the correct attribute keys.
package something;
use Orignal;
something->{SCALARS=>[qw(nothing)];There are four Attribute keys SCALARS, HASHES, ORDERED_HAHSES and ARRAYS and each key if used must point to an array reference of fields. Orignal takes the fields and then creates the code references for each them that you can then use as if the code was actually in the module.
Class Methods
attributes
Use only when defining your package. Any other use will result in a die. For example
package house;
use parent qw(Orignal);
house->attributes({SCALARS =>[qw(address style type)],
ORDERED_HASHES =>[qw(owners)],
HASHES =>[qw(rooms)],
ARRAYS =>[qw(occupants pets)]});
1;Will create a package called house that you can use like this
use house;
my $big_house = house->new({address=>'1313 Mockingbird',
type =>'Mansion'
style =>'Gothic'
owners =>{present=>'Lily Munster',past=>'Sam Dracula',builder=>'V. Frankenstein'}
rooms =>{bathrooms=>0,bedrooms=>5,playroom=>1, dungeon=>1, lab=>1},
occupants=>[qw(Herman Lilly Grandpa Eddie Marilyn)]},
pets =>[qw(Spot Kitty)]);
new
This is your standard new that takes a hash ref and if a Key in that hash matches a key the name of an attribute the attribute is set to that value. If a hash ref key does not match it is simply ignored. It also does not care if you do not match all the attribute names.
my $dho_house = house->new({address=>'472 Evergreen Terrace',
type =>'Small',
style =>'Clapboard',
owners =>{present=>'H. J. Simpson',past=>'Ned Flanders'},
pets =>[qw(snowball5,santas little helper)]);
my_attributes
This will return the attribute hash ref used in the creation of the class.
my $attrb = $big_house->my_attributes();
$attrb would point to this hash
{SCALARS =>['address','style','type'],
ORDERED_HASHES =>['owners'],
HASHES =>['rooms'],
ARRAYS =>['occupants','pets']}
Attribute Methods
SCALARS
Simple Perl scalars.
Getter
A perlish getter for these that uses the field name.
print $big_house->address();Will return the value stored in 'address' attribute;
Setter
A simple perlish setter that uses the field name.
$big_house->address('472 Evergreen Terrace');Will set the value of the 'address' attribute to '472 Evergreen Terrace';
Validate
You can add an optional validator sub to a SCALAR attribute. You can validate any condition you want but you will have to follow this design pattern ATTRIBUTE_NAME_validate for the sub name, a shift to get the class, then the @_ to get the values passed into to validation sub from the setter, Finally use die if you fail validation. See the examples below;
#address must not be undef
sub address_validate {
my $self = shift;
my ($new_address) = @_;
die("ERROR: SomeMode::House::address, cannot be empty.")
unless ($new_address);
}
#address cannot be "NO"
sub address_validate {
my $self = shift;
my ($new_address) = @_;
die("ERROR: SomeMode::House::address, cannot be 'NO'.")
if ($new_address eq 'NO');
}HASHES and ORDERED_HASHES
Simple Perl hashes of scalars. Orignal has two types unordered and ordered they share all the same methods.
Getter
A little more complex this time but still uses the field name.
my %some_rooms = $big_house->rooms();
my $some_rooms = $big_house->rooms();will return the hash stored in the rooms attribute of $big_house when called in list context. In scalar context it will return the hash key pair string.
my %bath_count = $big_house->rooms('bathrooms','dungeon');
my $bath_count = $big_house->rooms('bathrooms','dungeon');will return a hash of 2 keys and their values from the 'rooms' attribute when called in list context and in scalar context is will return the hash key pair string. If a key is not found it will return nothing.
Both the hash and ordered_hash work in the same manner.
Setter
Same as Scalar the field name but can take a hash ref as a parameter as well.
my %owners = $big_house->rooms({kitchen =>1});
my $owners = $big_house->rooms({kitchen =>1});Will add the name values pair 'kitchen=>1' to the rooms attribute is return the new hash while in scalar context just the key pair string will be returned. When using an ordered_hash the order in which you enter the new key value pairs will be retained by Orignal except when on a new as you are passing a hash in that will not be in order.
Sending an empty hash ref to the function
$big_house->owners({})will empty out the rooms attribute and return undef, both the hash and ordered_hash work in the same manner.
Delete
Orignal defines a delete method as well which is in the format delete_field() that works in the same manner as a normal hash delete deleting a value from a hash.
# big_house->rooms = {bathrooms=>0,bedrooms=>5,playroom=>1, dungeon=>1, lab=>1}
$scalar = $big_house->delete_rooms(bedrooms); # $scalar is 5
$scalar = $big_house->delete_rooms(qw(playroom bathrooms)); # $scalar is 0
@array = $big_house->delete_rooms(qw(dungeon playroom lab)); # @array is (1,undef,1);Both the hash and ordered_hash work in the same manner.
Exists
Orignal defines an exists method as well which is in the format exits_field() it works in the same manner as a normal hash exits, testing whether a hash key is present. It has the added bonus if you ask for more than one key it will give the total count of keys present.
# big_house->rooms = {bathrooms=>0,bedrooms=>5,playroom=>1, dungeon=>1, lab=>1}
$scalar = $big_house->exists_rooms(bedrooms); # $scalar is 1
$scalar = $big_house->exists_rooms(funroom); # $scalar is 0
$array = $big_house->exists_rooms(qw(dungeon playroom lab)); # $scalar is 3Both the hash and ordered_hash work in the same manner.
Keys
Orignal defines a keys method as well which is in the format keys_field() it works in the same manner as a normal hash keys retrieving the list of indices from a hash. However for an Ordered Hash they come out the same way they went in.
# big_house->rooms = {bathrooms=>0,bedrooms=>5,playroom=>1, dungeon=>1, lab=>1}
$scalar = $big_house->keys_rooms(); # $scalar is 5
@array = $big_house->keys_rooms(); # @array is (dungeon,lab,bedrooms,playroom,bathrooms)
# $big_house->owners ={present=>'Lily Munster',past=>'Sam Dracula',builder=>'V. Frankenstein'}
# ordered hash
$scalar = $big_house->keys_owners(); # $scalar is 3
$array = $big_house->keys_owners(); # @array is (present,past,builder)As you can see order hash preserves the order of the keys
Validate
You can add an optional validator sub to any HASH or ORDERED_HASH attribute. You can validate any condition you want but you will have to follow this design pattern ATTRIBUTE_NAME_validate for the sub name, a shift to get the class, then the @_ to get the values passed into to validation sub from the setter, Finally use die if you fail validation. See the examples below;
#address must not be empty
sub address_validate {
my $self = shift;
my ($new_address) = @_;
die("ERROR: SomeMode::House::address, cannot be empty.")
unless ($new_address);
}
#address has to be an must a hash ref
sub address_validate {
my $self = shift;
my ($new_address) = @_;
ref($new_address) eq 'HASH' || die("ERROR: SomeMode::House::address, must be a 'HASH' Ref.");
}
Values
Orignal defines a values method as well which is in the format values_field() it works in the same manner as a normal hash values returning a list of the values in a hash. However for an Ordered Hash they come out the same way they went in.
# big_house->rooms = {bathrooms=>0,bedrooms=>5,playroom=>1, dungeon=>1, lab=>1}
$scalar = $big_house->values_rooms(); # $scalar is 5
@array = $big_house->values_rooms(); # @array is (1,0,5,1,0)
# $big_house->owners ={present=>'Lily Munster',past=>'Sam Dracula',builder=>'V. Frankenstein'}
# ordered hash
$scalar = $big_house->values_owners(); # $scalar is 3
$array = $big_house->values_owners(); # @array is ('Lily Munster','Sam Dracula','V. Frankenstein')As you can see order hash preserves the order of the values.
Arrays
Simple Perl Arrays of scalars.
Getter
A little more complex this time but still uses the field name.
my @pets = $big_house->pets();
my $pets = $big_house->pets();will return the array stored in the pets attribute of $big_house when called in list context. In scalar context it will return the count of indexes on the array.
my @pets = $big_house->pets(0,2);
my $pets = $big_house->pets(0,2);will return an array of 2 the values from the 'pets' attribute when called in list context and in scalar context is will return the count. If a index is off the array it will return nothing.
Setter
Same as Scalar the field name but can also take an array ref as the parameter.
my @pets = $big_house->pets(qw(Raven Igor)});
my $pets = $big_house->pets(qw(Raven Igor));Will add the values Raven and Igor to the end of the pets attribute and return the new array if called in list context. If called in scalar context just the length of the array will be returned. Like any array values can be duplicated.
Sending an empty array ref to the method
$big_house->pets([]);will empty out the pets attribute and return undef.
Pop
Orignal defines a pop method as well which is in the format pop_field() it works in the same manner as a normal array pop removing the last element from an array and returning it.
pets =>[qw(Spot Kitty)])
$scalar = $big_house->pop_pets(); # $scalar is Kitty
@array = $big_house->pets(); # @array is ('Spot')Push
Orignal defines a push method as well which is in the format push_field() it works in the same manner as a normal array push appending one or more elements to an array.
pets =>[qw(Spot)])
$scalar = $big_house->push_pets('Kitty'); # $scalar is 2, pets= ('Spot','Kitty')
@array = $big_house->push_pets('Kitty'); @array is ('Spot','Kitty'), pets= ('Spot','Kitty')Shift
Orignal defines a shift method as well which is in the format shift_field() it works in the same manner as a normal array shift removing the first element of an array, and returning it .
pets =>[qw(Spot Kitty)])
$scalar = $big_house->shift_pets(); # $scalar is Spot
@array = $big_house->pets(); # @array is ('Kitty')Unshift
Orignal defines a unshift method as well which is in the format unshift_field() it works in the same manner as a normal array unshift prepending more elements to the beginning of a list.
pets =>[qw(Spot)])
$scalar = $big_house->push_pets('Kitty'); # $scalar is 2, pets= ('Kitty','Spot')
@array = $big_house->push_pets('Kitty'); @array is ('Kitty','Spot'), pets= ('Kitty','Spot')Validate
You can add an optional validator sub to an ARRAY attribute. You can validate any condition you want but you will have to follow this design pattern ATTRIBUTE_NAME_validate for the sub name, a shift to get the class, then the @_ to get the values passed into to validation sub from the setter, Finally use die if you fail validation. See the examples below;
#address must not be empty
sub address_validate {
my $self = shift;
my ($new_address) = @_;
die("ERROR: SomeMode::House::address, cannot be empty.")
unless ($new_address);
}
#address has to be an must a array ref
sub address_validate {
my $self = shift;
my ($new_address) = @_;
ref($new_address) eq 'ARRAY' || die("ERROR: SomeMode::House::address, must be an 'ARRAY' Ref.");
}CONTRIBUTING If you like Orignal and want to add to it or just complain. The source is available on GitHub at https://github.com/byterock/Orignal
Bugs
I haven't found any but I am sure there are? You can report them here https://rt.cpan.org/Public/Dist/Display.html?Name=Orignal or here https://github.com/byterock/Orignal/issues.
SUPPORT
Now there is a Wiki, but nothing there yet https://github.com/byterock/Orignal/wiki.
AUTHOR
John Scoles.
https://github.com/byterock/Orignal
COPYRIGHT AND LICENSE ^
Copyright 2011 By John Scoles.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.