NAME¶
Scalar::Properties - run-time properties on scalar variables
SYNOPSIS¶
use Scalar::Properties;
my $val = 0->true;
if ($val && $val == 0) {
print "yup, its true alright...\n";
}
my @text = (
'hello world'->greeting(1),
'forget it',
'hi there'->greeting(1),
);
print grep { $_->is_greeting } @text;
my $l = 'hello world'->length;
DESCRIPTION¶
Scalar::Properties attempts to make Perl more object-oriented by taking an idea
from Ruby: Everything you manipulate is an object, and the results of those
manipulations are objects themselves.
'hello world'->length
(-1234)->abs
"oh my god, it's full of properties"->index('g')
The first example asks a string to calculate its length. The second example asks
a number to calculate its absolute value. And the third example asks a string
to find the index of the letter 'g'.
Using this module you can have run-time properties on initialized scalar
variables and literal values. The word 'properties' is used in the Perl 6
sense: out-of-band data, little sticky notes that are attached to the value.
While attributes (as in Perl 5's attribute pragma, and see the
"Attribute::*" family of modules) are handled at compile-time,
properties are handled at run-time.
Internally properties are implemented by making their values into objects with
overloaded operators. The actual properties are then simply hash entries.
Most properties are simply notes you attach to the value, but some may have
deeper meaning. For example, the "true" and "false"
properties plays a role in boolean context, as the first example of the
Synopsis shows.
Properties can also be propagated between values. For details, see the EXPORTS
section below. Here is an example why this might be desirable:
pass_on('approximate');
my $pi = 3->approximate(1);
my $circ = 2 * $rad * $pi;
# now $circ->approximate indicates that this value was derived
# from approximate values
Please don't use properties whose name start with an underscore; these are
reserved for internal use.
You can set and query properties like this:
- "$var->myprop(1)"
- sets the property to a true value.
- "$var->myprop(0)"
- sets the property to a false value. Note that this doesn't
delete the property (to do so, use the "del_props" method
described below).
- "$var->is_myprop",
"$var->has_myprop"
- returns a true value if the property is set (i.e., defined
and has a true value). The two alternate interfaces are provided to make
querying attributes sound more natural. For example:
$foo->is_approximate;
$bar->has_history;
METHODS¶
Values thus made into objects also expose various utility methods. All of those
methods (unless noted otherwise) return the result as an overloaded value
ready to take properties and method calls itself, and don't modify the
original value.
INTROSPECTIVE METHODS¶
These methods help in managing a value's properties.
- "$var-"get_props>
- Get a list of names of the value's properties.
- "$var-"del_props(LIST)>
- Deletes one or more properties from the value. This is
different than setting the property value to zero.
- "$var-"del_all_props>
- Deletes all of the value's properties.
NUMERICAL METHODS¶
- "plus(EXPR)"
- Returns the value that is the sum of the value whose method
has been called and the argument value. This method also overloads
addition, so:
$a = 7 + 2;
$a = 7->plus(2); # the same
- "minus(EXPR)"
- Returns the value that is the the value whose method has
been called minus the argument value. This method also overloads
subtraction.
- "times(EXPR)"
- Returns the value that is the the value whose method has
been called times the argument value. This method also overloads
multiplication.
- "divide(EXPR)"
- Returns the value that is the the value whose method has
been called divided by the argument value. This method also overloads
division.
- "modulo(EXPR)"
- Returns the value that is the the value whose method has
been called modulo the argument value. This method also overloads the
modulo operator.
- "exp(EXPR)"
- Returns the value that is the the value whose method has
been called powered by the argument value. This method also overloads the
exponentiation operator.
- "abs"
- Returns the absolute of the value.
- "zero"
- Returns a boolean value indicating whether the value is
equal to 0.
STRING METHODS¶
- "length", "size"
- Returns the result of the built-in "length"
function applied to the value.
- "reverse"
- Returns the reverse string of the value.
- "uc", "ucfirst", "lc",
"lcfirst", "hex", "oct"
- Return the result of the appropriate built-in function
applied to the value.
- "concat(EXPR)", "append(EXPR)"
- Returns the result of the argument expression appended to
the value.
- "swapcase"
- Returns a version of the value with every character's case
reversed, i.e. a lowercase character becomes uppercase and vice
versa.
- "split /PATTERN/, LIMIT"
- Returns a list of overloaded values that is the result of
splitting (according to the built-in "split" function) the value
along the pattern, into a number of values up to the limit.
BOOLEAN METHODS¶
- "numcmp(EXPR)"
- Returns the (overloaded) value of the numerical three-way
comparison. This method also overloads the "<=>"
operator.
- "cmp(EXPR)"
- Returns the (overloaded) value of the alphabetical
three-way comparison. This method also overloads the "cmp"
operator.
- "eq(EXPR)", "ne(EXPR)",
"lt(EXPR)", "gt(EXPR)", "le(EXPR)",
"ge(EXPR)"
- Return the (overlaoded) boolean value of the appropriate
string comparison. These methods also overload those operators.
- "eqi(EXPR)", "nei(EXPR)",
"lti(EXPR)", "gti(EXPR)", "lei(EXPR)",
"gei(EXPR)"
- These methods are case-insensitive versions of the above
operators.
- "is_true", "is_false"
- Returns the (overloaded) boolean status of the value.
EXPORTS¶
Three subroutines dealing with how properties are propagated are automatically
exported. For an example of propagation, see the DESCRIPTION section above.
- "pass_on(LIST)"
- Sets (replaces) the list of properties that are passed on.
There is only one such list for the whole mechanism. The whole property
interface is experimental, but this one in particular is likely to change
in the future.
- "passed_on(STRING)"
- Tests whether a property is passed on and returns a boolean
value.
- "get_pass_on"
- Returns a list of names of properties that are passed
on.
If you talk about this module in blogs, on del.icio.us or anywhere else, please
use the "scalarproperties" tag.
BUGS AND LIMITATIONS¶
No bugs have been reported.
Please report any bugs or feature requests to
"bug-scalar-properties@rt.cpan.org", or through the web interface at
<
http://rt.cpan.org>.
INSTALLATION¶
See perlmodinstall for information and options on installing Perl modules.
AVAILABILITY¶
The latest version of this module is available from the Comprehensive Perl
Archive Network (CPAN). Visit <
http://www.perl.com/CPAN/> to find a CPAN
site near you. Or see
<
http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.
AUTHORS¶
Marcel Gruenauer, "<marcel@cpan.org>"
James A. Duncan "<jduncan@fotango.com>"
Some contributions from David Cantrell,
"<david@cantrell.org.uk>"
COPYRIGHT AND LICENSE¶
Copyright 2001-2007 by Marcel Gruenauer
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.