1### Class::MakeMethods 2 # Copyright 2002, 2003 Matthew Simon Cavalletto 3 # See documentation, license, and other information after _END_. 4 5package Class::MakeMethods; 6 7require 5.00307; # for the UNIVERSAL::isa method. 8use strict; 9use Carp; 10 11use vars qw( $VERSION ); 12$VERSION = 1.010; 13 14use vars qw( %CONTEXT %DIAGNOSTICS ); 15 16######################################################################## 17### MODULE IMPORT: import(), _import_version() 18######################################################################## 19 20sub import { 21 my $class = shift; 22 23 if ( scalar @_ and $_[0] =~ m/^\d/ ) { 24 $class->_import_version( shift ); 25 } 26 27 if ( scalar @_ == 1 and $_[0] eq '-isasubclass' ) { 28 shift; 29 my $target_class = ( caller )[0]; 30 no strict; 31 push @{"$target_class\::ISA"}, $class; 32 } 33 34 $class->make( @_ ) if ( scalar @_ ); 35} 36 37sub _import_version { 38 my $class = shift; 39 my $wanted = shift; 40 41 no strict; 42 my $version = ${ $class.'::VERSION '}; 43 44 # If passed a version number, ensure that we measure up. 45 # Based on similar functionality in Exporter.pm 46 if ( ! $version or $version < $wanted ) { 47 my $file = "$class.pm"; 48 $file =~ s!::!/!g; 49 $file = $INC{$file} ? " ($INC{$file})" : ''; 50 _diagnostic('mm_version_fail', $class, $wanted, $version || '(undef)', $file); 51 } 52} 53 54######################################################################## 55### METHOD GENERATION: make() 56######################################################################## 57 58sub make { 59 local $CONTEXT{MakerClass} = shift; 60 61 # Find the first class in the caller() stack that's not a subclass of us 62 local $CONTEXT{TargetClass}; 63 my $i = 0; 64 do { 65 $CONTEXT{TargetClass} = ( caller($i ++) )[0]; 66 } while UNIVERSAL::isa($CONTEXT{TargetClass}, __PACKAGE__ ); 67 68 my @methods; 69 70 # For compatibility with 5.004, which fails to splice use's constant @_ 71 my @declarations = @_; 72 73 if (@_ % 2) { _diagnostic('make_odd_args', $CONTEXT{MakerClass}); } 74 while ( scalar @declarations ) { 75 # The list passed to import should alternate between the names of the 76 # meta-method to call to generate the methods, and arguments to it. 77 my ($name, $args) = splice(@declarations, 0, 2); 78 unless ( defined $name ) { 79 croak "Undefined name"; 80 } 81 82 # Leading dash on the first argument of a pair means it's a 83 # global/general option to be stored in CONTEXT. 84 if ( $name =~ s/^\-// ) { 85 86 # To prevent difficult-to-predict retroactive behaviour, start by 87 # flushing any pending methods before letting settings take effect 88 if ( scalar @methods ) { 89 _install_methods( $CONTEXT{MakerClass}, @methods ); 90 @methods = (); 91 } 92 93 if ( $name eq 'MakerClass' ) { 94 # Switch base package for remainder of args 95 $CONTEXT{MakerClass} = _find_subclass($CONTEXT{MakerClass}, $args); 96 } else { 97 $CONTEXT{$name} = $args; 98 } 99 100 next; 101 } 102 103 # Argument normalization 104 my @args = ( 105 ! ref($args) ? split(' ', $args) : # If a string, it is split on spaces. 106 ref($args) eq 'ARRAY' ? (@$args) : # If an arrayref, use its contents. 107 ( $args ) # If a hashref, it is used directly 108 ); 109 110 # If the type argument contains an array of method types, do the first 111 # now, and put the others back in the queue to be processed subsequently. 112 if ( ref($name) eq 'ARRAY' ) { 113 ($name, my @name) = @$name; 114 unshift @declarations, map { $_=>[@args] } @name; 115 } 116 117 # If the type argument contains space characters, use the first word 118 # as the type, and prepend the remaining items to the argument list. 119 if ( $name =~ /\s/ ) { 120 my @items = split ' ', $name; 121 $name = shift( @items ); 122 unshift @args, @items; 123 } 124 125 # If name contains a colon or double colon, treat the preceeding part 126 # as the subclass name but only for this one set of methods. 127 local $CONTEXT{MakerClass} = _find_subclass($CONTEXT{MakerClass}, $1) 128 if ($name =~ s/^(.*?)\:{1,2}(\w+)$/$2/); 129 130 # Meta-method invocation via named_method or direct method call 131 my @results = ( 132 $CONTEXT{MakerClass}->can('named_method') ? 133 $CONTEXT{MakerClass}->named_method( $name, @args ) : 134 $CONTEXT{MakerClass}->can($name) ? 135 $CONTEXT{MakerClass}->$name( @args ) : 136 croak "Can't generate $CONTEXT{MakerClass}->$name() methods" 137 ); 138 # warn "$CONTEXT{MakerClass} $name - ", join(', ', @results) . "\n"; 139 140 ### A method-generator may be implemented in any of the following ways: 141 142 # SELF-CONTAINED: It may return nothing, if there are no methods 143 # to install, or if it has installed the methods itself. 144 # (We also accept a single false value, for backward compatibility 145 # with generators that are written as foreach loops, which return ''!) 146 if ( ! scalar @results or scalar @results == 1 and ! $results[0] ) { } 147 148 # ALIAS: It may return a string containing a meta-method type to run 149 # instead. Put the arguments back in the queue and go through again. 150 elsif ( scalar @results == 1 and ! ref $results[0]) { 151 unshift @declarations, $results[0], \@args; 152 } 153 154 # REWRITER: It may return one or more array reference containing a meta- 155 # method type and arguments which should be created to complete this 156 # request. Put the arguments back in the queue and go through again. 157 elsif ( ! grep { ref $_ ne 'ARRAY' } @results ) { 158 unshift @declarations, ( map { shift(@$_), $_ } @results ); 159 } 160 161 # CODE REFS: It may provide a list of name, code pairs to install 162 elsif ( ! scalar @results % 2 and ! ref $results[0] ) { 163 push @methods, @results; 164 } 165 166 # GENERATOR OBJECT: It may return an object reference which will construct 167 # the relevant methods. 168 elsif ( UNIVERSAL::can( $results[0], 'make_methods' ) ) { 169 push @methods, ( shift @results )->make_methods(@results, @args); 170 } 171 172 else { 173 _diagnostic('make_bad_meta', $name, join(', ', map "'$_'", @results)); 174 } 175 } 176 177 _install_methods( $CONTEXT{MakerClass}, @methods ); 178 179 return; 180} 181 182######################################################################## 183### DECLARATION PARSING: _get_declarations() 184######################################################################## 185 186sub _get_declarations { 187 my $class = shift; 188 189 my @results; 190 my %defaults; 191 192 while (scalar @_) { 193 my $m_name = shift @_; 194 if ( ! defined $m_name or ! length $m_name ) { 195 _diagnostic('make_empty') 196 } 197 198 # Various forms of default parameters 199 elsif ( substr($m_name, 0, 1) eq '-' ) { 200 if ( substr($m_name, 1, 1) ne '-' ) { 201 # Parse default values in the format "-param => value" 202 $defaults{ substr($m_name, 1) } = shift @_; 203 } elsif ( length($m_name) == 2 ) { 204 # Parse hash of default values in the format "-- => { ... }" 205 ref($_[0]) eq 'HASH' or _diagnostic('make_unsupported', $m_name.$_[0]); 206 %defaults = ( %defaults, %{ shift @_ } ); 207 } else { 208 # Parse "special" arguments in the format "--foobar" 209 $defaults{ '--' } .= $m_name; 210 } 211 } 212 213 # Parse string and string-then-hash declarations 214 elsif ( ! ref $m_name ) { 215 if ( scalar @_ and ref $_[0] eq 'HASH' and ! exists $_[0]->{'name'} ) { 216 push @results, { %defaults, 'name' => $m_name, %{ shift @_ } }; 217 } else { 218 push @results, { %defaults, 'name' => $m_name }; 219 } 220 } 221 222 # Parse hash-only declarations 223 elsif ( ref $m_name eq 'HASH' ) { 224 if ( length $m_name->{'name'} ) { 225 push @results, { %defaults, %$m_name }; 226 } else { 227 _diagnostic('make_noname'); 228 } 229 } 230 231 # Normalize: If we've got an array of names, replace it with those names 232 elsif ( ref $m_name eq 'ARRAY' ) { 233 my @items = @{ $m_name }; 234 # If array is followed by an params hash, each one gets the same params 235 if ( scalar @_ and ref $_[0] eq 'HASH' and ! exists $_[0]->{'name'} ) { 236 my $params = shift; 237 @items = map { $_, $params } @items 238 } 239 unshift @_, @items; 240 next; 241 } 242 243 else { 244 _diagnostic('make_unsupported', $m_name); 245 } 246 247 } 248 249 return @results; 250} 251 252######################################################################## 253### FUNCTION INSTALLATION: _install_methods() 254######################################################################## 255 256sub _install_methods { 257 my ($class, %methods) = @_; 258 259 no strict 'refs'; 260 261 # print STDERR "CLASS: $class\n"; 262 my $package = $CONTEXT{TargetClass}; 263 264 my ($name, $code); 265 while (($name, $code) = each %methods) { 266 267 # Skip this if the target package already has a function by the given name. 268 next if ( ! $CONTEXT{ForceInstall} and 269 defined *{$package. '::'. $name}{CODE} ); 270 271 if ( ! ref $code ) { 272 local $SIG{__DIE__}; 273 local $^W; 274 my $coderef = eval $code; 275 if ( $@ ) { 276 _diagnostic('inst_eval_syntax', $name, $@, $code); 277 } elsif ( ref $coderef ne 'CODE' ) { 278 _diagnostic('inst_eval_result', $name, $coderef, $code); 279 } 280 $code = $coderef; 281 } elsif ( ref $code ne 'CODE' ) { 282 _diagnostic('inst_result', $name, $code); 283 } 284 285 # Add the code refence to the target package 286 # _diagnostic('debug_install', $package, $name, $code); 287 local $^W = 0 if ( $CONTEXT{ForceInstall} ); 288 *{$package . '::' . $name} = $code; 289 290 } 291 return; 292} 293 294######################################################################## 295### SUBCLASS LOADING: _find_subclass() 296######################################################################## 297 298# $pckg = _find_subclass( $class, $optional_package_name ); 299sub _find_subclass { 300 my $class = shift; 301 my $package = shift or die "No package for _find_subclass"; 302 303 $package = $package =~ s/^::// ? $package : 304 "Class::MakeMethods::$package"; 305 306 (my $file = $package . '.pm' ) =~ s|::|/|go; 307 return $package if ( $::INC{ $file } ); 308 309 no strict 'refs'; 310 return $package if ( @{$package . '::ISA'} ); 311 312 local $SIG{__DIE__} = ''; 313 eval { require $file }; 314 $::INC{ $package } = $::INC{ $file }; 315 if ( $@ ) { _diagnostic('mm_package_fail', $package, $@) } 316 317 return $package 318} 319 320######################################################################## 321### CONTEXT: _context(), %CONTEXT 322######################################################################## 323 324sub _context { 325 my $class = shift; 326 return %CONTEXT if ( ! scalar @_ ); 327 my $key = shift; 328 return $CONTEXT{$key} if ( ! scalar @_ ); 329 $CONTEXT{$key} = shift; 330} 331 332BEGIN { 333 $CONTEXT{Debug} ||= 0; 334} 335 336######################################################################## 337### DIAGNOSTICS: _diagnostic(), %DIAGNOSTICS 338######################################################################## 339 340sub _diagnostic { 341 my $case = shift; 342 my $message = $DIAGNOSTICS{$case}; 343 $message =~ s/\A\s*\((\w)\)\s*//; 344 my $severity = $1 || 'I'; 345 if ( $severity eq 'Q' ) { 346 carp( sprintf( $message, @_ ) ) if ( $CONTEXT{Debug} ); 347 } elsif ( $severity eq 'W' ) { 348 carp( sprintf( $message, @_ ) ) if ( $^W ); 349 } elsif ( $severity eq 'F' ) { 350 croak( sprintf( $message, @_ ) ) 351 } else { 352 confess( sprintf( $message, @_ ) ) 353 } 354} 355 356 357BEGIN { %DIAGNOSTICS = ( 358 359 ### BASE CLASS DIAGNOSTICS 360 361 # _diagnostic('debug_install', $package, $name, $code) 362 debug_install => q|(W) Installing function %s::%s (%s)|, 363 364 # _diagnostic('make_odd_args', $CONTEXT{MakerClass}) 365 make_odd_args => q|(F) Odd number of arguments passed to %s method generator|, 366 367 # _diagnostic('make_bad_meta', $name, join(', ', map "'$_'", @results) 368 make_bad_meta => q|(I) Unexpected return value from method constructor %s: %s|, 369 370 # _diagnostic('inst_eval_syntax', $name, $@, $code) 371 inst_eval_syntax => q|(I) Unable to compile generated method %s(): %s| . 372 qq|\n (There's probably a syntax error in this generated code.)\n%s\n|, 373 374 # _diagnostic('inst_eval_result', $name, $coderef, $code) 375 inst_eval_result => q|(I) Unexpected return value from compilation of %s(): '%s'| . 376 qq|\n (This generated code should have returned a code ref.)\n%s\n|, 377 378 # _diagnostic('inst_result', $name, $code) 379 inst_result => q|(I) Unable to install code for %s() method: '%s'|, 380 381 # _diagnostic('mm_package_fail', $package, $@) 382 mm_package_fail => q|(F) Unable to dynamically load %s: %s|, 383 384 # _diagnostic('mm_version_fail', $class, $wanted, $version || '(undef) 385 mm_version_fail => q|(F) %s %s required--this is only version %s%s|, 386 387 ### STANDARD SUBCLASS DIAGNOSTICS 388 389 # _diagnostic('make_empty') 390 make_empty => q|(F) Can't parse meta-method declaration: argument is empty or undefined|, 391 392 # _diagnostic('make_noname') 393 make_noname => q|(F) Can't parse meta-method declaration: missing name attribute.| . 394 qq|\n (Perhaps a trailing attributes hash has become separated from its name?)|, 395 396 # _diagnostic('make_unsupported', $m_name) 397 make_unsupported => q|(F) Can't parse meta-method declaration: unsupported declaration type '%s'|, 398 399 ### TEMPLATE SUBCLASS DIAGNOSTICS 400 # ToDo: Should be moved to the Class::MakeMethods::Template package 401 402 debug_declaration => q|(Q) Meta-method declaration parsed: %s|, 403 debug_make_behave => q|(Q) Building meta-method behavior %s: %s(%s)|, 404 mmdef_not_interpretable => qq|(I) Not an interpretable meta-method: '%s'| . 405 qq|\n (Perhaps a meta-method attempted to import from a non-templated meta-method?)|, 406 make_bad_modifier => q|(F) Can't parse meta-method declaration: unknown option for %s: %s|, 407 make_bad_behavior => q|(F) Can't make method %s(): template specifies unknown behavior '%s'|, 408 behavior_mod_unknown => q|(F) Unknown modification to %s behavior: -%s|, 409 debug_template_builder => qq|(Q) Template interpretation for %s:\n%s|. 410 qq|\n---------\n%s\n---------\n|, 411 debug_template => q|(Q) Parsed template '%s': %s|, 412 debug_eval_builder => q|(Q) Compiling behavior builder '%s':| . qq|\n%s|, 413 make_behavior_mod => q|(F) Can't apply modifiers (%s) to code behavior %s|, 414 behavior_eval => q|(I) Class::MakeMethods behavior compilation error: %s| . 415 qq|\n (There's probably a syntax error in the below code.)\n%s|, 416 tmpl_unkown => q|(F) Can't interpret meta-method template: unknown template name '%s'|, 417 tmpl_empty => q|(F) Can't interpret meta-method template: argument is empty or undefined|, 418 tmpl_unsupported => q|(F) Can't interpret meta-method template: unsupported template type '%s'|, 419) } 420 4211; 422 423__END__ 424 425 426=head1 NAME 427 428Class::MakeMethods - Generate common types of methods 429 430 431=head1 SYNOPSIS 432 433 # Generates methods for your object when you "use" it. 434 package MyObject; 435 use Class::MakeMethods::Standard::Hash ( 436 'new' => 'new', 437 'scalar' => 'foo', 438 'scalar' => 'bar', 439 ); 440 441 # The generated methods can be called just like normal ones 442 my $obj = MyObject->new( foo => "Foozle", bar => "Bozzle" ); 443 print $obj->foo(); 444 $obj->bar("Barbados"); 445 446 447=head1 DESCRIPTION 448 449The Class::MakeMethods framework allows Perl class developers to 450quickly define common types of methods. When a module C<use>s 451Class::MakeMethods or one of its subclasses, it can select from a 452variety of supported method types, and specify a name for each 453method desired. The methods are dynamically generated and installed 454in the calling package. 455 456Construction of the individual methods is handled by subclasses. 457This delegation approach allows for a wide variety of method-generation 458techniques to be supported, each by a different subclass. Subclasses 459can also be added to provide support for new types of methods. 460 461Over a dozen subclasses are available, including implementations of 462a variety of different method-generation techniques. Each subclass 463generates several types of methods, with some supporting their own 464open-eneded extension syntax, for hundreds of possible combinations 465of method types. 466 467 468=head1 GETTING STARTED 469 470=head2 Motivation 471 472 "Make easy things easier." 473 474This module addresses a problem encountered in object-oriented 475development wherein numerous methods are defined which differ only 476slightly from each other. 477 478A common example is accessor methods for hash-based object attributes, 479which allow you to get and set the value $self-E<gt>{'foo'} by 480calling a method $self-E<gt>foo(). 481 482These methods are generally quite simple, requiring only a couple 483of lines of Perl, but in sufficient bulk, they can cut down on the 484maintainability of large classes. 485 486Class::MakeMethods allows you to simply declare those methods to 487be of a predefined type, and it generates and installs the necessary 488methods in your package at compile-time. 489 490=head2 A Contrived Example 491 492Object-oriented Perl code is widespread -- you've probably seen code like the below a million times: 493 494 my $obj = MyStruct->new( foo=>"Foozle", bar=>"Bozzle" ); 495 if ( $obj->foo() =~ /foo/i ) { 496 $obj->bar("Barbados!"); 497 } 498 print $obj->summary(); 499 500(If this doesn't look familiar, take a moment to read L<perlboot> 501and you'll soon learn more than's good for you.) 502 503Typically, this involves creating numerous subroutines that follow 504a handful of common patterns, like constructor methods and accessor 505methods. The classic example is accessor methods for hash-based 506object attributes, which allow you to get and set the value 507I<self>-E<gt>{I<foo>} by calling a method I<self>-E<gt>I<foo>(). 508These methods are generally quite simple, requiring only a couple 509of lines of Perl, but in sufficient bulk, they can cut down on the 510maintainability of large classes. 511 512Here's a possible implementation for the class whose interface is 513shown above: 514 515 package MyStruct; 516 517 sub new { 518 my $callee = shift; 519 my $self = bless { @_ }, (ref $callee || $callee); 520 return $self; 521 } 522 523 sub foo { 524 my $self = shift; 525 if ( scalar @_ ) { 526 $self->{'foo'} = shift(); 527 } else { 528 $self->{'foo'} 529 } 530 } 531 532 sub bar { 533 my $self = shift; 534 if ( scalar @_ ) { 535 $self->{'bar'} = shift(); 536 } else { 537 $self->{'bar'} 538 } 539 } 540 541 sub summary { 542 my $self = shift; 543 join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) ) 544 } 545 546Note in particular that the foo and bar methods are almost identical, 547and that the new method could be used for almost any class; this 548is precisely the type of redundancy Class::MakeMethods addresses. 549 550Class::MakeMethods allows you to simply declare those methods to 551be of a predefined type, and it generates and installs the necessary 552methods in your package at compile-time. 553 554Here's the equivalent declaration for that same basic class: 555 556 package MyStruct; 557 use Class::MakeMethods::Standard::Hash ( 558 'new' => 'new', 559 'scalar' => 'foo', 560 'scalar' => 'bar', 561 ); 562 563 sub summary { 564 my $self = shift; 565 join(', ', map { "\u$_: " . $self->$_() } qw( foo bar ) ) 566 } 567 568This is the basic purpose of Class::MakeMethods: The "boring" pieces 569of code have been replaced by succinct declarations, placing the 570focus on the "unique" or "custom" pieces. 571 572=head2 Finding the Method Types You Need 573 574Once you've grasped the basic idea -- simplifying repetitive code 575by generating and installing methods on demand -- the remaining 576complexity basically boils down to figuring out which arguments to 577pass to generate the specific methods you want. 578 579Unfortunately, this is not a trivial task, as there are dozens of 580different types of methods that can be generated, each with a 581variety of options, and several alternative ways to write each 582method declaration. You may prefer to start by just finding a few 583examples that you can modify to accomplish your immediate needs, 584and defer investigating all of the extras until you're ready to 585take a closer look. 586 587=head2 Other Documentation 588 589The remainder of this document focuses on points of usage that are 590common across all subclasses, and describes how to create your own 591subclasses. 592 593If this is your first exposure to Class::MakeMethods, you may want 594to skim over the rest of this document, then take a look at the 595examples and one or two of the method-generating subclasses to get 596a more concrete sense of typical usage, before returning to the 597details presented below. 598 599=over 4 600 601=item * 602 603A collection of sample uses is available in 604L<Class::MakeMethods::Docs::Examples>. 605 606=item * 607 608Some of the most common object and class methods are available from 609L<Class::MakeMethods::Standard::Hash>, 610L<Class::MakeMethods::Standard::Global> and 611L<Class::MakeMethods::Standard::Universal>. 612 613=item * 614 615If you need a bit more flexibility, see L<Class::MakeMethods::Composite> 616for method generators which offer more customization options, 617including pre- and post-method callback hooks. 618 619=item * 620 621For the largest collection of methods and options, see 622L<Class::MakeMethods::Template>, which uses a system of dynamic 623code generation to allow endless variation. 624 625=item * 626 627A listing of available method types from each of the different 628subclasses is provided in L<Class::MakeMethods::Docs::Catalog>. 629 630=back 631 632=head1 CLASS ARCHITECTURE 633 634Because there are so many common types of methods one might wish 635to generate, the Class::MakeMethods framework provides an extensible 636system based on subclasses. 637 638When your code requests a method, the MakeMethods base class performs 639some standard argument parsing, delegates the construction of the 640actual method to the appropriate subclass, and then installs whatever 641method the subclass returns. 642 643=head2 The MakeMethods Base Class 644 645The Class::MakeMethods package defines a superclass for method-generating 646modules, and provides a calling convention, on-the-fly subclass 647loading, and subroutine installation that will be shared by all 648subclasses. 649 650The superclass also lets you generate several different types of 651methods in a single call, and will automatically load named subclasses 652the first time they're used. 653 654=head2 The Method Generator Subclasses 655 656The type of method that gets created is controlled by the specific 657subclass and generator function you request. For example, 658C<Class::MakeMethods::Standard::Hash> has a generator function 659C<scalar()>, which is responsible for generating simple scalar-accessor 660methods for blessed-hash objects. 661 662Each generator function specified is passed the arguments specifying 663the method the caller wants, and produces a closure or eval-able 664sequence of Perl statements representing the ready-to-install 665function. 666 667=head2 Included Subclasses 668 669Because each subclass defines its own set of method types and 670customization options, a key step is to find your way to the 671appropriate subclasses. 672 673=over 4 674 675=item Standard (See L<Class::MakeMethods::Standard>.) 676 677Generally you will want to begin with the Standard::Hash subclass, 678to create constructor and accessor methods for working with 679blessed-hash objects (or you might choose the Standard::Array 680subclass instead). The Standard::Global subclass provides methods 681for class data shared by all objects in a class. 682 683Each Standard method declaration can optionally include a hash of 684associated parameters, which allows you to tweak some of the 685characteristics of the methods. Subroutines are bound as closures 686to a hash of each method's name and parameters. Standard::Hash and 687Standard::Array provide object constructor and accessors. The 688Standard::Global provides for static data shared by all instances 689and subclasses, while the data for Standard::Inheritable methods 690trace the inheritance tree to find values, and can be overriden 691for any subclass or instance. 692 693=item Composite (See L<Class::MakeMethods::Composite>.) 694 695For additional customization options, check out the Composite 696subclasses, which allow you to select from a more varied set of 697implementations and which allow you to adjust any specific method 698by adding your own code-refs to be run before or after it. 699 700Subroutines are bound as closures to a hash of each method's name 701and optional additional data, and to one or more subroutine references 702which make up the composite behavior of the method. Composite::Hash 703and Composite::Array provide object constructor and accessors. The 704Composite::Global provides for static data shared by all instances 705and subclasses, while the data for Composite::Inheritable methods 706can be overriden for any subclass or instance. 707 708=item Template (See L<Class::MakeMethods::Template>.) 709 710The Template subclasses provide an open-ended structure for objects 711that assemble Perl code on the fly into cachable closure-generating 712subroutines; if the method you need isn't included, you can extend 713existing methods by re-defining just the snippet of code that's 714different. 715 716Class::MakeMethods::Template extends MakeMethods with a text 717templating system that can assemble Perl code fragments into a 718desired subroutine. The code for generated methods is eval'd once 719for each type, and then repeatedly bound as closures to method-specific 720data for better performance. 721 722Templates for dozens of types of constructor, accessor, and mutator 723methods are included, ranging from from the mundane (constructors 724and value accessors for hash and array slots) to the esoteric 725(inheritable class data and "inside-out" accessors with external 726indexes). 727 728=item Basic (See L<Class::MakeMethods::Basic>.) 729 730The Basic subclasses provide stripped down method generators with 731no configurable options, for minimal functionality (and minimum 732overhead). 733 734Subroutines are bound as closures to the name of each method. 735Basic::Hash and Basic::Array provide simple object constructors 736and accessors. Basic::Global provides basic global-data accessors. 737 738=item Emulators (See L<Class::MakeMethods::Emulator>.) 739 740In several cases, Class::MakeMethods provides functionality closely 741equivalent to that of an existing module, and it is simple to map 742the existing module's interface to that of Class::MakeMethods. 743 744Emulators are included for Class::MethodMaker, Class::Accessor::Fast, 745Class::Data::Inheritable, Class::Singleton, and Class::Struct, each 746of which passes the original module's test suite, usually requiring 747only that the name of the module be changed. 748 749=item Extending 750 751Class::MakeMethods can be extended by creating subclasses that 752define additional method-generation functions. Callers can then 753specify the name of your subclass and generator function in their 754C<use Call::MakeMethods ...> statements and your function will be 755invoked to produce the required closures. See L</EXTENDING> for 756more information. 757 758=back 759 760=head2 Naming Convention for Generated Method Types 761 762Method generation functions in this document are often referred to using the 'I<MakerClass>:I<MethodType>' or 'I<MakerGroup>::I<MakerSubclass>:I<MethodType>' naming conventions. As you will see, these are simply the names of Perl packages and the names of functions that are contained in those packages. 763 764The included subclasses are grouped into several major groups, so the names used by the included subclasses and method types reflect three axes of variation, "I<Group>::I<Subclass>:I<Type>": 765 766=over 4 767 768=item Maker Group 769 770Each group shares a similar style of technical implementation and level of complexity. For example, the C<Standard::*> packages are all simple, while the C<Composite::*> packages all support pre- and post-conditions. 771 772(For a listing of the four main groups of included subclasses, see L<"/Included Subclasses">.) 773 774=item Maker Subclass 775 776Each subclass generates methods for a similar level of scoping or underlying object type. For example, the C<*::Hash> packages all make methods for objects based on blessed hashes, while the C<*::Global> packages make methods that access class-wide data that will be shared between all objects in a class. 777 778=item Method Type 779 780Each method type produces a similar type of constructor or accessor. For examples, the C<*:new> methods are all constructors, while the C<::scalar> methods are all accessors that allow you to get and set a single scalar value. 781 782=back 783 784Bearing that in mind, you should be able to guess the intent of many of the method types based on their names alone; when you see "Standard::Hash:scalar" you can read it as "a type of method to access a I<scalar> value stored in a I<hash>-based object, with a I<standard> implementation style" and know that it's going to call the scalar() function in the Class::MakeMethods::Standard::Hash package to generate the requested method. 785 786 787=head1 USAGE 788 789The supported method types, and the kinds of arguments they expect, vary from subclass to subclass; see the documentation of each subclass for details. 790 791However, the features described below are applicable to all subclasses. 792 793=head2 Invocation 794 795Methods are dynamically generated and installed into the calling 796package when you C<use Class::MakeMethods (...)> or one of its 797subclasses, or if you later call C<Class::MakeMethods-E<gt>make(...)>. 798 799The arguments to C<use> or C<make> should be pairs of a generator 800type name and an associated array of method-name arguments to pass to 801the generator. 802 803=over 4 804 805=item * 806 807use Class::MakeMethods::I<MakerClass> ( 808 'I<MethodType>' => [ I<Arguments> ], I<...> 809 ); 810 811=item * 812 813Class::MakeMethods::I<MakerClass>->make ( 814 'I<MethodType>' => [ I<Arguments> ], I<...> 815 ); 816 817=back 818 819You may select a specific subclass of Class::MakeMethods for 820a single generator-type/argument pair by prefixing the type name 821with a subclass name and a colon. 822 823=over 4 824 825=item * 826 827use Class::MakeMethods ( 828 'I<MakerClass>:I<MethodType>' => [ I<Arguments> ], I<...> 829 ); 830 831=item * 832 833Class::MakeMethods->make ( 834 'I<MakerClass>:I<MethodType>' => [ I<Arguments> ], I<...> 835 ); 836 837=back 838 839The difference between C<use> and C<make> is primarily one of precedence; the C<use> keyword acts as a BEGIN block, and is thus evaluated before C<make> would be. (See L</"About Precedence"> for additional discussion of this issue.) 840 841=head2 Alternative Invocation 842 843If you want methods to be declared at run-time when a previously-unknown 844method is invoked, see L<Class::MakeMethods::Autoload>. 845 846=over 4 847 848=item * 849 850use Class::MakeMethods::Autoload 'I<MakerClass>:I<MethodType>'; 851 852=back 853 854If you are using Perl version 5.6 or later, see 855L<Class::MakeMethods::Attribute> for an additional declaration 856syntax for generated methods. 857 858=over 4 859 860=item * 861 862use Class::MakeMethods::Attribute 'I<MakerClass>'; 863 864sub I<name> :MakeMethod('I<MethodType>' => I<Arguments>); 865 866=back 867 868=head2 About Precedence 869 870Rather than passing the method declaration arguments when you C<use> one of these packages, you may instead pass them to a subsequent call to the class method C<make>. 871 872The difference between C<use> and C<make> is primarily one of precedence; the C<use> keyword acts as a BEGIN block, and is thus evaluated before C<make> would be. In particular, a C<use> at the top of a file will be executed before any subroutine declarations later in the file have been seen, whereas a C<make> at the same point in the file will not. 873 874By default, Class::MakeMethods will not install generated methods over any pre-existing methods in the target class. To override this you can pass C<-ForceInstall =E<gt> 1> as initial arguments to C<use> or C<make>. 875 876If the same method is declared multiple times, earlier calls to 877C<use> or C<make()> win over later ones, but within each call, 878later declarations superceed earlier ones. 879 880Here are some examples of the results of these precedence rules: 881 882 # 1 - use, before 883 use Class::MakeMethods::Standard::Hash ( 884 'scalar'=>['baz'] # baz() not seen yet, so we generate, install 885 ); 886 sub baz { 1 } # Subsequent declaration overwrites it, with warning 887 888 # 2 - use, after 889 sub foo { 1 } 890 use Class::MakeMethods::Standard::Hash ( 891 'scalar'=>['foo'] # foo() is already declared, so has no effect 892 ); 893 894 # 3 - use, after, Force 895 sub bar { 1 } 896 use Class::MakeMethods::Standard::Hash ( 897 -ForceInstall => 1, # Set flag for following methods... 898 'scalar' => ['bar'] # ... now overwrites pre-existing bar() 899 ); 900 901 # 4 - make, before 902 Class::MakeMethods::Standard::Hash->make( 903 'scalar'=>['blip'] # blip() is already declared, so has no effect 904 ); 905 sub blip { 1 } # Although lower than make(), this "happens" first 906 907 # 5 - make, after, Force 908 sub ping { 1 } 909 Class::MakeMethods::Standard::Hash->make( 910 -ForceInstall => 1, # Set flag for following methods... 911 'scalar' => ['ping'] # ... now overwrites pre-existing ping() 912 ); 913 914=head2 Global Options 915 916Global options may be specified as an argument pair with a leading hyphen. (This distinguishes them from type names, which must be valid Perl subroutine names, and thus will never begin with a hyphen.) 917 918use Class::MakeMethods::I<MakerClass> ( 919 '-I<Param>' => I<ParamValue>, 920 'I<MethodType>' => [ I<Arguments> ], I<...> 921 ); 922 923Option settings apply to all subsequent method declarations within a single C<use> or C<make> call. 924 925The below options allow you to control generation and installation of the requested methods. (Some subclasses may support additional options; see their documentation for details.) 926 927=over 4 928 929=item -TargetClass 930 931By default, the methods are installed in the first package in the caller() stack that is not a Class::MakeMethods subclass; this is generally the package in which your use or make statement was issued. To override this you can pass C<-TargetClass =E<gt> I<package>> as initial arguments to C<use> or C<make>. 932 933This allows you to construct or modify classes "from the outside": 934 935 package main; 936 937 use Class::MakeMethods::Basic::Hash( 938 -TargetClass => 'MyWidget', 939 'new' => ['create'], 940 'scalar' => ['foo', 'bar'], 941 ); 942 943 $o = MyWidget->new( foo => 'Foozle' ); 944 print $o->foo(); 945 946=item -MakerClass 947 948By default, meta-methods are looked up in the package you called 949use or make on. 950 951You can override this by passing the C<-MakerClass> flag, which 952allows you to switch packages for the remainder of the meta-method 953types and arguments. 954 955use Class::MakeMethods ( 956 '-MakerClass'=>'I<MakerClass>', 957 'I<MethodType>' => [ I<Arguments> ] 958 ); 959 960When specifying the MakerClass, you may provide either the trailing 961part name of a subclass inside of the C<Class::MakeMethods::> 962namespace, or a full package name prefixed by C<::>. 963 964For example, the following four statements are equivalent ways of 965declaring a Basic::Hash scalar method named 'foo': 966 967 use Class::MakeMethods::Basic::Hash ( 968 'scalar' => [ 'foo' ] 969 ); 970 971 use Class::MakeMethods ( 972 'Basic::Hash:scalar' => [ 'foo' ] 973 ); 974 975 use Class::MakeMethods ( 976 '-MakerClass'=>'Basic::Hash', 977 'scalar' => [ 'foo' ] 978 ); 979 980 use Class::MakeMethods ( 981 '-MakerClass'=>'::Class::MakeMethods::Basic::Hash', 982 'scalar' => [ 'foo' ] 983 ); 984 985=item -ForceInstall 986 987By default, Class::MakeMethods will not install generated methods over any pre-existing methods in the target class. To override this you can pass C<-ForceInstall =E<gt> 1> as initial arguments to C<use> or C<make>. 988 989Note that the C<use> keyword acts as a BEGIN block, so a C<use> at the top of a file will be executed before any subroutine declarations later in the file have been seen. (See L</"About Precedence"> for additional discussion of this issue.) 990 991=back 992 993=head2 Mixing Method Types 994 995A single calling class can combine generated methods from different MakeMethods subclasses. In general, the only mixing that's problematic is combinations of methods which depend on different underlying object types, like using *::Hash and *::Array methods together -- the methods will be generated, but some of them are guaranteed to fail when called, depending on whether your object happens to be a blessed hashref or arrayref. 996 997For example, it's common to mix and match various *::Hash methods, with a scattering of Global or Inheritable methods: 998 999 use Class::MakeMethods ( 1000 'Basic::Hash:scalar' => 'foo', 1001 'Composite::Hash:scalar' => [ 'bar' => { post_rules => [] } ], 1002 'Standard::Global:scalar' => 'our_shared_baz' 1003 ); 1004 1005=head2 Declaration Syntax 1006 1007The following types of Simple declarations are supported: 1008 1009=over 4 1010 1011=item * 1012 1013I<generator_type> => 'I<method_name>' 1014 1015=item * 1016 1017I<generator_type> => 'I<method_1> I<method_2>...' 1018 1019=item * 1020 1021I<generator_type> => [ 'I<method_1>', 'I<method_2>', ...] 1022 1023=back 1024 1025For a list of the supported values of I<generator_type>, see 1026L<Class::MakeMethods::Docs::Catalog/"STANDARD CLASSES">, or the documentation 1027for each subclass. 1028 1029For each method name you provide, a subroutine of the indicated 1030type will be generated and installed under that name in your module. 1031 1032Method names should start with a letter, followed by zero or more 1033letters, numbers, or underscores. 1034 1035=head2 Argument Normalization 1036 1037The following expansion rules are applied to argument pairs to 1038enable the use of simple strings instead of arrays of arguments. 1039 1040=over 4 1041 1042=item * 1043 1044Each type can be followed by a single meta-method definition, or by a 1045reference to an array of them. 1046 1047=item * 1048 1049If the argument is provided as a string containing spaces, it is 1050split and each word is treated as a separate argument. 1051 1052=item * 1053 1054It the meta-method type string contains spaces, it is split and 1055only the first word is used as the type, while the remaining words 1056are placed at the front of the argument list. 1057 1058=back 1059 1060For example, the following statements are equivalent ways of 1061declaring a pair of Basic::Hash scalar methods named 'foo' and 'bar': 1062 1063 use Class::MakeMethods::Basic::Hash ( 1064 'scalar' => [ 'foo', 'bar' ], 1065 ); 1066 1067 use Class::MakeMethods::Basic::Hash ( 1068 'scalar' => 'foo', 1069 'scalar' => 'bar', 1070 ); 1071 1072 use Class::MakeMethods::Basic::Hash ( 1073 'scalar' => 'foo bar', 1074 ); 1075 1076 use Class::MakeMethods::Basic::Hash ( 1077 'scalar foo' => 'bar', 1078 ); 1079 1080(The last of these is clearly a bit peculiar and potentially misleading if used as shown, but it enables advanced subclasses to provide convenient formatting for declarations with defaults or modifiers, such as C<'Template::Hash:scalar --private' =E<gt> 'foo'>, discussed elsewhere.) 1081 1082=head2 Parameter Syntax 1083 1084The Standard syntax also provides several ways to optionally 1085associate a hash of additional parameters with a given method 1086name. 1087 1088=over 4 1089 1090=item * 1091 1092I<generator_type> => [ 1093 'I<method_1>' => { I<param>=>I<value>... }, I<...> 1094 ] 1095 1096A hash of parameters to use just for this method name. 1097 1098(Note: to prevent confusion with self-contained definition hashes, 1099described below, parameter hashes following a method name must not 1100contain the key C<'name'>.) 1101 1102=item * 1103 1104I<generator_type> => [ 1105 [ 'I<method_1>', 'I<method_2>', ... ] => { I<param>=>I<value>... } 1106 ] 1107 1108Each of these method names gets a copy of the same set of parameters. 1109 1110=item * 1111 1112I<generator_type> => [ 1113 { 'name'=>'I<method_1>', I<param>=>I<value>... }, I<...> 1114 ] 1115 1116By including the reserved parameter C<'name'>, you create a self-contained declaration with that name and any associated hash values. 1117 1118=back 1119 1120Simple declarations, as shown in the prior section, are treated as if they had an empty parameter hash. 1121 1122=head2 Default Parameters 1123 1124A set of default parameters to be used for several declarations 1125may be specified using any of the following types of arguments to 1126a method generator call: 1127 1128=over 4 1129 1130=item * 1131 1132I<generator_type> => [ 1133 '-I<param>' => 'I<value>', 'I<method_1>', 'I<method_2>', I<...> 1134 ] 1135 1136Set a default value for the specified parameter to be passed to all subsequent declarations. 1137 1138=item * 1139 1140I<generator_type> => [ 1141 '--' => { 'I<param>' => 'I<value>', ... }, 'I<method_1>', 'I<method_2>', I<...> 1142 ] 1143 1144Set default values for one or more parameters to be passed to all subsequent declarations. Equivalent to a series of '-I<param>' => 'I<value>' pairs for each pair in the referenced hash. 1145 1146=item * 1147 1148I<generator_type> => [ 1149 '--I<special_param>', 'I<method_1>', 'I<method_2>', I<...> 1150 ] 1151 1152Appends to the default value for a special parameter named "--". This parameter is currently only used by some subclasses; for details see L<Class::MakeMethods::Template> 1153 1154=back 1155 1156Parameters set in these ways are passed to each declaration that 1157follows it until the end of the method-generator argument array, 1158or until overridden by another declaration. Parameters specified 1159in a hash for a specific method name, as discussed above, will 1160override the defaults of the same name for that particular method. 1161 1162 1163=head1 DIAGNOSTICS 1164 1165The following warnings and errors may be produced when using 1166Class::MakeMethods to generate methods. (Note that this list does not 1167include run-time messages produced by calling the generated methods.) 1168 1169These messages are classified as follows (listed in increasing order of 1170desperation): 1171 1172 (Q) A debugging message, only shown if $CONTEXT{Debug} is true 1173 (W) A warning. 1174 (D) A deprecation. 1175 (F) A fatal error in caller's use of the module. 1176 (I) An internal problem with the module or subclasses. 1177 1178Portions of the message which may vary are denoted with a %s. 1179 1180=over 4 1181 1182=item Can't interpret meta-method template: argument is empty or 1183undefined 1184 1185(F) 1186 1187=item Can't interpret meta-method template: unknown template name 1188'%s' 1189 1190(F) 1191 1192=item Can't interpret meta-method template: unsupported template 1193type '%s' 1194 1195(F) 1196 1197=item Can't make method %s(): template specifies unknown behavior 1198'%s' 1199 1200(F) 1201 1202=item Can't parse meta-method declaration: argument is empty or 1203undefined 1204 1205(F) You passed an undefined value or an empty string in the list 1206of meta-method declarations to use or make. 1207 1208=item Can't parse meta-method declaration: missing name attribute. 1209 1210(F) You included an hash-ref-style meta-method declaration that 1211did not include the required name attribute. You may have meant 1212this to be an attributes hash for a previously specified name, but 1213if so we were unable to locate it. 1214 1215=item Can't parse meta-method declaration: unknown template name 1216'%s' 1217 1218(F) You included a template specifier of the form C<'-I<template_name>'> 1219in a the list of meta-method declaration, but that template is not 1220available. 1221 1222=item Can't parse meta-method declaration: unsupported declaration 1223type '%s' 1224 1225(F) You included an unsupported type of value in a list of meta-method 1226declarations. 1227 1228=item Compilation error: %s 1229 1230(I) 1231 1232=item Not an interpretable meta-method: '%s' 1233 1234(I) 1235 1236=item Odd number of arguments passed to %s make 1237 1238(F) You specified an odd number of arguments in a call to use or 1239make. The arguments should be key => value pairs. 1240 1241=item Unable to compile generated method %s(): %s 1242 1243(I) The install_methods subroutine attempted to compile a subroutine 1244by calling eval on a provided string, which failed for the indicated 1245reason, usually some type of Perl syntax error. 1246 1247=item Unable to dynamically load $package: $%s 1248 1249(F) 1250 1251=item Unable to install code for %s() method: '%s' 1252 1253(I) The install_methods subroutine was passed an unsupported value 1254as the code to install for the named method. 1255 1256=item Unexpected return value from compilation of %s(): '%s' 1257 1258(I) The install_methods subroutine attempted to compile a subroutine 1259by calling eval on a provided string, but the eval returned something 1260other than than the code ref we expect. 1261 1262=item Unexpected return value from meta-method constructor %s: %s 1263 1264(I) The requested method-generator was invoked, but it returned an unacceptable value. 1265 1266=back 1267 1268 1269=head1 EXTENDING 1270 1271Class::MakeMethods can be extended by creating subclasses that 1272define additional meta-method types. Callers then select your 1273subclass using any of the several techniques described above. 1274 1275=head2 Creating A Subclass 1276 1277The begining of a typical extension might look like the below: 1278 1279 package My::UpperCaseMethods; 1280 use strict; 1281 use Class::MakeMethods '-isasubclass'; 1282 1283 sub my_method_type { ... } 1284 1285You can name your subclass anything you want; it does not need to 1286begin with Class::MakeMethods. 1287 1288The '-isasubclass' flag is a shortcut that automatically puts 1289Class::MakeMethods into your package's @ISA array so that it will 1290inherit the import() and make() class methods. If you omit this 1291flag, you will need to place the superclass in your @ISA explicitly. 1292 1293Typically, the subclass should B<not> inherit from Exporter; both 1294Class::MakeMethods and Exporter are based on inheriting an import 1295class method, and getting a subclass to support both would require 1296additional effort. 1297 1298=head2 Naming Method Types 1299 1300Each type of method that can be generated is defined in a subroutine 1301of the same name. You can give your meta-method type any name that 1302is a legal subroutine identifier. 1303 1304(Names begining with an underscore, and the names C<import> and 1305C<make>, are reserved for internal use by Class::MakeMethods.) 1306 1307If you plan on distributing your extension, you may wish to follow 1308the "Naming Convention for Generated Method Types" described above 1309to facilitate reuse by others. 1310 1311=head2 Implementation Options 1312 1313Each method generation subroutine can be implemented in any one of 1314the following ways: 1315 1316=over 4 1317 1318=item * 1319 1320Subroutine Generation 1321 1322Returns a list of subroutine name/code pairs. 1323 1324The code returned may either be a coderef, or a string containing 1325Perl code that can be evaled and will return a coderef. If the eval 1326fails, or anything other than a coderef is returned, then 1327Class::MakeMethods croaks. 1328 1329For example a simple sub-class with a method type upper_case_get_set 1330that generates an accessor method for each argument provided might 1331look like this: 1332 1333 package My::UpperCaseMethods; 1334 use Class::MakeMethods '-isasubclass'; 1335 1336 sub uc_scalar { 1337 my $class = shift; 1338 map { 1339 my $name = $_; 1340 $name => sub { 1341 my $self = shift; 1342 if ( scalar @_ ) { 1343 $self->{ $name } = uc( shift ) 1344 } else { 1345 $self->{ $name }; 1346 } 1347 } 1348 } @_; 1349 } 1350 1351Callers could then generate these methods as follows: 1352 1353 use My::UpperCaseMethods ( 'uc_scalar' => 'foo' ); 1354 1355=item * 1356 1357Aliasing 1358 1359Returns a string containing a different meta-method type to use 1360for those same arguments. 1361 1362For example a simple sub-class that defines a method type stored_value 1363might look like this: 1364 1365 package My::UpperCaseMethods; 1366 use Class::MakeMethods '-isasubclass'; 1367 1368 sub regular_scalar { return 'Basic::Hash:scalar' } 1369 1370And here's an example usage: 1371 1372 use My::UpperCaseMethods ( 'regular_scalar' => [ 'foo' ] ); 1373 1374=item * 1375 1376Rewriting 1377 1378Returns one or more array references with different meta-method 1379types and arguments to use. 1380 1381For example, the below meta-method definition reviews the name of 1382each method it's passed and creates different types of meta-methods 1383based on whether the declared name is in all upper case: 1384 1385 package My::UpperCaseMethods; 1386 use Class::MakeMethods '-isasubclass'; 1387 1388 sub auto_detect { 1389 my $class = shift; 1390 my @rewrite = ( [ 'Basic::Hash:scalar' ], 1391 [ '::My::UpperCaseMethods:uc_scalar' ] ); 1392 foreach ( @_ ) { 1393 my $name_is_uppercase = ( $_ eq uc($_) ) ? 1 : 0; 1394 push @{ $rewrite[ $name_is_uppercase ] }, $_ 1395 } 1396 return @rewrite; 1397 } 1398 1399The following invocation would then generate a regular scalar accessor method foo, and a uc_scalar method BAR: 1400 1401 use My::UpperCaseMethods ( 'auto_detect' => [ 'foo', 'BAR' ] ); 1402 1403=item * 1404 1405Generator Object 1406 1407Returns an object with a method named make_methods which will be responsible for returning subroutine name/code pairs. 1408 1409See L<Class::MakeMethods::Template> for an example. 1410 1411=item * 1412 1413Self-Contained 1414 1415Your code may do whatever it wishes, and return an empty list. 1416 1417=back 1418 1419=head2 Access to Options 1420 1421Global option values are available through the _context() class method at the time that method generation is being performed. 1422 1423 package My::Maker; 1424 sub my_methodtype { 1425 my $class = shift; 1426 warn "Installing in " . $class->_context('TargetClass'); 1427 ... 1428 } 1429 1430=over 4 1431 1432=item * 1433 1434TargetClass 1435 1436Class into which code should be installed. 1437 1438=item * 1439 1440MakerClass 1441 1442Which subclass of Class::MakeMethods will generate the methods? 1443 1444=item * 1445 1446ForceInstall 1447 1448Controls whether generated methods will be installed over pre-existing methods in the target package. 1449 1450=back 1451 1452 1453=head1 SEE ALSO 1454 1455=head2 License and Support 1456 1457For distribution, installation, support, copyright and license 1458information, see L<Class::MakeMethods::Docs::ReadMe>. 1459 1460=head2 Package Documentation 1461 1462A collection of sample uses is available in 1463L<Class::MakeMethods::Docs::Examples>. 1464 1465See the documentation for each family of subclasses: 1466 1467=over 4 1468 1469=item * 1470 1471L<Class::MakeMethods::Basic> 1472 1473=item * 1474 1475L<Class::MakeMethods::Standard> 1476 1477=item * 1478 1479L<Class::MakeMethods::Composite> 1480 1481=item * 1482 1483L<Class::MakeMethods::Template> 1484 1485=back 1486 1487A listing of available method types from each of the different subclasses 1488is provided in L<Class::MakeMethods::Docs::Catalog>. 1489 1490=head2 Related Modules 1491 1492For a brief survey of the numerous modules on CPAN which offer some type 1493of method generation, see L<Class::MakeMethods::Docs::RelatedModules>. 1494 1495In several cases, Class::MakeMethods provides functionality closely 1496equivalent to that of an existing module, and emulator modules are provided 1497to map the existing module's interface to that of Class::MakeMethods. 1498See L<Class::MakeMethods::Emulator> for more information. 1499 1500If you have used Class::MethodMaker, you will note numerous similarities 1501between the two. Class::MakeMethods is based on Class::MethodMaker, but 1502has been substantially revised in order to provide a range of new features. 1503Backward compatibility and conversion documentation is provded in 1504L<Class::MakeMethods::Emulator::MethodMaker>. 1505 1506=head2 Perl Docs 1507 1508See L<perlboot> for a quick introduction to objects for beginners. For 1509an extensive discussion of various approaches to class construction, see 1510L<perltoot> and L<perltootc> (called L<perltootc> in the most recent 1511versions of Perl). 1512 1513See L<perlref/"Making References">, point 4 for more information on 1514closures. (FWIW, I think there's a big opportunity for a "perlfunt" podfile 1515bundled with Perl in the tradition of "perlboot" and "perltoot", exploring 1516the utility of function references, callbacks, closures, and 1517continuations... There are a bunch of useful references available, but 1518not a good overview of how they all interact in a Perlish way.) 1519 1520=cut 1521