Class

    package MyClass ;
    
    # implement constructor without options
    use Class::constr ;
    
    # just accessors without options (list of strings)
    use Object::props @prop_names ;                      # @prop_names (1)
    
    # 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       => \@prop_names2,     # @prop_names2 (1)
                        default    => sub{$_[0]->other_default} ,
                        validation => sub{ /\w+/ } ,
                        protected  => 1 ,
                        no_strict  => 1 ,
                        allowed    => qr/::allowed_sub$/
                      } ;
                      
    # all the above in just one step (list of strings and hash refs)
    use Object::props @prop_names ,                      # @prop_names (1)
                      { name       => 'digits',
                        validation => sub{ /^\d+\z/ } ,
                        default    => 10
                      } ,
                      { name       => \@prop_names2,     # @prop_names2 (1)
                        default    => sub{$_[0]->other_default} ,
                        validation => sub{ /\w+/ } ,
                        protected  => 1 ,
                        no_strict  => 1 ,
                        allowed    => qr/::allowed_sub$/
                      } ;
                      
    # (1) must be set in a BEGIN block to have effect at compile time

Usage

    $object = MyClass->new(digits => '123');
    
    $object->digits    = '123';
    
    $object->digits('123');      # old way supported
    
    $d = $object->digits;        # $d == 123
    $d = $$object{digits}        # $d == 123
    
    undef $object->digits        # $object->digits == 10 (default)
    
    # these would croak
    $object->digits    = "xyz";
    
    # this will bypass the accessor whithout croaking
    $$object{digits}  = "xyz";

Package, Class or Object properties?

Look at this example:

   package BaseClass;
   use Object::props  'an_object_prop';
   use Class::props   'a_class_prop';
   use Package::props 'a_package_prop';
   
   use Class::constr;
   
   package SubClass;
   our @ISA = 'BaseClass';
   
   package main;
   $obj = SubClass->new;
   
   # object
   $obj->an_object_prop;        # accessor callable through the object
   $obj->{an_object_prop};      # underlaying scalar in object $obj
   
   # class
   $obj->a_class_prop;          # accessor callable through the object
   ref($obj)->a_class_prop;     # accessor callable through the object class
   $SubClass::a_class_prop;     # underlaying scalar in class 'SubClass'
   
   # package
   $obj->a_package_prop;        # accessor callable through the object
   ref($obj)->a_package_prop;   # accessor callable through the object class
                                # accessible through @ISA
   BaseClass->a_package_prop;   # accessor callable through the package
   $BaseClass::a_package_prop;  # underlaying scalar in package 'BaseClass'

The object property is stored into the object itself, a class property is stored in a global scalar in the object class itself, while a package property is sotored in the package that implements it.

Different underlaying scalars are suitable for different usages depending on the need to access them and to inherit the defaults.

Example

   package MyClass;
   use Class::constr ;
   use Object::props 'obj_prop' ;
   use Class::props qw( class_prop1
                        class_prop2 ) ;
   
   package main ;
   my $object1 = MyClass->new( obj_prop    => 1   ,
                               class_prop1 => 11 ) ;
   my $object2 = MyClass->new( obj_prop    => 2    ,
                               class_prop2 => 22 ) ;
   
   print $object1->obj_prop    ; # would print 1
   print $$object1{obj_prop}   ; # would print 1
   
   print $object2->obj_prop    ; # would print 2
   print $$object2{obj_prop}   ; # would print 2
   
   print $object1->class_prop1 ; # would print 11
   print $object2->class_prop1 ; # would print 11
   print $MyClass::class_prop1 ; # would print 11
   
   print $object1->class_prop2 ; # would print 22
   print $object2->class_prop2 ; # would print 22
   print $MyClass::class_prop2 ; # would print 22
   
   $object2->class_prop1 = 100 ; # object method
   MyClass->class_prop2  = 200 ; # static method works as well
   
   print $object1->class_prop1 ; # would print 100
   print $object2->class_prop1 ; # would print 100
   print $object1->class_prop2 ; # would print 200
   print $object2->class_prop2 ; # would print 200

Note: If you want to see some working example of this module, take a look at the source of my other distributions.

name

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::constr is implemented
    # by the Class::constr 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

If you pass a CODE reference as the default it will be evaluated only when the property will be accessed, and only if the property has no defined value (this allows "lazy" data computing and may save some CPU); the property will be set to the result of the referenced CODE.

You can reset a property to its default value by assigning it the undef value.

no_strict

validation

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 $_.

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

You can alse use the "validation" code as a sort of pre_process or filter for the input values: just assign to $_ in the validation code in order to change the actual imput value.

    # this will uppercase all input values
    use Object::props { name       => 'uppercase_it'
                        validation => sub { $_ = uc }
                      }
    # when used
    $object->uppercase_it = 'abc' # stored 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.

post_process

In the post_process code, the object is passed in $_[0] and the value to be transformed is passed in $_[1]; the accessor will return the value returned from the post_process code

    # this will uppercase all output values
    use Object::props { name         => 'uppercase_it'
                        post_process => sub { uc $_[1] }
                      }
    
    # when used
    $object->uppercase_it = 'aBc'; # stored value will be 'aBc'
    print $object->uppercase_it  ; # would print 'ABC'

Warning: The post_process code is ALWAYS executed in SCALAR context regardless the execution context of the accessor itself.

allowed

    use Object::props { name    => 'restricted'
                        allowed => [ qr/::allowed_sub1$/ ,
                                     qr/::allowed_sub2$/ ]
                      }

You can however force the assignation from not matching subs by setting $Class::props::force to a true value.

protected

You can however force the protection and set the property from outside the class that implements it by setting $Class::props::force to a true value.

add_to( package, properties )

   package Any::Package;
   Object::props->('My::Package', { name => 'any_name', ... });
   
   # which has the same effect of
   package My::Package;
   use Object::props { name => 'any_name', ... }