This file is indexed.

/usr/share/perl5/Class/Multimethods.pod is in libclass-multimethods-perl 1.70-5.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
=head1 NAME

Class::Multimethods - Support multimethods and function overloading in Perl

=head1 VERSION

This document describes version 1.70 of Class::Multimethods,
released April  9, 2000.

=head1 SYNOPSIS

 # IMPORT THE multimethod DECLARATION SUB...

    use Class::Multimethods;

 # DECLARE VARIOUS MULTIMETHODS CALLED find...

 # 1. DO THIS IF find IS CALLED WITH A Container REF AND A Query REF...

    multimethod find => (Container, Query) 
		     => sub { $_[0]->findquery($_[1]) };

 # 2. DO THIS IF find IS CALLED WITH A Container REF AND A Sample REF...

    multimethod find => (Container, Sample)
		     => sub { $_[0]->findlike($_[1]) };

 # 3. DO THIS IF find IS CALLED WITH AN Index REF AND A Word REF...

    multimethod find => (Index, Word)      
		     => sub { $_[0]->lookup_word($_[1]) };

 # 4. DO THIS IF find IS CALLED WITH AN Index REF AND A qr// PATTERN

    multimethod find => (Index, Regexp)    
		     => sub { $_[0]->lookup_rx($_[1]) };

 # 5. DO THIS IF find IS CALLED WITH AN Index REF AND A NUMERIC SCALAR

    multimethod find => (Index, '#')       
		     => sub { $_[0]->lookup_elem($_[1]) };

 # 6. DO THIS IF find IS CALLED WITH AN Index REF AND A NON-NUMERIC SCALAR

    multimethod find => (Index, '$')       
		     => sub { $_[0]->lookup_str($_[1]) };

 # 7. DO THIS IF find IS CALLED WITH AN Index REF AND AN UNBLESSED ARRAY REF
 #    (NOTE THE RECURSIVE CALL TO THE find MULTIMETHOD)

    multimethod find => (Index, ARRAY)     
		     => sub { map { find($_[0],$_) } @{$_[1]} };


 # SET UP SOME OBJECTS...

	my $cntr = new Container ('./datafile');
	my $indx = $cntr->get_index();

 # ...AND SOME INHERITANCE...

	@BadWord::ISA = qw( Word );
	my $badword = new BadWord("fubar");

 # ...AND EXERCISE THEM...

	print find($cntr, new Query('cpan OR Perl'));		# CALLS 1.
	print find($cntr, new Example('by a committee'));	# CALLS 2.

	print find($indx, new Word('sugar'));			# CALLS 3.
	print find($indx, $badword);				# CALLS 3.
	print find($indx, qr/another brick in the Wall/);	# CALLS 4.
	print find($indx, 7);					# CALLS 5.
	print find($indx, 'But don't do that.');		# CALLS 6.
	print find($indx, [1,"one"]);				# CALLS 7,
								# THEN 5 & 6.
								


=head1 DESCRIPTION

The Class:Multimethod module exports a subroutine (&multimethod)
that can be used to declare other subroutines that are dispatched
using a algorithm different from the normal Perl subroutine or
method dispatch mechanism.

Normal Perl subroutines are dispatched by finding the
appropriately-named subroutine in the current (or specified) package
and calling that. Normal Perl methods are dispatched by attempting to
find the appropriately-named subroutine in the package into which the
invoking object is blessed or, failing that, recursively searching for
it in the packages listed in the appropriate C<@ISA> arrays.

Class::Multimethods multimethods are dispatched quite differently. The
dispatch mechanism looks at the classes or types of each argument to
the multimethod (by calling C<ref> on each) and determines the
"closest" matching I<variant> of the multimethod, according to the
argument types specified in the variants' definitions (see L<Finding
the "nearest" multimethod> for a definition of "closest").

