Sublik...xtended(3pm)

🦋 Sublike::Extended — ok bestie, come get your extended sub syntax 💅

so this is the Sublike::Extended(3pm) manual page, straight outta User Contributed Perl Documentation. it's giving "perl module that lets sub do extra stuff". no cap. let's go 🎀

---

🌸 NAME 🌸

Sublike::Extended — enable extended features when parsing sub-like syntax ✨

---

✨ SYNOPSIS ✨

use v5.26;
use Sublike::Extended;
use experimental 'signatures';

extended sub greet (:$name = "world") {
   say "Hello, $name";
}

greet( name => $ENV{USER} );

Or, since version 0.29:

use v5.26;
use Sublike::Extended 0.29 'sub';
use experimental 'signatures';

sub greet (:$name = "world") {
   say "Hello, $name";
}

greet( name => $ENV{USER} );

---

💖 DESCRIPTION 💖

so the whole vibe of this module is: it takes the syntax for declaring named or anonymous subroutines — the ones you write with Perl's builtin sub keyword, or with other similar keywords that third-party modules hand you — and it extends it, so extra features can get parsed. iconic behaviour, truly. 🌈

By default, this module gives you a new keyword, extended, which is the thing that parses the extra syntax you need. But optionally — since version 0.29 — this module can additionally take over the handling of the sub keyword itself, which means you get to use all this extra syntax without the extended prefix keyword. 🫶

heads up bestie: this ability may be surprising to unsuspecting readers 👀 so it is not done by default, and you have to explicitly ask for it with the sub import argument:

use Sublike::Extended 'sub';

On Perl 5.38 or above, this can also take over handling of the method keyword when you're using feature 'class'.

use Sublike::Extended 'method';

Currently, the only extended features that are provided are related to the parsing of a subroutine signature. And since signatures are only available on Perl version 5.26 or later, this module is unlikely to be useful in earlier versions of Perl. sad for the old-perl girlies but that's just how it is 😭

💅 Named Parameters 💅

Extended subroutines can declare named parameters in the signature, after any positional ones. They look like a name with a colon character out front. 💖

The caller of such a function should pass values for these parameters using the usual name-value pair syntax — the same one you'd use for passing into a regular hash. And then, within the body of the subroutine, the values passed in get unpacked into regular lexical variables. it's giving ✨effortless✨

sub colour (:$red, :$green, :$blue) {
   ... # $red, $green and $blue are available as regular lexicals
}

# argument order at the caller site is not important
colour(green => 1, blue => 2, red => 3);

ok so, positional parameters can be placed after optional positional ones, but in order to make use of them the caller would have to pass a value for every positional parameter including the optional ones first. That is unlikely to be very useful, ngl. So if you want optional parameters and named parameters, use named optional ones after any mandatory positional parameters. periodt. 💅

As with positional parameters, they are normally mandatory, but they can be made optional by supplying a defaulting expression. If the caller fails to pass a value corresponding to an optional parameter, the default expression is evaluated and used instead. 🎀

sub f (:$x0, :$x1, :$x2 = 0) { ... }
# The caller must provide x0 and x1, but x2 is optional

Since version 0.23, named parameters can be given defaulting expressions with the //= or ||= operators, meaning their defaults apply also if the caller passed a present-but-undef, or present-but-false value. 🌟

