Debian Codegraph @

README

raw
1 NAME
2 Scalar::Properties - Run-time properties on scalar variables
3
4 VERSION
5 version 1.100860
6
7 SYNOPSIS
8 use Scalar::Properties;
9 my $val = 0->true;
10 if ($val && $val == 0) {
11 print "yup, its true alright...\n";
12 }
13
14 my @text = (
15 'hello world'->greeting(1),
16 'forget it',
17 'hi there'->greeting(1),
18 );
19 print grep { $_->is_greeting } @text;
20
21 my $l = 'hello world'->length;
22
23 DESCRIPTION
24 Scalar::Properties attempts to make Perl more object-oriented by taking
25 an idea from Ruby: Everything you manipulate is an object, and the
26 results of those manipulations are objects themselves.
27
28 'hello world'->length
29 (-1234)->abs
30 "oh my god, it's full of properties"->index('g')
31
32 The first example asks a string to calculate its length. The second
33 example asks a number to calculate its absolute value. And the third
34 example asks a string to find the index of the letter 'g'.
35
36 Using this module you can have run-time properties on initialized scalar
37 variables and literal values. The word 'properties' is used in the Perl
38 6 sense: out-of-band data, little sticky notes that are attached to the
39 value. While attributes (as in Perl 5's attribute pragma, and see the
40 "Attribute::*" family of modules) are handled at compile-time,
41 properties are handled at run-time.
42
43 Internally properties are implemented by making their values into
44 objects with overloaded operators. The actual properties are then simply
45 hash entries.
46
47 Most properties are simply notes you attach to the value, but some may
48 have deeper meaning. For example, the "true" and "false" properties
49 plays a role in boolean context, as the first example of the Synopsis
50 shows.
51
52 Properties can also be propagated between values. For details, see the
53 EXPORTS section below. Here is an example why this might be desirable:
54
55 pass_on('approximate');
56 my $pi = 3->approximate(1);
57 my $circ = 2 * $rad * $pi;
58
59 # now $circ->approximate indicates that this value was derived
60 # from approximate values
61
62 Please don't use properties whose name start with an underscore; these
63 are reserved for internal use.
64
65 You can set and query properties like this:
66
67 "$var->myprop(1)"
68 sets the property to a true value.
69
70 "$var->myprop(0)"
71 sets the property to a false value. Note that this doesn't delete
72 the property (to do so, use the "del_props" method described below).
73
74 "$var->is_myprop", "$var->has_myprop"
75 returns a true value if the property is set (i.e., defined and has a
76 true value). The two alternate interfaces are provided to make
77 querying attributes sound more natural. For example:
78
79 $foo->is_approximate;
80 $bar->has_history;
81
82 Values thus made into objects also expose various utility methods. All
83 of those methods (unless noted otherwise) return the result as an
84 overloaded value ready to take properties and method calls itself, and
85 don't modify the original value.
86
87 METHODS
88 get_props
89 Get a list of names of the value's properties.
90
91 del_props(LIST)
92 Deletes one or more properties from the value. This is different than
93 setting the property value to zero.
94
95 del_all_props
96 Deletes all of the value's properties.
97
98 plus(EXPR)
99 Returns the value that is the sum of the value whose method has been
100 called and the argument value. This method also overloads addition, so:
101
102 $a = 7 + 2;
103 $a = 7->plus(2); # the same
104
105 minus(EXPR)
106 Returns the value that is the the value whose method has been called
107 minus the argument value. This method also overloads subtraction.
108
109 times(EXPR)
110 Returns the value that is the the value whose method has been called
111 times the argument value. This method also overloads multiplication.
112
113 divide(EXPR)
114 Returns the value that is the the value whose method has been called
115 divided by the argument value. This method also overloads division.
116
117 modulo(EXPR)
118 Returns the value that is the the value whose method has been called
119 modulo the argument value. This method also overloads the modulo
120 operator.
121
122 exp(EXPR)
123 Returns the value that is the the value whose method has been called
124 powered by the argument value. This method also overloads the
125 exponentiation operator.
126
127 abs
128 Returns the absolute of the value.
129
130 zero
131 Returns a boolean value indicating whether the value is equal to 0.
132
133 length
134 Returns the result of the built-in "length" function applied to the
135 value.
136
137 size
138 Same as "length()".
139
140 reverse
141 Returns the reverse string of the value.
142
143 uc
144 Returns the result of the built-in function "uc()" applied to the value.
145
146 ucfirst
147 Returns the result of the built-in function "ucfirst()" applied to the
148 value.
149
150 lc
151 Returns the result of the built-in function "lc()" applied to the value.
152
153 lcfirst
154 Returns the result of the built-in function "lcfirst()" applied to the
155 value.
156
157 hex
158 Returns the result of the built-in function "hex()" applied to the
159 value.
160
161 oct
162 Returns the result of the built-in function "oct()" applied to the
163 value.
164
165 concat(EXPR)
166 Returns the result of the argument expression appended to the value.
167
168 append(EXPR)
169 Same as "concat(EXPR)".
170
171 swapcase
172 Returns a version of the value with every character's case reversed,
173 i.e. a lowercase character becomes uppercase and vice versa.
174
175 split /PATTERN/, LIMIT
176 Returns a list of overloaded values that is the result of splitting
177 (according to the built-in "split" function) the value along the
178 pattern, into a number of values up to the limit.
179
180 numcmp(EXPR)
181 Returns the (overloaded) value of the numerical three-way comparison.
182 This method also overloads the "<=>" operator.
183
184 cmp(EXPR)
185 Returns the (overloaded) value of the alphabetical three-way comparison.
186 This method also overloads the "cmp" operator.
187
188 eq(EXPR)
189 Return the (overloaded) boolean value of the "eq" string comparison.
190 This method also overloads that operators.
191
192 ne(EXPR)
193 Return the (overloaded) boolean value of the "ne" string comparison.
194 This method also overloads that operators.
195
196 lt(EXPR)
197 Return the (overloaded) boolean value of the "lt" string comparison.
198 This method also overloads that operators.
199
200 gt(EXPR)
201 Return the (overloaded) boolean value of the "gt" string comparison.
202 This method also overloads that operators.
203
204 le(EXPR)
205 Return the (overloaded) boolean value of the "le" string comparison.
206 This method also overloads that operators.
207
208 ge(EXPR)
209 Return the (overloaded) boolean value of the "ge" string comparison.
210 This method also overloads that operators.
211
212 eqi
213 Same as "eq()", but is case-insensitive.
214
215 nei>
216 Same as "ne()", but is case-insensitive.
217
218 lti
219 Same as "lt()", but is case-insensitive.
220
221 gti
222 Same as "gt()", but is case-insensitive.
223
224 lei
225 Same as "le()", but is case-insensitive.
226
227 gei
228 Same as "ge()", but is case-insensitive.
229
230 is_true
231 Returns whether the (overloaded) boolean status of the value is true.
232
233 is_false
234 Returns whether the (overloaded) boolean status of the value is false.
235
236 create
237 FIXME
238
239 del_prop
240 FIXME
241
242 do_downto
243 FIXME
244
245 do_downto_step
246 FIXME
247
248 do_upto
249 FIXME
250
251 do_upto_step
252 FIXME
253
254 false
255 FIXME
256
257 gen_meth
258 FIXME
259
260 handle
261 FIXME
262
263 times_do
264 FIXME
265
266 true
267 FIXME
268
269 value
270 FIXME
271
272 FUNCTIONS
273 pass_on(LIST)
274 Sets (replaces) the list of properties that are passed on. There is only
275 one such list for the whole mechanism. The whole property interface is
276 experimental, but this one in particular is likely to change in the
277 future. This function is exported automatically.
278
279 passed_on(STRING)
280 Tests whether a property is passed on and returns a boolean value. This
281 function is exported automatically.
282
283 get_pass_on
284 Returns a list of names of properties that are passed on. This function
285 is exported automatically.
286
287 INSTALLATION
288 See perlmodinstall for information and options on installing Perl
289 modules.
290
291 BUGS AND LIMITATIONS
292 No bugs have been reported.
293
294 Please report any bugs or feature requests through the web interface at
295 <http://rt.cpan.org/Public/Dist/Display.html?Name=Scalar-Properties>.
296
297 AVAILABILITY
298 The latest version of this module is available from the Comprehensive
299 Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
300 CPAN site near you, or see
301 <http://search.cpan.org/dist/Scalar-Properties/>.
302
303 The development version lives at
304 <http://github.com/hanekomu/Scalar-Properties/>. Instead of sending
305 patches, please fork this project using the standard git and github
306 infrastructure.
307
308 AUTHOR
309 Marcel Gruenauer <[email protected]>
310
311 COPYRIGHT AND LICENSE
312 This software is copyright (c) 2001 by Marcel Gruenauer.
313
314 This is free software; you can redistribute it and/or modify it under
315 the same terms as the Perl 5 programming language system itself.
316