The result is something akin to C++'s function overloading, but more
intelligent, since multimethods take the inheritance relationships of
each argument into account. Another way of thinking of the mechanism
is that it performs polymorphic dispatch on I<every> argument of a 
method, not just the first.

=head2 Defining multimethods

The Class::Multimethods module exports a subroutine called
C<multimethod>, which can be used to specify multimethod variants with
the dispatch behaviour described above. The C<multimethod> subroutine
takes the name of the desired multimethod, a list of class names, and a
subroutine reference, and generates a corresponding multimethod variant
within the current package.

For example, the declaration:

	package LargeInt;   @ISA = (LargeNumeric);
	package LargeFloat; @ISA = (LargeNumeric);

	package LargeNumeric;
	use Class::Multimethods;

	multimethod divide => (LargeInt, LargeInt) => sub
	{
		LargeInt::divide($_[0],$_[1]);
	};

	multimethod divide => (LargeInt, LargeFloat) => sub
	{
		LargeFloat::divide($_[0]->AsLargeFloat(),$_[1]));
	};

creates a (single!) multimethod C<&LargeNumeric::divide> with two variants.
If the multimethod is called with two references to C<LargeInt> objects
as arguments, the first variant (i.e. anonymous subroutine) is invoked. If the
multimethod is called with a C<LargeInt> reference and a C<LargeFloat>
reference, the second variant is called.

Note that if you're running under C<use strict>, the list of bareword
class names in each variant definition will cause problems.
In that case you'll need to say:

	multimethod divide => ('LargeInt', 'LargeInt') => sub
	{
		LargeInt::divide($_[0],$_[1]);
	};

	multimethod divide => ('LargeInt', 'LargeFloat') => sub
	{
		LargeFloat::divide($_[0]->AsLargeFloat(),$_[1]));
	};


or better still:

	multimethod divide => qw( LargeInt LargeInt ) => sub
	{
		LargeInt::divide($_[0],$_[1]);
	};

	multimethod divide => qw( LargeInt LargeFloat ) => sub
	{
		LargeFloat::divide($_[0]->AsLargeFloat(),$_[1]));
	};

or best of all (;-):

	{
	    no strict;
	
	    multimethod divide => (LargeInt, LargeInt) => sub
	    {
		LargeInt::divide($_[0],$_[1]);
	    };

	    multimethod divide => (LargeInt, LargeFloat) => sub
	    {
		LargeFloat::divide($_[0]->AsLargeFloat(),$_[1]));
	    };
	}


Calling the multimethod with any other combination of C<LargeNumeric>
reference arguments (e.g. a reference to a C<LargeFloat> and a
reference to a C<LargeInt>, or two C<LargeFloat> referencess) results
in an exception being thrown, with the message:

	No viable candidate for call to
	multimethod LargeNumeric::divide at ...

To avoid this, we could provide a "catch-all" variant:

	multimethod divide => (LargeNumeric, LargeNumeric) => sub
	{
		LargeFloat::divide($_[0]->AsLargeFloat(),$_[1]->AsLargeFloat));
	}

Now, calling C<&LargeNumeric::divide> with either a C<LargeFloat>
reference and a C<LargeInt> reference or two C<LargeFloat> references
results in this third variant being invoked. Note that, adding this
third alternative doesn't affect calls to the other two, since
Class::Multimethods always selects the "nearest" match (see L<Finding
the "nearest" multimethod> below for details of what "nearest" means).

This "best fit" behaviour is extremely useful, because it means you can
code the specific cases you want to handle, and the one or more
"catch-all" cases to deal with any other combination of arguments.


=head2 Finding the "nearest" multimethod

Of course, the usefulness of the entire system depends on how intelligently
Class::Multimethods decides which version of a multimethod is "nearest"
to the set of arguments you provided. This decision process is called
"dispatch resolution", and Class::Multimethods does it like this:

=over 4

=item 1.

If the types of the arguments given (as determined by C<ref>) exactly
match the types specified in any variant of the multimethod, that variant
is the one called.