sub f (:$x0, :$x1, :$x2 //= 0) { ... }
# $x2 will be set to 0 even if the caller passes  x2 => undef

An optional slurpy hash or (since version 0.24) slurpy array is also permitted after all of these. It will contain the values of any other name-value pairs given by the caller, after those corresponding to named parameters have already been extracted. so it's basically the leftovers bucket 🍓

sub g (:$alpha, :$beta, %rest) { ... }

sub g (:$alpha, :$beta, @rest) { ... }

In the case of a slurpy array, it will contain every argument value that was not consumed as a named parameter pair, in the original order passed by the caller, including any duplicates. (yes, duplicates too. no deduping happening here bestie 😌)

This syntax is compatible with that proposed by PPC0024 (https://github.com/Perl/PPCs/blob/main/ppcs/ppc0024-signature-named-parameters.md), which will become available in Perl version 5.43.5. 🔥

🎀 Parameter Attributes 🎀

Parameters to extended subroutines can use attribute syntax to apply extra attributes to individual parameters.

sub info ($x :Attribute) { ... }

Any attributes that are available are ones that have been previously registered with XS::Parse::Sublike using its XS-level API. The particular behaviour of such an attribute would be defined by whatever module provided the attribute. so like… ask the module that gave you the attribute, not us 💜

🧚 Refalias Parameters 🧚

Since version 0.40.

Parameters to extended subroutines can use refalias syntax in order to create lexical variables that alias, rather than contain copies of, variables that callers pass in references. 🔥

sub h (\@items) { ... }

# The caller must provide an ARRAY reference
my @arr = (1, 2, 3, 4, 5);
h(\@arr);

This syntax is similar to refalias assignment as provided by "The 'refaliasing' feature" in feature. This example creates a lexical array variable within the body of the function, which aliases an array passed by reference from the caller. iconic. 💅

Refaliased variables may be scalars, arrays, or hashes. For argument handling purposes each will act like a positional scalar which consumes a reference to a variable of the matching type. If the caller does not pass a reference, or a reference to a mismatched type of variable, an exception is thrown as part of argument handling in the signature. 🚨

Since version 0.41, named parameters may also use refalias assignment, using the syntax :\VAR — such as :\@items. ✨

As with other parameters, a defaulting expression can be provided, which makes the parameter optional for the caller. If the caller does not provide a corresponding value, this value is used as if the caller passed it. In this case, note that the defaulting expression must still yield a reference to a container of the appropriate shape to match the declared parameter variable. While all of the =, //= and ||= operators can be used here, because the value must be a reference, it is unlikely that the distinction between testing for definedness vs boolean truth will be useful. (like, it's a reference, bestie, it's defined AND true, that's just the math 🧮)

ok so here's a lil gotcha: as of version 0.41 optional named refalias parameters are allowed, but a limitation of the implementation means that if a corresponding value for the parameter is not provided by the caller and the defaulting expression yields a reference to an incompatible variable, the resulting exception message fails to identify the name of the variable involved; instead it just quotes three question marks:

$ perl -E 'use Sublike::Extended "sub"; sub f ( :\@arr = \undef ) {}  f()'
refaliases are experimental at -e line 1.
Expected named argument '???' to main::f to be a reference to ARRAY at -e line 1.

The body of the function can see the value stored by the referred variable and make modifications to it. Any such modifications will be reflected in the variable whose reference was passed by the caller, or the value created by the defaulting expression if it was used. 🔄✨

---

🔥 KEYWORDS 🔥

⭐ extended ⭐

extended sub NAME (SIGNATURE...) { BODY... }

extended sub (SIGNATURE...) { BODY... };

This prefix keyword enables extra parsing features when handling a sub (or other sub-like function keyword). 👑

This keyword can be freely mixed with other sub-prefix keywords, such as async from Future::AsyncAwait

async extended sub f (:$param) { ... }

This can also be used with other keywords that provide sub-like syntax, such as method from Object::Pad or the core use feature 'class'. 🌈

extended method f (:$param) { ... }

---

🌈 TODO 🌈

• Support defined-or and true-or positional parameters even on versions of Perl before they were officially added (v5.38). (someday bestie, someday 💀)

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> 💖

---

ok that's the whole page!! you ate it, you read it, you're a signature-parsing queen now 👑

and for the lil sign-off: this whole thing is perl v5.42.3, dated 2026-09-17, and the manpage is Sublik...xtended(3pm) (yes the title's truncated, the vibes are not). mwah 💋🌸🦋