.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Class::props 3"
.TH Class::props 3 "2019-04-12" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::props \- Pragma to implement lvalue accessors with options
.SH "VERSION 2.41"
.IX Header "VERSION 2.41"
Included in OOTools 2.41 distribution.
.PP
The latest versions changes are reported in the \fIChanges\fR file in this distribution.
.PP
The distribution includes:
.IP "Package::props" 4
.IX Item "Package::props"
Pragma to implement lvalue accessors with options
.IP "Package::groups" 4
.IX Item "Package::groups"
Pragma to implement groups of properties accessors with options
.IP "Class::constr" 4
.IX Item "Class::constr"
Pragma to implement constructor methods
.IP "Class::props" 4
.IX Item "Class::props"
Pragma to implement lvalue accessors with options
.IP "Class::groups" 4
.IX Item "Class::groups"
Pragma to implement groups of properties accessors with options
.IP "Class::Error" 4
.IX Item "Class::Error"
Delayed checking of object failure
.IP "Class::Util" 4
.IX Item "Class::Util"
Class utility functions
.IP "Object::props" 4
.IX Item "Object::props"
Pragma to implement lvalue accessors with options
.IP "Object::groups" 4
.IX Item "Object::groups"
Pragma to implement groups of properties accessors with options
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.IP "Prerequisites" 4
.IX Item "Prerequisites"
.Vb 1
\&    Perl version >= 5.6.1
.Ve
.IP "\s-1CPAN\s0" 4
.IX Item "CPAN"
.Vb 1
\&    perl \-MCPAN \-e \*(Aqinstall OOTools\*(Aq
.Ve
.IP "Standard installation" 4
.IX Item "Standard installation"
From the directory where this file is located, type:
.Sp
.Vb 4
\&    perl Makefile.PL
\&    make
\&    make test
\&    make install
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Class"
.IX Subsection "Class"
.Vb 1
\&    package MyClass ;
\&    
\&    # implement constructor without options
\&    use Class::constr ;
\&    
\&    # just accessors without options (list of strings)
\&    use Class::props @prop_names ;                       # @prop_names (1)
\&    
\&    # a property with validation and default (list of hash refs)
\&    use Class::props { name       => \*(Aqdigits\*(Aq,
\&                       validation => sub{ /^\ed+\ez/ } ,    # just digits
\&                       default    => 10
\&                     } ;
\&    
\&    # a group of properties with common full options
\&    use Class::props { name       => \e@prop_names2,      # @prop_names2 (1)
\&                       default    => sub{$_[0]\->other_default} ,
\&                       validation => sub{ /\ew+/ } ,
\&                       protected  => 1 ,
\&                       no_strict  => 1 ,
\&                       allowed    => qr/::allowed_sub$/
\&                     } ;
\&                     
\&    # all the above in just one step (list of strings and hash refs)
\&    use Class::props @prop_names ,                       # @prop_names (1)
\&                     { name       => \*(Aqdigits\*(Aq,
\&                       validation => sub{ /^\ed+\ez/ } ,
\&                       default    => 10
\&                     } ,
\&                     { name       => \e@prop_names2,      # @prop_names2 (1)
\&                       default    => sub{$_[0]\->other_default} ,
\&                       validation => sub{ /\ew+/ } ,
\&                       protected  => 1 ,
\&                       no_strict  => 1 ,
\&                       allowed    => qr/::allowed_sub$/
\&                     } ;
\&                     
\&    # (1) must be set in a BEGIN block to have effect at compile time
.Ve
.SS "Usage"
.IX Subsection "Usage"
.Vb 1
\&    $object = MyClass\->new(digits => \*(Aq123\*(Aq);
\&    
\&    $object\->digits    = \*(Aq123\*(Aq;
\&    MyClass\->digits    = \*(Aq123\*(Aq;  # same thing
\&    
\&    $object\->digits(\*(Aq123\*(Aq);      # old way supported
\&    
\&    $d = $object\->digits;     # $d == 123
\&    $d = $MyClass::digits     # $d == 123
\&    
\&    undef $object\->digits        # $object\->digits == 10 (default)
\&    
\&    # these would croak
\&    $object\->digits    = "xyz";
\&    MyClass\->digits    = "xyz";
\&
\&    # this will bypass the accessor whithout croaking
\&    $MyClass::digits   = "xyz";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This pragma easily implements lvalue accessor methods for the properties of your Class (\fIlvalue\fR means that you can create a reference to it, assign to it and apply a regex to it; see also \*(L"\s-1KNOWN ISSUE\*(R"\s0), which are very efficient function templates that your modules may import at compile time. \*(L"This technique saves on both compile time and memory use, and is less error-prone as well, since syntax checks happen at compile time.\*(R" (quoted from \*(L"Function Templates\*(R" in the \fIperlref\fR manpage).
.PP
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.
.PP
The accessor method creates a scalar in the class that implements it (e.g. \f(CW$Class::any_property\fR) and sets/gets it using the options you set.
.PP
This module allows also \*(L"lazy\*(R" data computing (see the \f(CW\*(C`default\*(C'\fR option).
.PP
\&\fB\s-1IMPORTANT NOTE\s0\fR: Since the version 1.7 the options are ignored if you access the underlaying scalar without using the accessor, so you can directly access it when you need to bypass the options.
.SS "Package, Class or Object properties?"
.IX Subsection "Package, Class or Object properties?"
The main difference between  \f(CW\*(C`Packages::props\*(C'\fR, \f(CW\*(C`Object::props\*(C'\fR and \f(CW\*(C`Class::props\*(C'\fR is the underlaying scalar that holds the value of the property.
.PP
Look at this example:
.PP
.Vb 4
\&   package BaseClass;
\&   use Object::props  \*(Aqan_object_prop\*(Aq;
\&   use Class::props   \*(Aqa_class_prop\*(Aq;
\&   use Package::props \*(Aqa_package_prop\*(Aq;
\&   
\&   use Class::constr;
\&   
\&   package SubClass;
\&   our @ISA = \*(AqBaseClass\*(Aq;
\&   
\&   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 \*(AqSubClass\*(Aq
\&   
\&   # 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 \*(AqBaseClass\*(Aq
.Ve
.PP
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.
.PP
Different underlaying scalars are suitable for different usages depending on the need to access them and to inherit the defaults.
.SS "Example"
.IX Subsection "Example"
.Vb 5
\&   package MyClass;
\&   use Class::constr ;
\&   use Object::props \*(Aqobj_prop\*(Aq ;
\&   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
.Ve
.PP
\&\fBNote\fR: If you want to see some working example of this module, take a look at the source of my other distributions.
.SH "OPTIONS"
.IX Header "OPTIONS"
.ie n .SS "name => $name"
.el .SS "name => \f(CW$name\fP"
.IX Subsection "name => $name"
The name of the property is used as the identifier to create the accessor method, and the scalar that contains it.
.PP
Given 'my_prop' as the class property name:
.PP
.Vb 2
\&    MyClass\->my_prop = 10 ;  # assign 10 to $MyClass::my_prop
\&    MyClass\->my_prop( 10 );  # assign 10 to $MyClass::my_prop
\&    
\&    # assuming $object is an object of class MyClass
\&    $object\->my_prop = 10 ;  # assign 10 to $MyClass::my_prop
\&    $object\->my_prop( 10 );  # assign 10 to $MyClass::my_prop
\&    
\&    # same thing if MyClass::constr is implemented
\&    # by the Class::constr pragma
\&    
\&    $object = MyClass\->new( my_prop => 10 );
.Ve
.PP
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 \*(L"\s-1SYNOPSYS\*(R"\s0.
.ie n .SS "default => $value | \e&code"
.el .SS "default => \f(CW$value\fP | \e&code"
.IX Subsection "default => $value | &code"
Use this option to set a \fIdefault value\fR. If any \f(CW\*(C`validation\*(C'\fR option is set, then the \fIdefault value\fR is validated as well (the \f(CW\*(C`no_strict\*(C'\fR option override this).
.PP
If you pass a \s-1CODE\s0 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 \*(L"lazy\*(R" data computing and may save some \s-1CPU\s0); the property will be set to the result of the referenced \s-1CODE.\s0
.PP
You can reset a property to its default value by assigning it the undef value.
.SS "no_strict  => 0 | 1"
.IX Subsection "no_strict => 0 | 1"
With \f(CW\*(C`no_strict\*(C'\fR option set to a true value, the \f(CW\*(C`default\*(C'\fR value will not be validate even if a validation option is set. Without this option the method will croak if the \f(CW\*(C`default\*(C'\fR are not valid.
.SS "validation => \e&code"
.IX Subsection "validation => &code"
You can set a code reference to validate a new value. If you don't set any \f(CW\*(C`validation\*(C'\fR option, no validation will be done on the assignment.
.PP
In the validation code, the object or class is passed in \f(CW$_[0]\fR and the value to be validated is passed in \f(CW$_[1]\fR and for regexing convenience it is aliased in \f(CW$_\fR.
.PP
.Vb 6
\&    # web color validation
\&    use Class::props { name       => \*(Aqweb_color\*(Aq
\&                     , validation => sub { /^#[0\-9A\-F]{6}$/ }
\&                     } ;
\&    # this would croak
\&    $object\->web_color = \*(Aqdark gray\*(Aq ;
.Ve
.PP
You can alse use the \f(CW\*(C`validation\*(C'\fR code as a sort of pre_process or filter for the input values: just assign to \f(CW$_\fR in the validation code in order to change the actual imput value.
.PP
.Vb 6
\&    # this will uppercase all input values
\&    use Class::props { name       => \*(Aquppercase_it\*(Aq
\&                     , validation => sub { $_ = uc }
\&                     } ;
\&    # when used
\&    $object\->uppercase_it = \*(Aqabc\*(Aq ; # stored value will be \*(AqABC\*(Aq
.Ve
.PP
The validation code should return true on success and false on failure. Croak explicitly if you don't like the default error message.
.SS "post_process => \e&code"
.IX Subsection "post_process => &code"
You can set a code reference to transform the stored value, just before it is returned. If you don't set any \f(CW\*(C`post_process\*(C'\fR option, no transformation will be done on the returned value, so in that case the returned value will be the same stored value.
.PP
In the post_process code, the object or class is passed in \f(CW$_[0]\fR and the value to be transformed is passed in \f(CW$_[1]\fR, and for regexing convenience it is aliased in \f(CW$_\fR; the accessor will return the value returned from the post_process code
.PP
.Vb 4
\&    # this will uppercase all output values
\&    use Class::props { name         => \*(Aquppercase_it\*(Aq
\&                     , post_process => sub { uc }
\&                     }
\&    
\&    # when used
\&    Class\->uppercase_it = \*(AqaBc\*(Aq; # stored value will be \*(AqaBc\*(Aq
\&    print Class\->uppercase_it  ; # would print \*(AqABC\*(Aq
.Ve
.PP
\&\fBWarning\fR: The post_process code is \s-1ALWAYS\s0 executed in \s-1SCALAR\s0 context regardless the execution context of the accessor itself.
.ie n .SS "allowed => $re | \e@res"
.el .SS "allowed => \f(CW$re\fP | \e@res"
.IX Subsection "allowed => $re | @res"
The property is settable only by the caller sub that matches with the content of this option. The content can be a compiled \s-1RE\s0 or a simple string that will be used to check the caller. (Pass an array ref for multiple items)
.PP
.Vb 4
\&    use Class::props { name    => \*(Aqrestricted\*(Aq
\&                       allowed => [ qr/::allowed_sub1$/ ,
\&                                    qr/::allowed_sub2$/ ]
\&                     }
.Ve
.PP
You can however force the assignation from not matching subs by setting \f(CW$Class::props::force\fR to a true value.
.SS "protected => 0 | 1"
.IX Subsection "protected => 0 | 1"
Set this option to a true value and the property will be turned \fIread-only\fR 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.
.PP
You can however force the protection and set the property from outside the class that implements it by setting \f(CW$Class::props::force\fR to a true value.
.SH "METHODS"
.IX Header "METHODS"
.SS "add_to( package, properties )"
.IX Subsection "add_to( package, properties )"
This will add to the package \fIpackage\fR the accessors for the \fIproperties\fR. It is useful to add properties in other packages.
.PP
.Vb 2
\&   package Any::Package;
\&   Class:props\->(\*(AqMy::Package\*(Aq, { name => \*(Aqany_name\*(Aq, ... });
\&   
\&   # which has the same effect of
\&   package My::Package;
\&   use Class::props { name => \*(Aqany_name\*(Aq, ... }
.Ve
.SH "KNOWN ISSUE"
.IX Header "KNOWN ISSUE"
Due to the perl bug #17663 \fI(Perl 5 Debugger doesn't handle properly lvalue sub assignment)\fR, you must know that under the \fB\-d\fR switch the lvalue sub assignment will not work, so your program will not run as you expect.
.PP
In order to avoid the perl-bug you have 3 alternatives:
.IP "1." 4
patch perl itself as suggested in this post: http://www.talkaboutprogramming.com/group/comp.lang.perl.moderated/messages/13142.html (See also the cgi-builder-users mailinglist about that topic)
.IP "2." 4
use the lvalue sub assignment (e.g. \f(CW\*(C`$s\->any_property = \*(Aqsomething\*(Aq\*(C'\fR) only if you will never need \fB\-d\fR
.IP "3." 4
if you plan to use \fB\-d\fR, use only standard assignments (e.g. \f(CW\*(C`$s\->any_property(\*(Aqsomething\*(Aq)\*(C'\fR)
.PP
Maybe a next version of perl will fix the bug, or maybe lvalue subs will be banned forever, meanwhile be careful with lvalue sub assignment.
.SH "SUPPORT and FEEDBACK"
.IX Header "SUPPORT and FEEDBACK"
If you need support or if you want just to send me some feedback or request, please use this link: http://perl.4pro.net/?Class::props.
.SH "AUTHOR and COPYRIGHT"
.IX Header "AUTHOR and COPYRIGHT"
Copyright 2004\-2005 by Domizio Demichelis.
.PP
All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.
.SH "CREDITS"
.IX Header "CREDITS"
Thanks to Juerd Waalboer (http://search.cpan.org/author/JUERD) that with its \fIAttribute::Property\fR inspired the creation of this distribution.