1Scalar::Properties(3) User Contributed Perl DocumentationScalar::Properties(3)
2
6 Scalar::Properties - run-time properties on scalar variables
7
9 use Scalar::Properties;
10 my $val = 0->true;
11 if ($val && $val == 0) {
12 print "yup, its true alright...\n";
13 }
14 my @text = (
16 'hello world'->greeting(1),
17 'forget it',
18 'hi there'->greeting(1),
19 );
20 print grep { $_->is_greeting } @text;
21 my $l = 'hello world'->length;
23
25 Scalar::Properties attempts to make Perl more object-oriented by taking
26 an idea from Ruby: Everything you manipulate is an object, and the
27 results of those manipulations are objects themselves.
28 'hello world'->length
30 (-1234)->abs
31 "oh my god, it's full of properties"->index('g')
32 The first example asks a string to calculate its length. The second
34 example asks a number to calculate its absolute value. And the third
35 example asks a string to find the index of the letter 'g'.
36 Using this module you can have run-time properties on initialized
38 scalar variables and literal values. The word 'properties' is used in
39 the Perl 6 sense: out-of-band data, little sticky notes that are
40 attached to the value. While attributes (as in Perl 5's attribute
41 pragma, and see the "Attribute::*" family of modules) are handled at
42 compile-time, properties are handled at run-time.
43 Internally properties are implemented by making their values into
45 objects with overloaded operators. The actual properties are then
46 simply hash entries.
47 Most properties are simply notes you attach to the value, but some may
49 have deeper meaning. For example, the "true" and "false" properties
50 plays a role in boolean context, as the first example of the Synopsis
51 shows.
52 Properties can also be propagated between values. For details, see the
54 EXPORTS section below. Here is an example why this might be desirable:
55 pass_on('approximate');
57 my $pi = 3->approximate(1);
58 my $circ = 2 * $rad * $pi;
59 # now $circ->approximate indicates that this value was derived
61 # from approximate values
62 Please don't use properties whose name start with an underscore; these
64 are reserved for internal use.
65 You can set and query properties like this:
67 "$var->myprop(1)"
69 sets the property to a true value.
70 "$var->myprop(0)"
72 sets the property to a false value. Note that this doesn't delete
73 the property (to do so, use the "del_props" method described
74 below).
75 "$var->is_myprop", "$var->has_myprop"
77 returns a true value if the property is set (i.e., defined and has
78 a true value). The two alternate interfaces are provided to make
79 querying attributes sound more natural. For example:
80 $foo->is_approximate;
82 $bar->has_history;
83
85 Values thus made into objects also expose various utility methods. All
86 of those methods (unless noted otherwise) return the result as an
87 overloaded value ready to take properties and method calls itself, and
88 don't modify the original value.
89 INTROSPECTIVE METHODS
91 These methods help in managing a value's properties.
92 "$var-"get_props>
94 Get a list of names of the value's properties.
95 "$var-"del_props(LIST)>
97 Deletes one or more properties from the value. This is different
98 than setting the property value to zero.
99 "$var-"del_all_props>
101 Deletes all of the value's properties.
102 NUMERICAL METHODS
104 "plus(EXPR)"
105 Returns the value that is the sum of the value whose method has
106 been called and the argument value. This method also overloads
107 addition, so:
108 $a = 7 + 2;
110 $a = 7->plus(2); # the same
111 "minus(EXPR)"
113 Returns the value that is the the value whose method has been
114 called minus the argument value. This method also overloads
115 subtraction.
116 "times(EXPR)"
118 Returns the value that is the the value whose method has been
119 called times the argument value. This method also overloads
120 multiplication.
121 "divide(EXPR)"
123 Returns the value that is the the value whose method has been
124 called divided by the argument value. This method also overloads
125 division.
126 "modulo(EXPR)"
128 Returns the value that is the the value whose method has been
129 called modulo the argument value. This method also overloads the
130 modulo operator.
131 "exp(EXPR)"
133 Returns the value that is the the value whose method has been
134 called powered by the argument value. This method also overloads
135 the exponentiation operator.
136 "abs"
138 Returns the absolute of the value.
139 "zero"
141 Returns a boolean value indicating whether the value is equal to 0.
142 STRING METHODS
144 "length", "size"
145 Returns the result of the built-in "length" function applied to the
146 value.
147 "reverse"
149 Returns the reverse string of the value.
150 "uc", "ucfirst", "lc", "lcfirst", "hex", "oct"
152 Return the result of the appropriate built-in function applied to
153 the value.
154 "concat(EXPR)", "append(EXPR)"
156 Returns the result of the argument expression appended to the
157 value.
158 "swapcase"
160 Returns a version of the value with every character's case
161 reversed, i.e. a lowercase character becomes uppercase and vice
162 versa.
163 "split /PATTERN/, LIMIT"
165 Returns a list of overloaded values that is the result of splitting
166 (according to the built-in "split" function) the value along the
167 pattern, into a number of values up to the limit.
168 BOOLEAN METHODS
170 "numcmp(EXPR)"
171 Returns the (overloaded) value of the numerical three-way
172 comparison. This method also overloads the "<=>" operator.
173 "cmp(EXPR)"
175 Returns the (overloaded) value of the alphabetical three-way
176 comparison. This method also overloads the "cmp" operator.
177 "eq(EXPR)", "ne(EXPR)", "lt(EXPR)", "gt(EXPR)", "le(EXPR)", "ge(EXPR)"
179 Return the (overlaoded) boolean value of the appropriate string
180 comparison. These methods also overload those operators.
181 "eqi(EXPR)", "nei(EXPR)", "lti(EXPR)", "gti(EXPR)", "lei(EXPR)",
183 "gei(EXPR)"
184 These methods are case-insensitive versions of the above operators.
185 "is_true", "is_false"
187 Returns the (overloaded) boolean status of the value.
188
190 Three subroutines dealing with how properties are propagated are
191 automatically exported. For an example of propagation, see the
192 DESCRIPTION section above.
193 "pass_on(LIST)"
195 Sets (replaces) the list of properties that are passed on. There is
196 only one such list for the whole mechanism. The whole property
197 interface is experimental, but this one in particular is likely to
198 change in the future.
199 "passed_on(STRING)"
201 Tests whether a property is passed on and returns a boolean value.
202 "get_pass_on"
204 Returns a list of names of properties that are passed on.
205
207 If you talk about this module in blogs, on del.icio.us or anywhere
208 else, please use the "scalarproperties" tag.
209
211 No bugs have been reported.
212 Please report any bugs or feature requests to
214 "bug-scalar-properties@rt.cpan.org", or through the web interface at
215 <http://rt.cpan.org>.
216
218 See perlmodinstall for information and options on installing Perl
219 modules.
220
222 The latest version of this module is available from the Comprehensive
223 Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find
224 a CPAN site near you. Or see
225 <http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.
226
228 Marcel Gruenauer, "<marcel@cpan.org>"
229 James A. Duncan "<jduncan@fotango.com>"
231 Some contributions from David Cantrell, "<david@cantrell.org.uk>"
233
235 Copyright 2001-2007 by Marcel Gruenauer
236 This library is free software; you can redistribute it and/or modify it
238 under the same terms as Perl itself.
239perl v5.12.0 2007-10-18 Scalar::Properties(3)