=item 2.

Otherwise, Class::Multimethods compiles a list of "viable targets". A
viable target is a variant of the multimethod with the correct number
of parameters, such that for each parameter the specified parameter
type is a base class of the actual type of the corresponding argument
in the actual call.

=item 3.

If there is only one viable target, it is immediately called. if there are
no viable targets, an exception is thrown indicating the fact.

=item 4.

Otherwise, Class::Multimethod examines each viable target and computes
its "distance" to the actual set of arguments. The distance of a target
is the sum of the distances of each of its parameters. The distance of
an individual parameter is the number of inheritance steps between its
class and the actual class of the corresponding argument.

Hence, if a specific argument is of the same class as the corresponding
parameter type, the distance to that parameter is zero.
If the argument is of a class that is an immediate child of the
parameter type, the distance is 1. If the argument is of a class which 
is a "grandchild" of the parameter type, the distance is 2. Et cetera.

=item 5.

Class::Multimethod then chooses the viable target with the smallest "distance"
as the "final target". If there is more than one viable target with an equally
smallest distance, an exception is thrown indicating that the call is
ambiguous. If there I<is> only a single final target
Class::Multimethod records its identity (so the distance computations don't
have to be repeated next time the same set of argument types is used),
and then calls that final target.

=back

=head2 Where to define multimethods

Class::Multimethods doesn't care which packages the individual variants
of a multimethod are defined in. Every variant of a multimethod is
visible to the underlying multimethod dispatcher, no matter where it
was defined.

For example, the three variants for the C<divide> multimethod shown
above could all be defined in the LargeNumeric package, or the
LargeFloat package or the LargeInt package, or in C<main>, or in a
separate package of their own.

Of course, to make a specific multimethod visible within a given
package you still need to tell that package about it. That can be done
by specifying the name of the multimethod only (i.e. no argument list
or variant code):

	package Some::Other::Package::That::Wants::To::Use::divide;

	use Class::Multimethods;
	multimethod "divide";

For convenience, the declaration itself can be abbreviated to:

	package Some::Other::Package::That::Wants::To::Use::divide;

	use Class::Multimethods "divide";


Similarly, Class::Multimethod doesn't actually care whether
multimethods are called as methods or as regular subroutines. This is quite
different from the behaviour of normal Perl methods and subroutines, where how
you call them, determines how they are dispatched.

With multimethods, since all arguments participate in the polymorphic
resolution of a call (instead of just the first), it make no difference
whether a multimethod is called as a subroutine:

	numref3 = divide($numref1, $numref2);

or a method:

	numref3 = $numref1->divide($numref2);

(so long as the multimethod has been I<declared> in the appropriate place:
the current package for subroutine-like calls, or the invoking object's
package for method-like calls).


In other words, Class::Multimethods also provides general subroutine
overloading. For example:

	package main;
	use IO;
	use Class::Multimethods;

	multimethod debug => (IO::File) => sub
	{
		print $_[0] "This should go in a file\n";
	}

	multimethod debug => (IO::Pipe) => sub
	{
		print $_[0] "This should go down a pipe\n";
	}

	multimethod debug => (IO::Socket) => sub
	{
		print $_[0] "This should go out a socket\n";
	}

	# and later

	debug($some_io_handle);


=head2 Non-class types as parameters

Yet another thing Class::Multimethods doesn't care about is whether the
parameter types for each multimethod variant are the names of "real"
classes or just the identifiers returned when raw Perl data types are
passed to the built-in C<ref> function. That means you could also
define multimethod variants like this:

	multimethod stringify => (ARRAY) => sub
	{
		my @arg = @{$_[0]};
		return "[" .  join(", ",@arg) . "]";
	}

	multimethod stringify => (HASH) => sub
	{
		my %arg = %{$_[0]};
		return "{" . join(", ", map("$_=>$arg{$_}",keys %arg)) . "}";
	}

	multimethod stringify => (CODE) => sub
	{
		return "sub {???}";
	}

	# and later

	print stringify( [1,2,3] ), "\n";
	print stringify( {a=>1,b=>2,c=>3} ), "\n"; 
	print stringify( $array_or_hash_ref ), "\n";

