view release on metacpan or  search on metacpan

Object.pod  view on Meta::CPAN

on which the attribute is defined. Two different objects with an attribute
of the same name retain separate copies of the attribute. They do not even
need to be the same datatype.

An attribute of type I<number> can take on any valid decimal numeric value
that Perl recognizes. Such an attribute can be created as follows:

    $obj->new_attr(-name => "price",
		   -type => "number",
		   -value => 1.99);

Any attempt to set this to a non-numeric value later would be treated
as an error.

The datatype of I<int> is similar to I<number> except that it restricts the
value to integers. Attempting to set the attribute to a numeric that is not
an integer, either when created or later modified, is not an error, but the
result will be silently truncated as if using the Perl C<int()> function.
An I<int> attribute can be created as follows:

    $obj->new_attr(-name => "experience",
		   -type => "int",
		   -value => 0);

An attribute of type I<string> is intended to contain any arbitrary, printable
text. This text can contain newlines and other text formatting characters such
as tabs. These will be treated correctly if the object is later saved to a
file. No special interpretation is performed on the data. Such an attribute
can be created as follows:

    $obj->new_attr(-name => "description",
		   -type => "string",
		   -value => "A long blade set in an ornamental scabbard of gold.");

The I<any> datatype is used for data that does not fall into any of the above
categories. No particular interpretation is performed on the data, and no
special abilities are associated with it. Use this datatype when you wish to
store references to arrays or hashes. The only caveat is that these complex
data structures must eventually work down to simple scalar types for the
data in the attribute to be C<save()>d correctly later. Do not use this for
object references, except for objects subclassed to Games::Object (this is
covered in more detail in an upcoming section). Here is an example of using
the I<any> datatype:

    $obj->new_attr(-name => "combat_skill_levels",
		   -type => "any",
		   -value => {
			melee		=> 4,
			ranged		=> 2,
			hand_to_hand	=> 3,
			magical		=> 5,
		   });

There is one more datatype called I<object>, which is intended to provided a
way for storing an object reference in an attribute. However, as there are
some special caveats and setup required, this is covered as a separate topic.

=item Split attributes

A "split" attribute is available only to datatypes I<number> and I<int>. An
attribute that is split maintains two separate values for the attribute, a
"real value" and a "current value" (or simply the "value"). An attribute that
is split in this way has the following properties:

=over 4

=item *

By default, when retrieving the value, the current value is returned.

=item *

The current value will "tend towards" the real value when the object's
C<process()> method is called (covered in a later section).

=item *

Both the current and real values can be manipulated independent of one another
(except where noted above with regards to the "tend to" processing).

=back

A split attribute is defined by specifying the additional parameter
I<-tend_to_rate>, as in this example:

    $obj->new_attr(-name => "health",
		   -type => "int",
		   -tend_to_rate => 1,
		   -value => 100);

This indicates that each time the object is processed, the current value will
tend towards the real by 1. The tend-to rate is always treated as a positive
number. Its sign is adjusted internally to reflect what direction the current
needs to go to reach the real (thus in this case if the real were less than
the current, 1 would be subtracted from the current when the object was
processed).

Note in the above example that in the absense of specifying what the starting
real value is, the real value will start off set to the current (in this case,
the value of 100). If you wish to start off the real at a different value
than the current, you add the I<-real_value> option, as in this example:

    $obj->new_attr(-name => "power",
		   -type => "number",
		   -tend_to_rate => 0.2,
		   -value => 0,
		   -real_value => 250);

=item Limited attributes

An attribute's value can be "limited", in that it is not allowed to go beyond
a certain range or a certain set of values.

Attributes of type I<number> and I<int> can be limited in range by adding the
I<-minimum> and I<-maximum> options when the attribute is created. Note that
you can choose to use one or the other or both. Example:

    $obj->new_attr(-name => "hit_points",
		   -type => "int",
		   -tend_to_rate => 1,
		   -value => 20,