• NAME
• VERSION 1.1
• SYNOPSIS
• Class
• Usage
• DESCRIPTION
• INSTALLATION
• OPTIONS
• BUGS
• CREDITS

NAME

Object::props - Pragma to implement lvalue accessors with options

VERSION 1.1

Included in ObjectTools 1.1 distribution.

SYNOPSIS

Class

    package MyClass ;

    # implement constructor without options
    use Object::new ;

    # just accessors without options (list of strings)
    use Object::props @prop_names ;

    # a property with validation and default (list of hash refs)
    use Object::props { name       => 'digits',
                        validation => sub{ /^\d+\z/ }       # just digits
                        default    => 10
                      } ;

    # a group of properties with common full options
    use Object::props { name       => \@other_prop_names,   # array ref
                        default    => 'something' ,
                        validation => sub{ /\w+/ }
                        protected  => 1
                      } ;

    # all the above in just one step (list of strings and hash refs)
    use Object::props @prop_names ,
                      { name       => 'digits',
                        validation => sub{ /^\d+\z/ }
                        default    => 10
                      } ,
                      { name       => \@other_prop_names,
                        default    => 'something' ,
                        validation => sub{ /\w+/ }
                        protected  => 1
                      } ;

Usage

    my $object = MyClass->new(digits => '123');

    $object->digits    = '123';

    $object->digits('123');

    my $d = $object->digits;  # $d == 123

    undef $object->digits     # $object->digits == 10 (default)

    # This would croak
    $object->digits    = "xyz";

DESCRIPTION

This pragma easily implements lvalue accessor methods for the properties of your object (lvalue means that you can create a reference to it, assign to it and apply a regex to it).

You can completely avoid to write the accessor by just declaring the names and eventually the default value, validation code and other option of your properties.

INSTALLATION

Prerequisites

    Perl version >= 5.6.1

CPAN

    perl -MCPAN -e 'install ObjectTools'

Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

OPTIONS

name

The name of the property is used as the identifier to create the accessor method, and as the key of the blessed object hash.

Given 'my_prop' as the property name:

    $object->my_prop = 10 ;  # assign 10 to $object->{my_prop}
    $object->my_prop( 10 );  # assign 10 to $object->{my_prop}

    # same thing if MyClass::new is implemented
    # by the Object::new pragma

    $object = MyClass->new( my_prop => 10 );

You can group properties that have the same set of option by passing a reference to an array containing the names. If you don't use any option you can pass a list of plain names as well. See SYNOPSYS.

default

The property will be initially set to the default value. You can reset a property to its default value by assigning it the undef value.

    # this will reset the property to its default
    $object->my_prop = undef ;

    # this works as well
    undef $object->my_prop ;

If any validation option is set, then the default value is validated at compile time. If no default option is set, then the property will return the undef value and will bypass the validation sub.

validation

You can set a code reference to validate a new value. If you don't set any validation option, no validation will be done on the assignment.

In the validation code, the object is passed in $_[0] and the value to be validated is passed in $_[1] and for regexing convenience it is aliased in $_. Assign to $_ in the validation code to change the actual imput value.

    # web color validation
    use Object::props { name       => 'web_color'
                        validation => sub { /^#[0-9A-F]{6}$/ }
                      }

    # this will uppercase all input value
    use Object::props { name       => 'uppercase_it'
                        validation => sub { $_ = uc }
                      }
    # this would croak
    $object->web_color = 'dark gray'

    # when used
    $object->uppercase_it = 'abc' # real value will be 'ABC'

The validation code should return true on success and false on failure. Croak explicitly if you don't like the default error message.

protected

Set this option to a true value and the property will be turned read-only when used from outside its class or sub-classes. This allows you to normally read and set the property from your class but it will croak if your user tries to set it.

BUGS

None known, but the module is not completely tested.

CREDITS

Thanks to Juerd Waalboer (http://search.cpan.org/author/JUERD) that with its Attribute::Property inspired the creation of this distribution.