Provided you remember that the parameter types ARRAY, HASH, and CODE
really mean "reference to array", "reference to hash", and "reference
to subroutine", the names of built-in types (i.e. those returned by
C<ref>) are perfectly acceptable as multimethod parameters.

That's a nice bonus, but there's a problem. Because C<ref> returns an
empty string when given any literal string or numeric value, the
following code:

	print stringify( 2001 ), "\n";
	print stringify( "a multiple dispatch oddity" ), "\n";

will produce a nasty surprise:

	No viable candidate for call to multimethod stringify() at line 1

That's because the dispatch resolution process first calls C<ref(2001)>
to get the class name for the first argument, and therefore thinks it's
of class C<"">. Since there's no C<stringify> variant with an empty string as
its parameter type, there are no viable targets for the multimethod
call. Hence the exception.

To overcome this limitation, Class::Multimethods allows three special
pseudo-type names within the parameter lists of multimethod variants.
The first pseudo-type - C<"$"> - is the class that Class::Multimethods
pretends that any scalar value (except a reference) belongs to. Hence,
you can make the two recalcitrant stringifications of scalars work
by defining:

	multimethod stringify => ("$")
		=> sub { return qq{"$_[0]"} }

With that definition in place, the two calls:

	print stringify( 2001 ), "\n";
	print stringify( "a multiple dispatch oddity" ), "\n";

would produce:

	"2001"
	"a multiple dispatch oddity"

That solves the problem, but not as elegantly as it might. It
would be better if numeric values were left unquoted. To this end,
Class::Multimethods offers a second pseudo-type - C<"#"> - which is
the class it pretends numeric scalar values belong to (where
a scalar value is "numeric" if it's truly a numerical value (without implicit
coercions):

	$var = 0	# numeric --> '$'
	$var = 0.0	# numeric --> '$'
	$var = "0";	# string  --> '#'

Hence you could now also define:

	multimethod stringify => ("#")
		=> sub { return "+$_[0]" }
	
the two calls to C<&stringify> now
produce:

	+2001
	"a multiple dispatch oddity"

The final pseudo-type - C<"*"> - is a wild-card or "don't care" type
specifier, which matches I<any> argument type exactly. For example, we
could provide a "catch-all" C<stringify> variant (to handle "GLOB" or
"IO" references, for example):

	multimethod stringify => ("*")
		=> sub { croak "can't stringify a " . ref($_[0]) }
	

The C<"*"> pseudo-type can also be used in multiple-argument multimethods.
For example:

	# General case...

	    multimethod handle => (Window, Event, Mode)
		=> sub { ... }
	
	# Special cases...

	    multimethod handle => (MovableWindow, MoveEvent, NormalMode)
		=> sub { ... }

	    multimethod handle => (ScalableWindow, ResizeEvent, NormalMode)
		=> sub { ... }

	# Very special case
	# (ignore any event in any window in PanicMode)

	    multimethod handle => ("*", "*", PanicMode)
		=> sub { ... }


=head2 Resolving ambiguities and non-dispatchable calls

It's relatively easy to set up a multimethod such that particular
combinations of argument types cannot be correctly dispatched. For
example, consider the following variants of a multimethod called
C<put_peg>:

	multimethod put_peg => (RoundPeg,Hole) => sub
	{
		print "a round peg in any old hole\n";
	};

	multimethod put_peg => (Peg,SquareHole) => sub
	{
		print "any old peg in a square hole\n";
	};

	multimethod put_peg => (Peg,Hole) => sub
	{
		print "any old peg in any old hole\n";
	};

If C<put_peg> is called like so:

	put_peg( RoundPeg->new(), SquareHole->new() );

