.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Syntax::Keyword::MultiSub 3pm"
.TH Syntax::Keyword::MultiSub 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
"Syntax::Keyword::MultiSub" \- multiple dispatch on subroutines
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&   use v5.26;
\&   use Syntax::Keyword::MultiSub;
\&   use experimental \*(Aqsignatures\*(Aq;
\&
\&   multi sub max()          { return undef; }
\&   multi sub max($x)        { return $x; }
\&   multi sub max($x, @more) { my $y = max(@more);
\&                              return $x > $y ? $x : $y; }
\&
\&   say max(1, 2, 15, 3, 4);  # prints 15
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides a new keyword, \f(CW\*(C`multi\*(C'\fR, to put before subroutine
declarations, which permits multiple distinct function bodies to be provided,
which take different parameters. A call to a \f(CW\*(C`multi sub\*(C'\fR will invoke
whichever function body best fits the arguments passed.
.PP
Currently this module can only make dispatching decisions based on the number
of arguments as compared to the number of signature parameters each body was
expecting. It requires \fIperl\fR version 5.26 or above, in order to get enough
support from signatures. Note also enabling this module does not enable the
\&\f(CW\*(C`signatures\*(C'\fR feature; you must do that independently.
.SH KEYWORDS
.IX Header "KEYWORDS"
.SS multi
.IX Subsection "multi"
.Vb 1
\&   multi sub NAME (SIGNATURE) { BODY... }
.Ve
.PP
Declares an alternative for the \f(CW\*(C`multi sub\*(C'\fR of the given name. Each
alternative will be distinguished by the number of parameters its signature
declares. If the signature includes optional parameters, this alternative is
considered to cover the entire range from none to all of the optional ones
being present. The ranges of parameter count covered by every alternative to
a given function name must be non-overlapping; it is a compiletime error for
two function bodies to claim the same number of parameters.
.PP
Each of the non-final alternatives for any given name must use only scalar
parameters (though some may be optional); but as a special-case, the final
alternative may end in a slurpy parameter (either an array or a hash). If this
is the case then it will be considered for dispatch if none of the previous
alternatives match, as long as it has at least the minimum number of required
parameters present.
.SH "WITH OTHER MODULES"
.IX Header "WITH OTHER MODULES"
.SS Future::AsyncAwait
.IX Subsection "Future::AsyncAwait"
As of Future::AsyncAwait version 0.55 a cross-module integration test
asserts that the \f(CW\*(C`multi\*(C'\fR modifier can be applied to \f(CW\*(C`async sub\*(C'\fR.
.PP
.Vb 2
\&   use Future::AsyncAwait;
\&   use Syntax::Keyword::MultiSub;
\&
\&   async multi sub f () { return "nothing"; }
\&   async multi sub f ($key) { return await get_thing($key); }
.Ve
.SH TODO
.IX Header "TODO"
.IP \(bu 4
Much better error checking and diagnostics for function bodies that don't use
signatures.
.IP \(bu 4
Cross-module testing with Object::Pad (for \f(CW\*(C`multi method\*(C'\fR). This may
require a better combined implementation, to be aware of method resolution
order, inheritence, etc...
.IP \(bu 4
An eventual consideration of type assertions or value testing, as well as
simple argument count.
.Sp
This particular task is likely to be a large undertaking as it spans several
other areas of language. As well as types on parameters, it would be nice to 
put them on lexical variables, object slots, \f(CW\*(C`match/case\*(C'\fR comparisons, and so
on. It would be a shame to invent a special mechanism for one of these areas
that could not be reüsed by the others.
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>