« blib/lib/Class/MakeMethods/Utility/TextBuilder.pm
↑ Summary
blib/lib/Class/MakeMethods/Emulator/MethodMaker.pm »
| 1 | =head1 NAME | ||||||||||||||||||
| 2 | |||||||||||||||||||
| 3 | Class::MakeMethods::Basic::Hash - Basic hash methods | ||||||||||||||||||
| 4 | |||||||||||||||||||
| 5 | |||||||||||||||||||
| 6 | =head1 SYNOPSIS | ||||||||||||||||||
| 7 | |||||||||||||||||||
| 8 | package MyObject; | ||||||||||||||||||
| 9 | use Class::MakeMethods::Basic::Hash ( | ||||||||||||||||||
| 10 | new => 'new', | ||||||||||||||||||
| 11 | scalar => [ 'foo', 'bar' ], | ||||||||||||||||||
| 12 | array => 'my_list', | ||||||||||||||||||
| 13 | hash => 'my_index', | ||||||||||||||||||
| 14 | ); | ||||||||||||||||||
| 15 | ... | ||||||||||||||||||
| 16 | |||||||||||||||||||
| 17 | # Constructor | ||||||||||||||||||
| 18 | my $obj = MyObject->new( foo => 'Foozle' ); | ||||||||||||||||||
| 19 | |||||||||||||||||||
| 20 | # Scalar Accessor | ||||||||||||||||||
| 21 | print $obj->foo(); | ||||||||||||||||||
| 22 | |||||||||||||||||||
| 23 | $obj->bar('Barbados'); | ||||||||||||||||||
| 24 | print $obj->bar(); | ||||||||||||||||||
| 25 | |||||||||||||||||||
| 26 | # Array accessor | ||||||||||||||||||
| 27 | $obj->my_list(0 => 'Foozle', 1 => 'Bang!'); | ||||||||||||||||||
| 28 | print $obj->my_list(1); | ||||||||||||||||||
| 29 | |||||||||||||||||||
| 30 | # Hash accessor | ||||||||||||||||||
| 31 | $obj->my_index('broccoli' => 'Blah!', 'foo' => 'Fiddle'); | ||||||||||||||||||
| 32 | print $obj->my_index('foo'); | ||||||||||||||||||
| 33 | |||||||||||||||||||
| 34 | |||||||||||||||||||
| 35 | =head1 DESCRIPTION | ||||||||||||||||||
| 36 | |||||||||||||||||||
| 37 | The Basic::Hash subclass of MakeMethods provides a basic constructor and accessors for blessed-hash object instances. | ||||||||||||||||||
| 38 | |||||||||||||||||||
| 39 | =head2 Calling Conventions | ||||||||||||||||||
| 40 | |||||||||||||||||||
| 41 | When you C<use> this package, the method names you provide | ||||||||||||||||||
| 42 | as arguments cause subroutines to be generated and installed in | ||||||||||||||||||
| 43 | your module. | ||||||||||||||||||
| 44 | |||||||||||||||||||
| 45 | See L<Class::MakeMethods::Basic/"Calling Conventions"> for a summary, or L<Class::MakeMethods/"USAGE"> for full details. | ||||||||||||||||||
| 46 | |||||||||||||||||||
| 47 | =head2 Declaration Syntax | ||||||||||||||||||
| 48 | |||||||||||||||||||
| 49 | To declare methods, pass in pairs of a method-type name followed | ||||||||||||||||||
| 50 | by one or more method names. Valid method-type names for this | ||||||||||||||||||
| 51 | package are listed in L<"METHOD GENERATOR TYPES">. | ||||||||||||||||||
| 52 | |||||||||||||||||||
| 53 | See L<Class::MakeMethods::Basic/"Declaration Syntax"> for more | ||||||||||||||||||
| 54 | syntax information. | ||||||||||||||||||
| 55 | |||||||||||||||||||
| 56 | |||||||||||||||||||
| 57 | =cut | ||||||||||||||||||
| 58 | |||||||||||||||||||
| 59 | package Class::MakeMethods::Basic::Hash; | ||||||||||||||||||
| 60 | |||||||||||||||||||
| 61 | 1 | $VERSION = 1.000; | |||||||||||||||||
| 62 | 1 | ▶ | use strict; | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 63 | 1 | ▶ | use Class::MakeMethods '-isasubclass'; | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 64 | |||||||||||||||||||
| 65 | ######################################################################## | ||||||||||||||||||
| 66 | |||||||||||||||||||
| 67 | =head1 METHOD GENERATOR TYPES | ||||||||||||||||||
| 68 | |||||||||||||||||||
| 69 | =head2 new - Constructor | ||||||||||||||||||
| 70 | |||||||||||||||||||
| 71 | For each method name passed, returns a subroutine with the following characteristics: | ||||||||||||||||||
| 72 | |||||||||||||||||||
| 73 | =over 4 | ||||||||||||||||||
| 74 | |||||||||||||||||||
| 75 | =item * | ||||||||||||||||||
| 76 | |||||||||||||||||||
| 77 | If called as a class method, makes a new hash and blesses it into that class. | ||||||||||||||||||
| 78 | |||||||||||||||||||
| 79 | =item * | ||||||||||||||||||
| 80 | |||||||||||||||||||
| 81 | If called on a hash-based instance, makes a copy of it and blesses the copy into the same class as the original instance. | ||||||||||||||||||
| 82 | |||||||||||||||||||
| 83 | =item * | ||||||||||||||||||
| 84 | |||||||||||||||||||
| 85 | If passed a list of key-value pairs, appends them to the new hash. These arguments override any copied values, and later arguments with the same name will override earlier ones. | ||||||||||||||||||
| 86 | |||||||||||||||||||
| 87 | =item * | ||||||||||||||||||
| 88 | |||||||||||||||||||
| 89 | Returns the new instance. | ||||||||||||||||||
| 90 | |||||||||||||||||||
| 91 | =back | ||||||||||||||||||
| 92 | |||||||||||||||||||
| 93 | Sample declaration and usage: | ||||||||||||||||||
| 94 | |||||||||||||||||||
| 95 | package MyObject; | ||||||||||||||||||
| 96 | use Class::MakeMethods::Basic::Hash ( | ||||||||||||||||||
| 97 | new => 'new', | ||||||||||||||||||
| 98 | ); | ||||||||||||||||||
| 99 | ... | ||||||||||||||||||
| 100 | |||||||||||||||||||
| 101 | # Bare constructor | ||||||||||||||||||
| 102 | my $empty = MyObject->new(); | ||||||||||||||||||
| 103 | |||||||||||||||||||
| 104 | # Constructor with initial values | ||||||||||||||||||
| 105 | my $obj = MyObject->new( foo => 'Foozle', bar => 'Barbados' ); | ||||||||||||||||||
| 106 | |||||||||||||||||||
| 107 | # Copy with overriding value | ||||||||||||||||||
| 108 | my $copy = $obj->new( bar => 'Bob' ); | ||||||||||||||||||
| 109 | |||||||||||||||||||
| 110 | =cut | ||||||||||||||||||
| 111 | |||||||||||||||||||
| 112 | 1 | ▶ | sub new { | ||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||
| 113 | 1 | my $class = shift; | |||||||||||||||||
| 114 | map { | ||||||||||||||||||
| 115 | 1 | my $name = $_; | |||||||||||||||||
| 116 | 4 | ▶ | $name => sub { | ||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=6.9
| |||||||||||||||||||
| 117 | 4 | my $callee = shift; | |||||||||||||||||
| 118 | 4 | ▶ | if ( ref $callee ) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 119 | 1 | bless { %$callee, @_ }, ref $callee; | |||||||||||||||||
| 120 | } else { | ||||||||||||||||||
| 121 | 3 | bless { @_ }, $callee; | |||||||||||||||||
| 122 | } | ||||||||||||||||||
| 123 | } | ||||||||||||||||||
| 124 | 1 | } @_; | |||||||||||||||||
| 125 | } | ||||||||||||||||||
| 126 | |||||||||||||||||||
| 127 | ######################################################################## | ||||||||||||||||||
| 128 | |||||||||||||||||||
| 129 | =head2 scalar - Instance Accessor | ||||||||||||||||||
| 130 | |||||||||||||||||||
| 131 | For each method name passed, uses a closure to generate a subroutine with the following characteristics: | ||||||||||||||||||
| 132 | |||||||||||||||||||
| 133 | =over 4 | ||||||||||||||||||
| 134 | |||||||||||||||||||
| 135 | =item * | ||||||||||||||||||
| 136 | |||||||||||||||||||
| 137 | Must be called on a hash-based instance. | ||||||||||||||||||
| 138 | |||||||||||||||||||
| 139 | =item * | ||||||||||||||||||
| 140 | |||||||||||||||||||
| 141 | Uses the method name as a hash key to access the related value for each instance. | ||||||||||||||||||
| 142 | |||||||||||||||||||
| 143 | =item * | ||||||||||||||||||
| 144 | |||||||||||||||||||
| 145 | If called without any arguments returns the current value. | ||||||||||||||||||
| 146 | |||||||||||||||||||
| 147 | =item * | ||||||||||||||||||
| 148 | |||||||||||||||||||
| 149 | If called with an argument, stores that as the value, and returns it, | ||||||||||||||||||
| 150 | |||||||||||||||||||
| 151 | =back | ||||||||||||||||||
| 152 | |||||||||||||||||||
| 153 | Sample declaration and usage: | ||||||||||||||||||
| 154 | |||||||||||||||||||
| 155 | package MyObject; | ||||||||||||||||||
| 156 | use Class::MakeMethods::Basic::Hash ( | ||||||||||||||||||
| 157 | scalar => 'foo', | ||||||||||||||||||
| 158 | ); | ||||||||||||||||||
| 159 | ... | ||||||||||||||||||
| 160 | |||||||||||||||||||
| 161 | # Store value | ||||||||||||||||||
| 162 | $obj->foo('Foozle'); | ||||||||||||||||||
| 163 | |||||||||||||||||||
| 164 | # Retrieve value | ||||||||||||||||||
| 165 | print $obj->foo; | ||||||||||||||||||
| 166 | |||||||||||||||||||
| 167 | =cut | ||||||||||||||||||
| 168 | |||||||||||||||||||
| 169 | 2 | ▶ | sub scalar { | ||||||||||||||||
|
Subroutine
scalar: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||
| 170 | 2 | my $class = shift; | |||||||||||||||||
| 171 | map { | ||||||||||||||||||
| 172 | 2 | my $name = $_; | |||||||||||||||||
| 173 | 15 | ▶ | $name => sub { | ||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=6.9
| |||||||||||||||||||
| 174 | 15 | ▶ | if ( scalar @_ > 1 ) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 175 | 2 | $_[0]->{$name} = $_[1]; | |||||||||||||||||
| 176 | } else { | ||||||||||||||||||
| 177 | 13 | $_[0]->{$name}; | |||||||||||||||||
| 178 | } | ||||||||||||||||||
| 179 | } | ||||||||||||||||||
| 180 | 3 | } @_; | |||||||||||||||||
| 181 | } | ||||||||||||||||||
| 182 | |||||||||||||||||||
| 183 | ######################################################################## | ||||||||||||||||||
| 184 | |||||||||||||||||||
| 185 | =head2 array - Instance Ref Accessor | ||||||||||||||||||
| 186 | |||||||||||||||||||
| 187 | For each method name passed, uses a closure to generate a subroutine with the following characteristics: | ||||||||||||||||||
| 188 | |||||||||||||||||||
| 189 | =over 4 | ||||||||||||||||||
| 190 | |||||||||||||||||||
| 191 | =item * | ||||||||||||||||||
| 192 | |||||||||||||||||||
| 193 | Must be called on a hash-based instance. | ||||||||||||||||||
| 194 | |||||||||||||||||||
| 195 | =item * | ||||||||||||||||||
| 196 | |||||||||||||||||||
| 197 | Uses the method name as a hash key to access the related value for each instance. | ||||||||||||||||||
| 198 | |||||||||||||||||||
| 199 | =item * | ||||||||||||||||||
| 200 | |||||||||||||||||||
| 201 | The value for each instance will be a reference to an array (or undef). | ||||||||||||||||||
| 202 | |||||||||||||||||||
| 203 | =item * | ||||||||||||||||||
| 204 | |||||||||||||||||||
| 205 | If called without any arguments, returns the current array-ref value (or undef). | ||||||||||||||||||
| 206 | |||||||||||||||||||
| 207 | =item * | ||||||||||||||||||
| 208 | |||||||||||||||||||
| 209 | If called with one argument, uses that argument as an index to retrieve from the referenced array, and returns that value (or undef). | ||||||||||||||||||
| 210 | |||||||||||||||||||
| 211 | =item * | ||||||||||||||||||
| 212 | |||||||||||||||||||
| 213 | If called with a list of index-value pairs, stores the value at the given index in the referenced array. If the instance's value was previously undefined, a new array is autovivified. The current value in each position will be overwritten, and later arguments with the same index will override earlier ones. Returns the current array-ref value. | ||||||||||||||||||
| 214 | |||||||||||||||||||
| 215 | =back | ||||||||||||||||||
| 216 | |||||||||||||||||||
| 217 | Sample declaration and usage: | ||||||||||||||||||
| 218 | |||||||||||||||||||
| 219 | package MyObject; | ||||||||||||||||||
| 220 | use Class::MakeMethods::Basic::Hash ( | ||||||||||||||||||
| 221 | array => 'bar', | ||||||||||||||||||
| 222 | ); | ||||||||||||||||||
| 223 | ... | ||||||||||||||||||
| 224 | |||||||||||||||||||
| 225 | # Set values by position | ||||||||||||||||||
| 226 | $obj->bar(0 => 'Foozle', 1 => 'Bang!'); | ||||||||||||||||||
| 227 | |||||||||||||||||||
| 228 | # Positions may be overwritten, and in any order | ||||||||||||||||||
| 229 | $obj->bar(2 => 'And Mash', 1 => 'Blah!'); | ||||||||||||||||||
| 230 | |||||||||||||||||||
| 231 | # Retrieve value by position | ||||||||||||||||||
| 232 | print $obj->bar(1); | ||||||||||||||||||
| 233 | |||||||||||||||||||
| 234 | # Direct access to referenced array | ||||||||||||||||||
| 235 | print scalar @{ $obj->bar() }; | ||||||||||||||||||
| 236 | |||||||||||||||||||
| 237 | # Reset the array contents to empty | ||||||||||||||||||
| 238 | @{ $obj->bar() } = (); | ||||||||||||||||||
| 239 | |||||||||||||||||||
| 240 | =cut | ||||||||||||||||||
| 241 | |||||||||||||||||||
| 242 | 0 | ▶ | sub array { | ||||||||||||||||
|
Subroutine
array: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||
| 243 | 0 | my $class = shift; | |||||||||||||||||
| 244 | map { | ||||||||||||||||||
| 245 | 0 | my $name = $_; | |||||||||||||||||
| 246 | 0 | ▶ | $name => sub { | ||||||||||||||||
|
Subroutine
__ANON__: not called CC=5 SCAR=34.0
| |||||||||||||||||||
| 247 | 0 | my $self = shift; | |||||||||||||||||
| 248 | 0 | ▶ | if ( scalar(@_) == 0 ) { | ||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||
| 249 | 0 | return $self->{$name}; | |||||||||||||||||
| 250 | } elsif ( scalar(@_) == 1 ) { | ||||||||||||||||||
| 251 | 0 | $self->{$name}->[ shift() ]; | |||||||||||||||||
| 252 | } elsif ( scalar(@_) % 2 ) { | ||||||||||||||||||
| 253 | 0 | Carp::croak "Odd number of items in assigment to $name"; | |||||||||||||||||
| 254 | } else { | ||||||||||||||||||
| 255 | 0 | ▶ | while ( scalar(@_) ) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 256 | 0 | my $key = shift(); | |||||||||||||||||
| 257 | 0 | $self->{$name}->[ $key ] = shift(); | |||||||||||||||||
| 258 | } | ||||||||||||||||||
| 259 | 0 | return $self->{$name}; | |||||||||||||||||
| 260 | } | ||||||||||||||||||
| 261 | } | ||||||||||||||||||
| 262 | 0 | } @_; | |||||||||||||||||
| 263 | } | ||||||||||||||||||
| 264 | |||||||||||||||||||
| 265 | ######################################################################## | ||||||||||||||||||
| 266 | |||||||||||||||||||
| 267 | =head2 hash - Instance Ref Accessor | ||||||||||||||||||
| 268 | |||||||||||||||||||
| 269 | For each method name passed, uses a closure to generate a subroutine with the following characteristics: | ||||||||||||||||||
| 270 | |||||||||||||||||||
| 271 | =over 4 | ||||||||||||||||||
| 272 | |||||||||||||||||||
| 273 | =item * | ||||||||||||||||||
| 274 | |||||||||||||||||||
| 275 | Must be called on a hash-based instance. | ||||||||||||||||||
| 276 | |||||||||||||||||||
| 277 | =item * | ||||||||||||||||||
| 278 | |||||||||||||||||||
| 279 | Uses the method name as a hash key to access the related value for each instance. | ||||||||||||||||||
| 280 | |||||||||||||||||||
| 281 | =item * | ||||||||||||||||||
| 282 | |||||||||||||||||||
| 283 | The value for each instance will be a reference to a hash (or undef). | ||||||||||||||||||
| 284 | |||||||||||||||||||
| 285 | =item * | ||||||||||||||||||
| 286 | |||||||||||||||||||
| 287 | If called without any arguments, returns the current hash-ref value (or undef). | ||||||||||||||||||
| 288 | |||||||||||||||||||
| 289 | =item * | ||||||||||||||||||
| 290 | |||||||||||||||||||
| 291 | If called with one argument, uses that argument as an index to retrieve from the referenced hash, and returns that value (or undef). | ||||||||||||||||||
| 292 | |||||||||||||||||||
| 293 | =item * | ||||||||||||||||||
| 294 | |||||||||||||||||||
| 295 | If called with a list of key-value pairs, stores the value under the given key in the referenced hash. If the instance's value was previously undefined, a new hash is autovivified. The current value under each key will be overwritten, and later arguments with the same key will override earlier ones. Returns the current hash-ref value. | ||||||||||||||||||
| 296 | |||||||||||||||||||
| 297 | =back | ||||||||||||||||||
| 298 | |||||||||||||||||||
| 299 | Sample declaration and usage: | ||||||||||||||||||
| 300 | |||||||||||||||||||
| 301 | package MyObject; | ||||||||||||||||||
| 302 | use Class::MakeMethods::Basic::Hash ( | ||||||||||||||||||
| 303 | hash => 'baz', | ||||||||||||||||||
| 304 | ); | ||||||||||||||||||
| 305 | ... | ||||||||||||||||||
| 306 | |||||||||||||||||||
| 307 | # Set values by key | ||||||||||||||||||
| 308 | $obj->baz('foo' => 'Foozle', 'bar' => 'Bang!'); | ||||||||||||||||||
| 309 | |||||||||||||||||||
| 310 | # Values may be overwritten, and in any order | ||||||||||||||||||
| 311 | $obj->baz('broccoli' => 'Blah!', 'foo' => 'Fiddle'); | ||||||||||||||||||
| 312 | |||||||||||||||||||
| 313 | # Retrieve value by key | ||||||||||||||||||
| 314 | print $obj->baz('foo'); | ||||||||||||||||||
| 315 | |||||||||||||||||||
| 316 | # Direct access to referenced hash | ||||||||||||||||||
| 317 | print keys %{ $obj->baz() }; | ||||||||||||||||||
| 318 | |||||||||||||||||||
| 319 | # Reset the hash contents to empty | ||||||||||||||||||
| 320 | @{ $obj->baz() } = (); | ||||||||||||||||||
| 321 | |||||||||||||||||||
| 322 | =cut | ||||||||||||||||||
| 323 | |||||||||||||||||||
| 324 | 0 | ▶ | sub hash { | ||||||||||||||||
|
Subroutine
hash: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||
| 325 | 0 | my $class = shift; | |||||||||||||||||
| 326 | map { | ||||||||||||||||||
| 327 | 0 | my $name = $_; | |||||||||||||||||
| 328 | 0 | ▶ | $name => sub { | ||||||||||||||||
|
Subroutine
__ANON__: not called CC=5 SCAR=34.0
| |||||||||||||||||||
| 329 | 0 | my $self = shift; | |||||||||||||||||
| 330 | 0 | ▶ | if ( scalar(@_) == 0 ) { | ||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||
| 331 | 0 | return $self->{$name}; | |||||||||||||||||
| 332 | } elsif ( scalar(@_) == 1 ) { | ||||||||||||||||||
| 333 | 0 | $self->{$name}->{ shift() }; | |||||||||||||||||
| 334 | } elsif ( scalar(@_) % 2 ) { | ||||||||||||||||||
| 335 | 0 | Carp::croak "Odd number of items in assigment to $name"; | |||||||||||||||||
| 336 | } else { | ||||||||||||||||||
| 337 | 0 | ▶ | while ( scalar(@_) ) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 338 | 0 | $self->{$name}->{ shift() } = shift(); | |||||||||||||||||
| 339 | } | ||||||||||||||||||
| 340 | 0 | return $self->{$name}; | |||||||||||||||||
| 341 | } | ||||||||||||||||||
| 342 | } | ||||||||||||||||||
| 343 | 0 | } @_; | |||||||||||||||||
| 344 | } | ||||||||||||||||||
| 345 | |||||||||||||||||||
| 346 | ######################################################################## | ||||||||||||||||||
| 347 | |||||||||||||||||||
| 348 | =head1 SEE ALSO | ||||||||||||||||||
| 349 | |||||||||||||||||||
| 350 | See L<Class::MakeMethods> for general information about this distribution. | ||||||||||||||||||
| 351 | |||||||||||||||||||
| 352 | See L<Class::MakeMethods::Basic> for more about this family of subclasses. | ||||||||||||||||||
| 353 | |||||||||||||||||||
| 354 | See L<Class::MakeMethods::Basic::Array> for equivalent functionality | ||||||||||||||||||
| 355 | based on blessed arrays. If all access to your object is through | ||||||||||||||||||
| 356 | constructors and accessors declared using this package, and your | ||||||||||||||||||
| 357 | class will not be extensively subclassed, consider switching to | ||||||||||||||||||
| 358 | Basic::Array to minimize resource consumption. | ||||||||||||||||||
| 359 | |||||||||||||||||||
| 360 | =cut | ||||||||||||||||||
| 361 | |||||||||||||||||||
| 362 | 1 | 1; | |||||||||||||||||