then Class::Multimethods can't dispatch the call, because it cannot
decide between the C<(RoundPeg,Hole)> and C<(Peg,SquareHole)> variants,
each of which is the same "distance" (i.e. 1 derivation) from the actual
arguments.

The default behaviour is to throw an exception (i.e. die) like this:

	Cannot resolve call to multimethod put_peg(RoundPeg,SquareHole).
	The multimethods:
		put_peg(RoundPeg,Hole)
		put_peg(Peg,SquareHole)
	are equally viable at ...

Sometimes, however, the more specialized variants are only
optimizations, and a more general case (e.g. the C<(Peg,Hole)> variant)
would suffice as a default where such an ambiguity exists. If that is
the case, it's possible to tell Class::Multimethods to resolve the
ambiguity by calling that variant, using the C<resolve_ambiguous>
subroutine. C<resolve_ambiguous> is automatically exported by
Class::Multimethods and is used like this:

	resolve_ambiguous put_peg => (Peg,Hole);

That is, you specify the name of the multimethod being disambiguated, and the
signature of the variant to be used in ambiguous cases. Of course, the specified
variant must actually exist at the time of the call. If it doesn't,
Class::Multimethod ignores it and throws the usual exception.

Alternatively, if no variant is suitable as a default, you can register a reference to a
subroutine that is to be called instead:

	resolve_ambiguous put_peg => \&disambiguator;

Now, whenever C<put_peg> can't dispatch a call because it's ambiguous, 
C<disambiguator> will be called instead, with the
same argument list as C<put_peg> was given.

Of course, C<resolve_ambiguous> doesn't care what subroutine it's given a 
reference to, so you can also use an anonymous subroutine:

	resolve_ambiguous put_peg
		=> sub
		   {
			print "can't put a ", ref($_[0]),
			      " into a ", ref($_[1]), "\n";
		   };


Dispatch can also fail if there are I<no> suitable variants available
to handle a particular call. For example:

	put_peg( JPEG->new(), Loophole->new() );

which would normally produce the exception:

	No viable candidate for call to
	multimethod put_peg(JPeg,Loophole) at ...

since classes JPEG and Loophole are't in the Peg and Hole hierarchies, so
there's no inheritance path back to a more general variant.

To handle cases like this, you can use the <resolve_no_match> subroutine,
which is also exported from Class::Multimethods. C<resolve_no_match>
registers a multimethod variant, or a reference to some other subroutine, 
that is then used whenever the dispatch mechanism can't find a suitable
variant for a given multimethod call.

For example:

	resolve_no_match put_peg
		=> sub
		   {
			put_jpeg(@_)
				if ref($_[0]) eq 'JPEG';
			shift()->hang(@_)
				if ref($_[0]) eq 'ClothesPeg';
			hammer(@_)
				if ref($_[0]) eq 'TentPeg';
			# etc.
				
		   };

As with C<resolve_ambiguous> the registered variant or subroutine
is called with the same set of arguments that were passed to
the original multimethod call.

=head2 Redispatching multimethod calls

Sometimes a polymorphic method in a derived class is used to add
functionality to an inherited method. For example, a derived class's
C<print_me> method might call it's base class's C<print_me>, making use
of Perl's special C<$obj->SUPER::method()> construct:

	class Base;

	sub print_me
	{	
		my ($self) = @_;
		print "Base stuff\n";
	}

	class Derived; @ISA = qw( Base );

	sub print_me
	{
		my ($self) = @_;
		$self->SUPER::print_me();	# START LOOKING IN ANCESTORS
		print "Derived stuff\n";
	}

If the C<print_me> methods are implemented as multimethods, it's still possible
to reinvoke an "ancestral" method, using the automatically exported
C<Class::Multimethods::superclass> subroutine:

	use Class::Multimethods;

	multimethod print_me => (Base) => sub
	{	
		my ($self) = @_;
		print "Base stuff\n";
	}

	multimethod print_me => (Derived) => sub
	{
		my ($self) = @_;
		print_me( superclass($self) );	# START LOOKING IN ANCESTORS
		print "Derived stuff\n";
	}
	}

