.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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::Meta 3pm"
.TH Class::Meta 3pm "2021-01-08" "perl v5.32.0" "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::Meta \- Class automation, introspection, and data validation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Generate a class:
.PP
.Vb 3
\& package MyApp::Thingy;
\& use strict;
\& use Class::Meta;
\&
\& BEGIN {
\&
\& # Create a Class::Meta object for this class.
\& my $cm = Class::Meta\->new(
\& key => \*(Aqthingy\*(Aq,
\& default_type => \*(Aqstring\*(Aq,
\& );
\&
\& # Add a constructor.
\& $cm\->add_constructor(
\& name => \*(Aqnew\*(Aq,
\& create => 1,
\& );
\&
\& # Add a couple of attributes with generated methods.
\& $cm\->add_attribute(
\& name => \*(Aquuid\*(Aq,
\& authz => \*(AqREAD\*(Aq,
\& required => 1,
\& default => sub { Data::UUID\->new\->create_str },
\& );
\& $cm\->add_attribute(
\& name => \*(Aqname\*(Aq,
\& is => \*(Aqstring\*(Aq,
\& default => undef,
\& );
\& $cm\->add_attribute(
\& name => \*(Aqage\*(Aq,
\& is => \*(Aqinteger\*(Aq,
\& default => undef,
\& );
\&
\& # Add a custom method.
\& $cm\->add_method(
\& name => \*(Aqchk_pass\*(Aq,
\& view => \*(AqPUBLIC\*(Aq,
\& code => sub { ... },
\& );
\&
\& $cm\->build;
\& }
\&
\& sub chck_pass { ... }
.Ve
.PP
Or use Class::Meta::Express for a more pleasant declarative syntax (highly
recommended!):
.PP
.Vb 3
\& package MyApp::Thingy;
\& use strict;
\& use Class::Meta::Express;
\&
\& class {
\& meta thingy => ( default_type => \*(Aqstring\*(Aq );
\& ctor \*(Aqnew\*(Aq;
\& has uuid => (
\& authz => \*(AqREAD\*(Aq,
\& required => 1,
\& default => sub { Data::UUID\->new\->create_str },
\& );
\& has name => ( required => 1 );
\& has age => ( is => \*(Aqinteger\*(Aq );
\& method chk_pass => sub { ... }
\& };
.Ve
.PP
Now isn't that nicer? Then use the class:
.PP
.Vb 1
\& use MyApp::Thingy;
\&
\& my $thingy = MyApp::Thingy\->new( id => 19 );
\& print "ID: ", $thingy\->id, $/;
\& $thingy\->name(\*(AqLarry\*(Aq);
\& print "Name: ", $thingy\->name, $/;
\& $thingy\->age(42);
\& print "Age: ", $thingy\->age, $/;
.Ve
.PP
Or make use of the introspection \s-1API:\s0
.PP
.Vb 1
\& use MyApp::Thingy;
\&
\& my $class = MyApp::Thingy\->my_class;
\& my $thingy;
\&
\& print "Examining object of class ", $class\->package, $/;
\&
\& print "\enConstructors:\en";
\& for my $ctor ($class\->constructors) {
\& print " o ", $ctor\->name, $/;
\& $thingy = $ctor\->call($class\->package);
\& }
\&
\& print "\enAttributes:\en";
\& for my $attr ($class\->attributes) {
\& print " o ", $attr\->name, " => ", $attr\->get($thingy), $/;
\& if ($attr\->authz >= Class::Meta::SET && $attr\->type eq \*(Aqstring\*(Aq) {
\& $attr\->get($thingy, \*(Aqhey there!\*(Aq);
\& print " Changed to: ", $attr\->get($thingy), $/;
\& }
\& }
\&
\& print "\enMethods:\en";
\& for my $meth ($class\->methods) {
\& print " o ", $meth\->name, $/;
\& $meth\->call($thingy);
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Class::Meta provides an interface for automating the creation of Perl classes
with attribute data type validation. It differs from other such modules in
that it includes an introspection \s-1API\s0 that can be used as a unified interface
for all Class::Meta\-generated classes. In this sense, it is an implementation
of the \*(L"Facade\*(R" design pattern.
.SH "USAGE"
.IX Header "USAGE"
Before we get to the introspection \s-1API,\s0 let's take a look at how to create
classes with Class::Meta. Unlike many class automation modules for Perl, the
classes that Class::Meta builds do not inherit from Class::Meta. This frees
you from any dependencies on the interfaces that such a base class might
compel. For example, you can create whatever constructors you like, and name
them whatever you like.
.PP
First of all, you really want to be using
Class::Meta::Express to declare your Class::Meta
classes. It provides a much more pleasant class declaration experience than
Class::Meta itself does. But since its functions support many of the same
arguments as the declaration methods described here, it's worth it to skim the
notes here, as well. Or if you're just a masochist and want to use the
Class::Meta interface itself, well, read on!
.PP
I recommend that you create your Class::Meta classes in a \f(CW\*(C`BEGIN\*(C'\fR block.
Although this is not strictly necessary, it helps ensure that the classes
you're building are completely constructed and ready to go by the time
compilation has completed. Creating classes with Class::Meta is easy, using
the Class::Meta object oriented interface. Here is an example of a very simple
class:
.PP
.Vb 4
\& package MyApp::Dog;
\& use strict;
\& use Class::Meta;
\& use Class::Meta::Types::Perl;
\&
\& BEGIN {
\&
\& # Create a Class::Meta object for this class.
\& my $cm = Class::Meta\->new( key => \*(Aqdog\*(Aq );
\&
\& # Add a constructor.
\& $cm\->add_constructor(
\& name => \*(Aqnew\*(Aq,
\& create => 1,
\& );
\&
\& # Add an attribute.
\& $cm\->add_attribute(
\& name => \*(Aqtail\*(Aq,
\& type => \*(Aqscalar\*(Aq,
\& );
\&
\& # Add a custom method.
\& $cm\->add_method( name => \*(Aqwag\*(Aq );
\& $cm\->build;
\& }
\&
\& sub wag {
\& my $self = shift;
\& print "Wagging ", $self\->tail;
\& }
.Ve
.PP
This simple example shows of the construction of all three types of objects
supported by Class::Meta: constructors, attributes, and methods. Here's how
it does it:
.IP "\(bu" 4
First we load Class::Meta and Class::Meta::Types::Perl. The latter module
creates data types that can be used for attributes, including a \*(L"scalar\*(R"
data type.
.IP "\(bu" 4
Second, we create a Class::Meta object. It's okay to create it within the
\&\f(CW\*(C`BEGIN\*(C'\fR block, as it won't be needed beyond that. All Class::Meta classes
have a \f(CW\*(C`key\*(C'\fR that uniquely identifies them across an application. If none is
provided, the class name will be used, instead.
.IP "\(bu" 4
Next, we create a Class::Meta::Constructor object to describe a constructor
method for the class. The \f(CW\*(C`create\*(C'\fR parameter to the \f(CW\*(C`add_constructor()\*(C'\fR
method tells Class::Meta to create the constructor named "\f(CW\*(C`new()\*(C'\fR".
.IP "\(bu" 4
Then we call \f(CW\*(C`add_attribute()\*(C'\fR to create a single attribute, \*(L"tail\*(R". This is a
simple scalar attribute, meaning that any scalar value can be stored in
it. Class::Meta will create a Class::Meta::Attribute object that describes
this attribute, and will also shortly create accessor methods for the
attribute.
.IP "\(bu" 4
The \f(CW\*(C`add_method()\*(C'\fR method constructs a Class::Meta::Method object to describe
any methods written for the class. In this case, we've told Class::Meta that
there will be a \f(CW\*(C`wag()\*(C'\fR method.
.IP "\(bu" 4
And finally, we tell Class::Meta to build the class. This is the point at
which all constructors and accessor methods will be created in the class. In
this case, these include the \f(CW\*(C`new()\*(C'\fR constructor and a \f(CW\*(C`tail()\*(C'\fR accessor for
the \*(L"tail\*(R" attribute. And finally, Class::Meta will install another method,
\&\f(CW\*(C`my_class()\*(C'\fR. This method will return a Class::Meta::Class object that
describes the class, and provides the complete introspection \s-1API.\s0
.PP
Thus, the class the above code creates has this interface:
.PP
.Vb 4
\& sub my_class;
\& sub new;
\& sub tail;
\& sub wag;
.Ve
.SS "Data Types"
.IX Subsection "Data Types"
By default, Class::Meta loads no data types. If you attempt to create an
attribute without creating or loading the appropriate data type, you will
get an error.
.PP
But I didn't want to leave you out in the cold, so I created a whole bunch of
data types to get you started. Any of these will automatically be loaded by
Class::Meta if it is used to create an attribute. They can also be loaded
simply by \f(CW\*(C`use\*(C'\fRing the appropriate module. The modules are:
.IP "Class::Meta::Types::Perl" 4
.IX Item "Class::Meta::Types::Perl"
Typical Perl data types.
.RS 4
.IP "scalar" 4
.IX Item "scalar"
Any scalar value.
.IP "scalarref" 4
.IX Item "scalarref"
A scalar reference.
.IP "array" 4
.IX Item "array"
.PD 0
.IP "arrayref" 4
.IX Item "arrayref"
.PD
An array reference.
.IP "hash" 4
.IX Item "hash"
.PD 0
.IP "hashref" 4
.IX Item "hashref"
.PD
A hash reference.
.IP "code" 4
.IX Item "code"
.PD 0
.IP "coderef" 4
.IX Item "coderef"
.IP "closure" 4
.IX Item "closure"
.PD
A code reference.
.RE
.RS 4
.RE
.IP "Class::Meta::Types::String" 4
.IX Item "Class::Meta::Types::String"
.RS 4
.PD 0
.IP "string" 4
.IX Item "string"
.PD
Attributes of this type must contain a string value. Essentially, this means
anything other than a reference.
.RE
.RS 4
.RE
.IP "Class::Meta::Types::Boolean" 4
.IX Item "Class::Meta::Types::Boolean"
.RS 4
.PD 0
.IP "boolean" 4
.IX Item "boolean"
.IP "bool" 4
.IX Item "bool"
.PD
Attributes of this type store a boolean value. Implementation-wise, this means
either a 1 or a 0.
.RE
.RS 4
.RE
.IP "Class::Meta::Types::Numeric" 4
.IX Item "Class::Meta::Types::Numeric"
These data types are validated by the functions provided by
Data::Types.
.RS 4
.IP "whole" 4
.IX Item "whole"
A whole number.
.IP "integer" 4
.IX Item "integer"
An integer.
.IP "decimal" 4
.IX Item "decimal"
A decimal number.
.IP "real" 4
.IX Item "real"
A real number.
.IP "float" 4
.IX Item "float"
a floating point number.
.RE
.RS 4
.RE
.PP
Other data types may be added in the future. See the individual data type
modules for more information.
.SS "Accessors"
.IX Subsection "Accessors"
Class::Meta supports the creation of three different types of attribute
accessors: typical Perl single-method accessors, \*(L"affordance\*(R" accessors, and
\&\*(L"semi-affordance\*(R" accessors. The single accessors are named for their
attributes, and typically tend to look like this:
.PP
.Vb 5
\& sub tail {
\& my $self = shift;
\& return $self\->{tail} unless @_;
\& return $self\->{tail} = shift;
\& }
.Ve
.PP
Although this can be an oversimplification if the data type has associated
validation checks.
.PP
Affordance accessors provide at up to two accessors for every attribute: One
to set the value and one to retrieve the value. They tend to look like this:
.PP
.Vb 1
\& sub get_tail { shift\->{tail} }
\&
\& sub set_tail { shift\->{tail} = shift }
.Ve
.PP
These accessors offer a bit less overhead than the traditional Perl accessors,
in that they don't have to check whether they're called to get or set a
value. They also have the benefit of creating a psychological barrier to
misuse. Since traditional Perl accessors \fIcan\fR be created as read-only or
write-only accessors, one can't tell just by looking at them which is the
case. The affordance accessors make this point moot, as they make clear what
their purpose is.
.PP
Semi-affordance accessors are similar to affordance accessors in that they
provide at least two accessors for every attribute. However, the accessor that
fetches the value is named for the attribute. Thus, they tend to look like
this:
.PP
.Vb 1
\& sub tail { shift\->{tail} }
\&
\& sub set_tail { shift\->{tail} = shift }
.Ve
.PP
To get Class::Meta's data types to create affordance accessors, simply pass
the string \*(L"affordance\*(R" to them when you load them:
.PP
.Vb 1
\& use Class::Meta::Types::Perl \*(Aqaffordance\*(Aq;
.Ve
.PP
Likewise, to get them to create semi-affordance accessors, pass the string
\&\*(L"semi-affordance\*(R":
.PP
.Vb 1
\& use Class::Meta::Types::Perl \*(Aqsemi\-affordance\*(Aq;
.Ve
.PP
The boolean data type is the only one that uses a slightly different approach
to the creation of affordance accessors: It creates three of them. Assuming
you're creating a boolean attribute named \*(L"alive\*(R", it will create these
accessors:
.PP
.Vb 3
\& sub is_alive { shift\->{alive} }
\& sub set_alive_on { shift\->{alive} = 1 }
\& sub set_alive_off { shift\->{alive} = 0 }
.Ve
.PP
Incidentally, I stole the term \*(L"affordance\*(R" from Damian Conway's \*(L"Object
Oriented Perl,\*(R" pp 83\-84, where he borrows it from Donald Norman.
.PP
See Class::Meta::Type for details on creating new data
types.
.SS "Introspection \s-1API\s0"
.IX Subsection "Introspection API"
Class::Meta provides four classes the make up the introspection \s-1API\s0 for
Class::Meta\-generated classes. Those classes are:
.PP
\fIClass::Meta::Class\fR
.IX Subsection "Class::Meta::Class"
.PP
Describes the class. Each Class::Meta\-generated class has a single constructor
object that can be retrieved by calling a class' \f(CW\*(C`my_class()\*(C'\fR class
method. Using the Class::Meta::Class object, you can get access to all of the
other objects that describe the class. The relevant methods are:
.IP "constructors" 4
.IX Item "constructors"
Provides access to all of the Class::Meta::Constructor objects that describe
the class' constructors, and provide indirect access to those constructors.
.IP "attributes" 4
.IX Item "attributes"
Provides access to all of the Class::Meta::Attribute objects that describe the
class' attributes, and provide methods for indirectly getting and setting
their values.
.IP "methods" 4
.IX Item "methods"
Provides access to all of the Class::Meta::Method objects that describe the
class' methods, and provide indirect execution of those constructors.
.PP
\fIClass::Meta::Constructor\fR
.IX Subsection "Class::Meta::Constructor"
.PP
Describes a class constructor. Typically a class will have only a single
constructor, but there could be more, and client code doesn't necessarily know
its name. Class::Meta::Constructor objects resolve these issues by describing
all of the constructors in a class. The most useful methods are:
.IP "name" 4
.IX Item "name"
Returns the name of the constructor, such as \*(L"new\*(R".
.IP "call" 4
.IX Item "call"
Calls the constructor on an object, passing in the arguments passed to
\&\f(CW\*(C`call()\*(C'\fR itself.
.PP
\fIClass::Meta::Attribute\fR
.IX Subsection "Class::Meta::Attribute"
.PP
Describes a class attribute, including its name and data type. Attribute
objects are perhaps the most useful Class::Meta objects, in that they can
provide a great deal of information about the structure of a class. The most
interesting methods are:
.IP "name" 4
.IX Item "name"
Returns the name of the attribute.
.IP "type" 4
.IX Item "type"
Returns the name of the attribute's data type.
.IP "required" 4
.IX Item "required"
Returns true if the attribute is required to have a value.
.IP "once" 4
.IX Item "once"
Returns true if the attribute value can be set to a defined value only once.
.IP "set" 4
.IX Item "set"
Sets the value of an attribute on an object.
.IP "get" 4
.IX Item "get"
Returns the value of an attribute on an object.
.PP
\fIClass::Meta::Method\fR
.IX Subsection "Class::Meta::Method"
.PP
Describes a method of a class, including its name and context (class
vs. instance). The relevant methods are:
.IP "name" 4
.IX Item "name"
The method name.
.IP "context" 4
.IX Item "context"
The context of the method indicated by a value corresponding to either
Class::Meta::OBJECT or Class::Meta::CLASS.
.IP "call" 4
.IX Item "call"
Calls the method, passing in the arguments passed to \f(CW\*(C`call()\*(C'\fR itself.
.PP
Consult the documentation of the individual classes for a complete description
of their interfaces.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Class Methods"
.IX Subsection "Class Methods"
\fIdefault_error_handler\fR
.IX Subsection "default_error_handler"
.PP
.Vb 2
\& Class::Meta\->default_error_handler($code);
\& my $default_error_handler = Class::Meta\->default_error_handler;
.Ve
.PP
Sets the default error handler for Class::Meta classes. If no \f(CW\*(C`error_handler\*(C'\fR
attribute is passed to new, then this error handler will be associated with
the new class. The default default error handler uses \f(CW\*(C`Carp::croak()\*(C'\fR to
handle errors.
.PP
Note that if other modules are using Class::Meta that they will use your
default error handler unless you reset the default error handler to its
original value before loading them.
.PP
\fIhandle_error\fR
.IX Subsection "handle_error"
.PP
.Vb 1
\& Class::Meta\->handle_error($err);
.Ve
.PP
Uses the code reference returned by \f(CW\*(C`default_error_handler()\*(C'\fR to handle an
error. Used internally Class::Meta classes when no Class::Meta::Class object
is available. Probably not useful outside of Class::Meta unless you're
creating your own accessor generation class. Use the \f(CW\*(C`handle_error()\*(C'\fR
instance method in Class::Meta::Class, instead.
.PP
\fIfor_key\fR
.IX Subsection "for_key"
.PP
.Vb 1
\& my $class = Class::Meta\->for_key($key);
.Ve
.PP
Returns the Class::Meta::Class object for a class by its key name. This can be
useful in circumstances where the key has been used to track a class, and you
need to get a handle on that class. With the class package name, you can of
course simply call \f(CW\*(C`$pkg\->my_class\*(C'\fR; this method is the solution for
getting the class object for a class key.
.PP
\fIkeys\fR
.IX Subsection "keys"
.PP
.Vb 1
\& my @keys = Class::Meta\->keys;
.Ve
.PP
Returns the keys for all Class::Meta::Class objects. The order of keys is
not guaranteed. In scalar context, this method returns an array reference
containing the keys.
.PP
\fIclear\fR
.IX Subsection "clear"
.PP
.Vb 2
\& Class::Meta\->clear;
\& Class::Meta\->clear($key);
.Ve
.PP
Called without arguments, \f(CW\*(C`clear\*(C'\fR will remove all
Class::Meta::Class objects from memory. Called with an
argument, \f(CW\*(C`clear\*(C'\fR attempts to remove only that key from memory. Calling it
with a non-existent key is a no-op.
.PP
In general, you probably won't want to use this method, except perhaps in
tests, when you might need to do funky things with your classes.
.SS "Constructors"
.IX Subsection "Constructors"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\& my $cm = Class::Meta\->new( key => $key );
.Ve
.PP
Constructs and returns a new Class::Meta object that can then be used to
define and build the complete interface of a class. Many of the supported
parameters values will default to values specified for the most immediate
Class::Meta\-built parent class, if any. The supported parameters are:
.IP "package" 4
.IX Item "package"
The package that defines the class. Defaults to the package of the code
that calls \f(CW\*(C`new()\*(C'\fR.
.IP "key" 4
.IX Item "key"
A key name that uniquely identifies a class within an application. Defaults to
the value of the \f(CW\*(C`package\*(C'\fR parameter if not specified.
.IP "name" 4
.IX Item "name"
The human name to use for the class. Defaults to the value of \f(CW\*(C`key\*(C'\fR with
underscores replaced with spaces and each word capitalized by the \f(CW\*(C`ucfirst\*(C'\fR
operator. So \*(L"foo\*(R" will become \*(L"Foo\*(R" and \*(L"contact_type\*(R" will become \*(L"Contact
Type\*(R".
.IP "abstract" 4
.IX Item "abstract"
A boolean indicating whether the class being defined is an abstract class. An
abstract class, also known as a \*(L"virtual\*(R" class, is not intended to be used
directly. No objects of an abstract class should every be created. Instead,
classes that inherit from an abstract class must be implemented.
.IP "default_type" 4
.IX Item "default_type"
A data type to use for attributes added to the class with no explicit data
type. See \*(L"Data Types\*(R" for some possible values for this parameter.
Inheritable from parent class.
.IP "trust" 4
.IX Item "trust"
An array reference of key names or packages that are trusted by the class.
.Sp
.Vb 1
\& trust => [\*(AqFoo::Bar\*(Aq, \*(AqFoo::Bat\*(Aq],
.Ve
.Sp
Trusted packages and the classes that inherit from them can retrieve trusted
attributes and methods of the class. Trusted packages need not be Class::Meta
classes. Trusted classes do not include the declaring class by default, so if
you want the class that declares an attribute to be able to use trusted
attribute accessors, be sure to include it in the list of trusted packages:
.Sp
.Vb 1
\& trust => [_\|_PACKAGE_\|_, \*(AqFoo::Bar\*(Aq, \*(AqFoo::Bat\*(Aq],
.Ve
.Sp
If you need to trust a single class, you may pass in the key name or package
of that class rather than an array reference:
.Sp
.Vb 1
\& trust => \*(AqFoo::Bar\*(Aq,
.Ve
.IP "class_class" 4
.IX Item "class_class"
The name of a class that inherits from Class::Meta::Class to be used to create
all of the class objects for the class. Defaults to Class::Meta::Class.
Inheritable from parent class.
.IP "constructor_class" 4
.IX Item "constructor_class"
The name of a class that inherits from Class::Meta::Constructor to be used to
create all of the constructor objects for the class. Defaults to
Class::Meta::Constructor. Inheritable from parent class.
.IP "attribute_class" 4
.IX Item "attribute_class"
The name of a class that inherits from Class::Meta::Attribute to be used to
create all of the attribute objects for the class. Defaults to
Class::Meta::Attribute. Inheritable from parent class.
.IP "method_class" 4
.IX Item "method_class"
The name of a class that inherits from Class::Meta::Method to be used to
create all of the method objects for the class. Defaults to
Class::Meta::Method. Inheritable from parent class.
.IP "error_handler" 4
.IX Item "error_handler"
A code reference that will be used to handle errors thrown by the methods
created for the new class. Defaults to the value returned by \f(CW\*(C`Class::Meta\->default_error_handler\*(C'\fR. Inheritable from parent class.
.PP
\fIadd_constructor\fR
.IX Subsection "add_constructor"
.PP
.Vb 4
\& $cm\->add_constructor(
\& name => \*(Aqconstruct\*(Aq,
\& create => 1,
\& );
.Ve
.PP
Creates and returns a Class::Meta::Constructor object that describes a
constructor for the class. The supported parameters are:
.IP "name" 4
.IX Item "name"
The name of the constructor. The name must consist of only alphanumeric
characters or \*(L"_\*(R". Required.
.IP "create" 4
.IX Item "create"
When true, Class::Meta::Constructor will automatically create and install a
constructor named for the \f(CW\*(C`name\*(C'\fR parameter. Defaults to true unless \f(CW\*(C`code\*(C'\fR
is passed. In general you won't need to specify this parameter unless you've
written your own constructor in the package, in which case you'll want to
specify \f(CW\*(C`create => 0\*(C'\fR.
.IP "label" 4
.IX Item "label"
A label for the constructor. Generally used for displaying its name in a user
interface. Optional.
.IP "desc" 4
.IX Item "desc"
A description of the constructor. Possibly useful for displaying help text in
a user interface. Optional.
.IP "code" 4
.IX Item "code"
You can implicitly define the constructor in your class by passing a code
reference via the \f(CW\*(C`code\*(C'\fR parameter. Once \f(CW\*(C`build()\*(C'\fR is called,
Kinetic::Meta::Constructor will install the
constructor into the package for which the Class::Meta object was defined, and
with the name specified via the \f(CW\*(C`name\*(C'\fR parameter. Note that if the
constructor view is \s-1PRIVATE\s0 or \s-1PROTECTED,\s0 the constructor will be wrapped in
extra code to constrain the view. Optional.
.IP "view" 4
.IX Item "view"
The visibility of the constructor. The possible values are defined by the
following constants:
.RS 4
.IP "Class::Meta::PUBLIC" 4
.IX Item "Class::Meta::PUBLIC"
Can be used by any client.
.IP "Class::Meta::PRIVATE" 4
.IX Item "Class::Meta::PRIVATE"
Can only be used by the declaring class.
.IP "Class::Meta::TRUSTED" 4
.IX Item "Class::Meta::TRUSTED"
Can only be used by the classes specified by the \f(CW\*(C`trust\*(C'\fR parameter to
\&\f(CW\*(C`new()\*(C'\fR.
.IP "Class::Meta::PROTECTED" 4
.IX Item "Class::Meta::PROTECTED"
Can only be used by the declaring class or by classes that inherit from it.
.RE
.RS 4
.Sp
Defaults to Class::Meta::PUBLIC if not defined. You can also use strings
aliases to the above constants, although the constant values will actually be
stored in the Class::Meta::Constructor object,
rather than the string. The supported strings are \*(L"\s-1PUBLIC\*(R", \*(L"PRIVATE\*(R",
\&\*(L"TRUSTED\*(R",\s0 and \*(L"\s-1PROTECTED\*(R".\s0
.RE
.IP "caller" 4
.IX Item "caller"
A code reference that calls the constructor. Defaults to a code reference that
calls a method with the name provided by the \f(CW\*(C`name\*(C'\fR attribute on the class
being defined.
.PP
If Class::Meta creates the constructor, it will be a simple parameter-list
constructor, wherein attribute values can be passed as a list of
attribute\-name/value pairs, e.g.:
.PP
.Vb 4
\& my $thingy = MyApp::Thingy\->new(
\& name => \*(AqLarry\*(Aq,
\& age => 32,
\& );
.Ve
.PP
Required attributes must have a value passed to the constructor, with one
exception: You can pass an optional subroutine reference as the last argument
to the constructor. After all parameter values and default values have been
set on the object, but before any exceptions are thrown for undefined required
attributes, the constructor will execute this subroutine reference, passing in
the object being constructed as the sole argument. So, for example, if \f(CW\*(C`name\*(C'\fR
is required but, for some reason, could not be set before constructing the
object, you could set it like so:
.PP
.Vb 9
\& my $thingy = MyApp::Thingy\->new(
\& age => 32,
\& sub {
\& my $thingy = shift;
\& # age and attributes with default values are already set.
\& my $name = calculate_name( $thingy );
\& $thingy\->name($name);
\& },
\& );
.Ve
.PP
This allows developers to have a scope-limited context in which to work before
required constraints are enforced.
.PP
\fIadd_attribute\fR
.IX Subsection "add_attribute"
.PP
.Vb 4
\& $cm\->add_attribute(
\& name => \*(Aqtail\*(Aq,
\& type => \*(Aqscalar\*(Aq,
\& );
.Ve
.PP
Creates and returns a Class::Meta::Attribute object that describes an
attribute of the class. The supported parameters are:
.IP "name" 4
.IX Item "name"
The name of the attribute. The name must consist of only alphanumeric
characters or \*(L"_\*(R". Required.
.IP "type" 4
.IX Item "type"
.PD 0
.IP "is" 4
.IX Item "is"
.PD
The data type of the attribute. See \*(L"Data Types\*(R" for some possible values
for this parameter. If the type name corresponds to a data type in a package
in the Class::Meta::Types name space, that package will automatically be
loaded and configured with Perl-style accessors, so that the data type can
simply be used. If both \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`is\*(C'\fR are passed, \f(CW\*(C`is\*(C'\fR will be used.
Required unless the class was declared with a \f(CW\*(C`default_type\*(C'\fR.
.IP "required" 4
.IX Item "required"
A boolean value indicating whether the attribute is required to have a value.
Defaults to false.
.IP "once" 4
.IX Item "once"
A boolean value indicating whether the attribute can be set to a defined value
only once. Defaults to false.
.IP "label" 4
.IX Item "label"
A label for the attribute. Generally used for displaying its name in a user
interface. Optional.
.IP "desc" 4
.IX Item "desc"
A description of the attribute. Possibly useful for displaying help text in a
user interface. Optional.
.IP "view" 4
.IX Item "view"
The visibility of the attribute. See the description of the \f(CW\*(C`view\*(C'\fR parameter
to \f(CW\*(C`add_constructor\*(C'\fR for a description of its value.
.IP "authz" 4
.IX Item "authz"
The authorization of the attribute. This value indicates whether it is
read-only, write-only, read/write, or inaccessible. The possible values are
defined by the following constants:
.RS 4
.IP "Class::Meta::READ" 4
.IX Item "Class::Meta::READ"
.PD 0
.IP "Class::Meta::WRITE" 4
.IX Item "Class::Meta::WRITE"
.IP "Class::Meta::RDWR" 4
.IX Item "Class::Meta::RDWR"
.IP "Class::Meta::NONE" 4
.IX Item "Class::Meta::NONE"
.RE
.RS 4
.PD
.Sp
Defaults to Class::Meta::RDWR if not defined. You can also use strings aliases
to the above constants, although the constant values will actually be stored
in the Class::Meta::Attribute object, rather than
the string. The supported strings are \*(L"\s-1READ\*(R", \*(L"WRITE\*(R", \*(L"RDWR\*(R",\s0 and \*(L"\s-1NONE\*(R".\s0
.RE
.IP "create" 4
.IX Item "create"
Indicates what type of accessor or accessors are to be created for the
attribute.
.RS 4
.IP "Class::Meta::GET" 4
.IX Item "Class::Meta::GET"
Create read-only accessor(s).
.IP "Class::Meta::SET" 4
.IX Item "Class::Meta::SET"
Create write-only accessor(s).
.IP "Class::Meta::GETSET" 4
.IX Item "Class::Meta::GETSET"
Create read/write accessor(s).
.IP "Class::Meta::NONE" 4
.IX Item "Class::Meta::NONE"
Create no accessors.
.RE
.RS 4
.Sp
You can also use strings aliases to the above constants, although the constant
values will actually be stored in the
Class::Meta::Attribute object, rather than the
string. The supported strings are \*(L"\s-1GET\*(R", \*(L"SET\*(R", \*(L"GETSET\*(R",\s0 and \*(L"\s-1NONE\*(R".\s0
.Sp
If not unspecified, the value of the \f(CW\*(C`create\*(C'\fR parameter will correspond to
the value of the \f(CW\*(C`authz\*(C'\fR parameter like so:
.Sp
.Vb 6
\& authz create
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& READ => GET
\& WRITE => SET
\& RDWR => GETSET
\& NONE => NONE
.Ve
.Sp
The \f(CW\*(C`create\*(C'\fR parameter differs from the \f(CW\*(C`authz\*(C'\fR parameter in case you've
taken it upon yourself to create some accessors, and therefore don't need
Class::Meta to do so. For example, if you were using standard Perl-style
accessors, and needed to do something a little different by coding your own
accessor, you'd specify it like this:
.Sp
.Vb 6
\& $cm\->add_attribute(
\& name => $name,
\& type => $type,
\& authz => Class::Meta::RDWR,
\& create => Class::Meta::NONE
\& );
.Ve
.Sp
Just be sure that your custom accessor compiles before you call
\&\f(CW\*(C`$cm\->build\*(C'\fR so that Class::Meta::Attribute can get a handle on it for
its \f(CW\*(C`get()\*(C'\fR and/or \f(CW\*(C`set()\*(C'\fR methods.
.RE
.IP "context" 4
.IX Item "context"
The context of the attribute. This indicates whether it's a class attribute or
an object attribute. The possible values are defined by the following
constants:
.RS 4
.IP "Class::Meta::CLASS" 4
.IX Item "Class::Meta::CLASS"
.PD 0
.IP "Class::Meta::OBJECT" 4
.IX Item "Class::Meta::OBJECT"
.RE
.RS 4
.PD
.Sp
You can also use strings aliases to the above constants, although the constant
values will actually be stored in the
Class::Meta::Attribute object, rather than the
string. The supported strings are \*(L"\s-1CLASS\*(R",\s0 and \*(L"\s-1OBJECT\*(R".\s0
.RE
.IP "default" 4
.IX Item "default"
The default value for the attribute, if any. This may be either a literal
value or a code reference that will be executed to generate a default value.
.IP "override" 4
.IX Item "override"
If an attribute being added to a class has the same name as an attribute in a
parent class, Class::Meta will normally throw an exception. However, in some
cases you might want to override an attribute in a parent class to change its
properties. In such a case, pass a true value to the \f(CW\*(C`override\*(C'\fR parameter to
override the attribute and avoid the exception.
.PP
\fIadd_method\fR
.IX Subsection "add_method"
.PP
.Vb 1
\& $cm\->add_method( name => \*(Aqwag\*(Aq );
.Ve
.PP
Creates and returns a Class::Meta::Method object that describes a method of
the class. The supported parameters are:
.IP "name" 4
.IX Item "name"
The name of the method. The name must consist of only alphanumeric
characters or \*(L"_\*(R".
.IP "label" 4
.IX Item "label"
A label for the method. Generally used for displaying its name in a user
interface. Optional.
.IP "desc" 4
.IX Item "desc"
A description of the method. Possibly useful for displaying help text in a
user interface. Optional.
.IP "view" 4
.IX Item "view"
The visibility of the method. See the description of the \f(CW\*(C`view\*(C'\fR parameter to
\&\f(CW\*(C`add_constructor\*(C'\fR for a description of its value. Class::Meta only enforces
the \f(CW\*(C`view\*(C'\fR if the \f(CW\*(C`code\*(C'\fR parameter is used to define the method body.
Otherwise, it's up to the class implementation itself to do the job.
.IP "code" 4
.IX Item "code"
You can implicitly define the method in your class by passing a code reference
via the \f(CW\*(C`code\*(C'\fR parameter. Once \f(CW\*(C`build()\*(C'\fR is called,
Kinetic::Meta::Method will install the method into
the package for which the Class::Meta object was defined, and with the name
specified via the \f(CW\*(C`name\*(C'\fR parameter. If the \f(CW\*(C`view\*(C'\fR is anything other than
\&\s-1PUBLIC,\s0 it will be enforced.
.IP "context" 4
.IX Item "context"
The context of the method. This indicates whether it's a class method or an
object method. See the description of the \f(CW\*(C`context\*(C'\fR parameter to \f(CW\*(C`add_attribute\*(C'\fR
for a description of its value.
.IP "caller" 4
.IX Item "caller"
A code reference that calls the method. This code reference will be be used by
the \f(CW\*(C`call()\*(C'\fR method of Class::Meta::Method to execute
the method on behalf of an object. Defaults to a code reference that calls a
method with the name provided by the \f(CW\*(C`name\*(C'\fR attribute on the class being
defined.
.IP "args" 4
.IX Item "args"
A description of the arguments to the method. This can be anything you like,
but I recommend something like a string for a single argument, an array
reference for a list of arguments, or a hash reference for parameter
arguments.
.IP "returns" 4
.IX Item "returns"
A string describing the return value or values of the method.
.SS "Instance Methods"
.IX Subsection "Instance Methods"
\fIclass\fR
.IX Subsection "class"
.PP
.Vb 1
\& my $class = $cm\->class;
.Ve
.PP
Returns the instance of the Class::Meta::Class object that will be used to
provide the introspection \s-1API\s0 for the class being generated.
.PP
\fIbuild\fR
.IX Subsection "build"
.PP
.Vb 1
\& $cm\->build;
.Ve
.PP
Builds the class defined by the Class::Meta object, including the
\&\f(CW\*(C`my_class()\*(C'\fR class method, and all requisite constructors and accessors.
.SH "JUSTIFICATION"
.IX Header "JUSTIFICATION"
One might argue that there are already too many class automation and parameter
validation modules on \s-1CPAN.\s0 And one would be right. They range from simple
accessor generators, such as Class::Accessor, to simple
parameter validators, such as Params::Validate, to more
comprehensive systems, such as Class::Contract and
Class::Tangram. But, naturally, none of them could do
exactly what I needed.
.PP
What I needed was an implementation of the \*(L"Facade\*(R" design pattern. Okay, this
isn't a facade like the \*(L"Gang of Four\*(R" meant it, but it is in the respect that
it creates classes with a common \s-1API\s0 so that objects of these classes can all
be used identically, calling the same methods on each. This is done via the
implementation of an introspection \s-1API.\s0 So the process of creating classes
with Class::Meta not only creates attributes and accessors, but also creates
objects that describe those classes. Using these descriptive objects, client
applications can determine what to do with objects of Class::Meta\-generated
classes. This is particularly useful for user interface code.
.SH "TO DO"
.IX Header "TO DO"
.IP "\(bu" 4
Add support for an \f(CW\*(C`accessor\*(C'\fR parameter to \f(CW\*(C`add_attribute()\*(C'\fR that will be
used for the accessor instead of generating one.
.IP "\(bu" 4
Make class attribute accessors behave as they do in Class::Data::Inheritable.
.IP "\(bu" 4
Modify class attribute accessors so that they are thread safe. This will
involve sharing the attributes across threads, and locking them before
changing their values. If they've also been made to behave as they do in
Class::Data::Inheritable, we'll have to figure out a way to make it so that
newly generated accessors for subclasses are shared between threads, too. This
may not be easy.
.SH "SUPPORT"
.IX Header "SUPPORT"
This module is stored in an open GitHub
repository . Feel free to fork and
contribute!
.PP
Please file bug reports via GitHub
Issues or by sending mail to
bug\-Class\-Meta@rt.cpan.org .
.SH "AUTHOR"
.IX Header "AUTHOR"
David E. Wheeler
.SH "SEE ALSO"
.IX Header "SEE ALSO"
First of all, use Class::Meta::Express instead of
Class::Meta to declare your classes. I hope I've made that clear enough by
now.
.PP
Other classes of interest within the Class::Meta distribution include:
.IP "Class::Meta::Class" 4
.IX Item "Class::Meta::Class"
.PD 0
.IP "Class::Meta::Constructor" 4
.IX Item "Class::Meta::Constructor"
.IP "Class::Meta::Attribute" 4
.IX Item "Class::Meta::Attribute"
.IP "Class::Meta::Method" 4
.IX Item "Class::Meta::Method"
.IP "Class::Meta::Type" 4
.IX Item "Class::Meta::Type"
.IP "Class::Meta::Types::Perl" 4
.IX Item "Class::Meta::Types::Perl"
.IP "Class::Meta::Types::String" 4
.IX Item "Class::Meta::Types::String"
.IP "Class::Meta::Types::Boolean" 4
.IX Item "Class::Meta::Types::Boolean"
.IP "Class::Meta::Types::Numeric" 4
.IX Item "Class::Meta::Types::Numeric"
.PD
.PP
For comparative purposes, you might also want to check out these fine modules:
.IP "Class::Accessor" 4
.IX Item "Class::Accessor"
Accessor and constructor automation.
.IP "Params::Validate" 4
.IX Item "Params::Validate"
Parameter validation.
.IP "Class::Contract" 4
.IX Item "Class::Contract"
Design by contract.
.IP "Class::Tangram" 4
.IX Item "Class::Tangram"
Accessor automation and data validation for Tangram applications.
.IP "Class::Maker" 4
.IX Item "Class::Maker"
An ambitious yet under-documented module that also manages accessor and
constructor generation, data validation, and provides a reflection \s-1API.\s0 It
also supports serialization.
.IP "Class::MOP" 4
.IX Item "Class::MOP"
Stevan Little's application of Perl 6 meta classes to Perl 5.
.IP "Moose" 4
.IX Item "Moose"
\&\*(L"It's the new camel.\*(R" Another extension of the Perl 5 object system, built on
Class::MOP.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2002\-2011, David E. Wheeler. Some Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.