view release on metacpan or  search on metacpan

lib/OOP.pm  view on Meta::CPAN

(or exit) in the event a user would choose to customize the class. 

=item B<PROTOTYPE>

This property contains all the properties and their I<definitions>. Collectively 
this represents the "I<prototype>" for the constructor of the user class.

The prototype is, in effect, the I<design> of how the properties are to be 
handled by the OOP class (and consequently the user class).

=back

These attributes happen to be the other two types of properties.  It is 
important to remember that unless otherwise specified all system attributes are 
required.  All system attributes are reserved meaning that a developer should 
never clutter the namespace by adding custom keys as they could override future 
developments causing for undesirable side-effects.  For this purpose use the 
B<CUSTOM> system attribute as a safe attribute to funnel your custom data 
through.

=item B<Prototype Properties>

This is possibly one of the coolest features of the OOP class.  It permits the 
developer to define accessibility to properties in more ways than just either 
hiding the information or not (encapsulation).  As a matter of fact it allows to 
control properties to an unprecendented level allowing the developer to control 
how much or how little access to a property a user class should have. 

The prototype is built by way of a hash that is passed to the constructor of the 
OOP class via the I<system attributes> (see above), as such:

  my $obj = OOP->new({
                      ARGS=> $objectProperties,
                      PROTOTYPE => {
                                    one => {
                                            dataType => 'hash',
                                            allowEmpty => 0,
                                            maxLength => 3,
                                            minLength => 1,
                                            readAccess => 1,
                                            required => 1,
                                            value => {
                                                      abye => '',
                                                      bbye => {...}
                                                     },
                                            writeAccess => 1                                      
                                           },
                                   two => 'foobar',
                                   three => [1,2,3,4]
                                  },
                      CUSTOM => {}
                     });

Attention should be given to the B<PROTOTYPE> attribute in the above 
illustration where we can see an example of how the prototype properties are 
implemented.

The above illustrates how to define the various restrictions to a particular 
property.  Keep in mind that this is only the prototype so it does not directly 
deal with data passed into a constructor.  One way of seeing it is as a template 
that is overlayed with the actual data from the constructor.

Providing a definition of a property is always optional.  If none is provided then 
various logical defaults apply.  If one does not provide definitions then it will 
be considered that the elements (or properties) in the prototype are not exclusive 
but they are required.  In other words one could add properties dynamically but the 
constructor of the user class would need to have at the very least the properties 
of the prototype passed to it.

The OOP class guesses that it is a property definition by finding the keyword 
I<dataType> which happens to be the only reserved keyword (for a hash key).  This means that when a user 
class uses the OOP class it should try to avoid using a parameter called "I<dataType>" 
as it will trigger the OOP class to process it as a parameter definition and subsequently 
process all other keys within that level of the hash as I<prototype properties>.  

Any other keywords in a property definition each have their own special effects. All 
of them are required as of this writing but could change in the future.  The one 
property worthy pointing out right now is I<value>.  

The I<value> property simply states that if this is the actual value associated with 
the parameter of whose definition we are in.  Thus, in the above example I<value> would 
be the value of the property I<one>.  

To expand on this example, if the property I<two> had a definition then 'foobar' would 
be shifted to I<value>, as such:

  my $obj = OOP->new({
                      ARGS=> $objectProperties,
                      PROTOTYPE => {
                                    one => {
				            abye => '',
				            bbye => {...}
 			                   },
 			            two => {
				            dataType => 'scalar',
				            allowEmpty => 0,
				            maxLength => 7,
				            minLength => 1,
				            readAccess => 1,
				            required => 1,
				            value => 'foobar',
				            writeAccess => 1                                      
 			                   },
 			            three => [1,2,3,4]
                                   },
                       CUSTOM => {}
                     });
                     
In the above example we also see how I<value> of I<one> is the actual value when 
no definition is provided.

The various properties are explained (in alphabetical order):

=over 2

=item B<allowEmpty> 

This is a boolean (0 or 1) that simply defines whether or not the value of this 
parameter is allowed to be empty.  If it is set to zero then there must be a value, 
otherwise a 1 would instruct that the value can be empty.