Applying C<superclass> to the multimethod argument tells Class::Multimethod
to start looking for parameter types amongst the ancestors of Derived.

It's also possible in regular Perl to explcitly tell the polymorphic dispacther
where to start looking, by explicitly qualifying the method name:

	sub Derived::print_me
	{
		my ($self) = @_;
		$self->Base::print_me();	# START LOOKING IN Base CLASS
		print "Derived stuff\n";
	}

The same is possible with multimethods. C<superclass> takes an optional second
argument that tells Class::Multimethods exactly where to start looking:

	multimethod print_me => (Derived) => sub
	{
		my ($self) = @_;
		print_me( superclass($self => Base) );	# START LOOKING IN Base
		print "Derived stuff\n";
	}

Note that, unlike regular method calls, with multimethods you can apply the
C<superclass> subroutine to any or all of a multimethod's arguments. For
example:

	multimethod handle => (MovableWindow, MoveEvent, NormalMode) => sub
	{
		my ($w, $e, $m) = @_;

		# Do any special stuff,
		# then redispatch to more general handler...

		handle(superclass($w), $e, superclass($m => Mode) );
	}

In this case the redispatch would start looking for variants which matched
C<(I<any of MovableWindow's ancestors>, MoveEvent, Mode)>.

It's also important to remember that, as with regular methods,
the class of the actual arguments doesn't change just because we subverted the
dispatch sequence. That means if the above redispatch called the handle variant
that takes arguments (Window, MoveEvent, Mode), the actual arguments would
still be of types (MovableWindow, MoveEvent, NormalMode).

=head1 DIAGNOSTICS

If you call C<multimethod> and forget to provide a code reference as the
last argument, it C<die>s with the message:

	"multimethod: last arg must be a code reference at %s"


If the dispatch mechanism cannot find any multimethod with a signature
matching the actual arguments, it C<die>s with the message:

	"No viable candidate for call to multimethod %s at %s"
	

If the dispatch mechanism finds two or more multimethods with signatures
equally "close" to the actual arguments
(see L<"The dispatch resolution process">), it C<die>s with the message:

	"Cannot resolve call to multimethod %s. The multimethods:
		%s
	 are equally viable at %s"

If you specify two variants with the same parameter lists, Class::Multimethods
warns:

	"Multimethod %s redefined at %s"

but only if $^W is true (i.e. under the C<-w> flag).

=head1 AUTHOR

Damian Conway (damian@conway.org)

=head1 BUGS AND IRRITATIONS

There are undoubtedly serious bugs lurking somewhere in code this complex :-)
Bug reports and other feedback are most welcome.

Ongoing annoyances include:

=over 4

=item *

The module uses qr// constructs to improve performance. Hence it won't
run under Perls earlier than 5.005.

=item *

Multimethod dispatch is much slower than regular dispatch when the
resolution has to resort to the more generic cases (though it's
actually as very nearly as fast as doing the equivalent type resolution
"by hand", and certainly more reliable and maintainable)

=item *

The cache management is far too dumb. Adding any new multimethod
clobbers the entire cache, when it should only expunge those entries
"upstream" from the the new multimethod's actual parameter types.

It's unclear, however, under what circumstances the expense of a more
careful cache correction algorithm would ever be recouped by the savings in
dispatch (well, obviously, when the installion of multimethods is a
rare event and multimethod dispatching is frequent, but where is the
breakeven point?)

=back

=head1 COPYRIGHT

        Copyright (c) 1998-2000, Damian Conway. All Rights Reserved.
      This module is free software. It may be used, redistributed
      and/or modified under the terms of the Perl Artistic License
           (see http://www.perl.com/perl/misc/Artistic.html)