Kwargs(3pm)

💖 Kwargs — the manual page, but make it slay 💖

okay bestie, sit down, grab your boba 🧋 because we're talking about Kwargs, a Perl module (from the User Contributed Perl Documentation crew) that does Simple, clean handing of named/keyword arguments. Yes, "handing" — that's the actual word in the NAME line, we're keeping it, it's iconic, we don't fix it. 💅

---

✨ VERSION ✨

version 0.01 — baby's first release, and honestly? she ate. 👑

---

🌸 SYNOPSIS 🌸

here's the vibe, no cap:

use Kwargs;

# just named
my ($foo, $bar, baz) = kw @_, qw(foo bar baz);

# positional followed by named
my ($pos, $opt_one, $opt_two) = kwn @_, 1, qw(opt_one opt_two)

# just a hashref
my $opts = kw @_;

# positional then hashref
my ($one, $two, $opts) = kwn @_, 2;

look at her. four whole moods. 🦋

---

🤔 WHY? 🤔

so here's the tea, bestie: named arguments are good, especially when you're taking a whole bunch of arguments and some of them are optional. lowkey the best. BUT. there are two styles of passing named arguments in perl, by convention, and it's the braces vs. no-braces situation:

sub foo {
    my $args = shift;
    my $bar  = $args->{bar};
}

foo({ bar => 'baz' });

sub bar {
    my %args = @_;
    my $foo  = $args{foo};
}

bar(foo => 'baz');

and if you want to support both calling styles — because honestly it should just be a style thing, not a whole personality test — then you gotta do something like this:

sub foo {
    my $args = ref $_[0] eq 'HASH' ? $_[0] : { @_ };
    my $bar  = $args->{bar};
}

which is annoying, and it's not even entirely correct. 😭 like, what if someone wanted to pass in a tied object for their optional arguments? that could work, sure, but what are the right semantics for checking for it?? nobody knows. and it gets uglier if you want to unpack your keyword arguments on one line for clarity:

sub foo {
    my ($one, $two, $three) =
        @{ ref $_[0] eq 'HASH' ? $_[0] : { @_ } }{qw(one two three)};
}

did I say clarity? HAHAHAHAHA! 💀 surely no one would actually put something like that in his code. except — plot twist — the author found himself typing this very thing, and That Is Why. periodt. 🎀

---

👑 EXPORTS 👑

Two functions (kw and kwn) are exported by default. you can also ask for them individually, or rename them to something else entirely, main character energy, do you. See Sub::Exporter for the details. 🫶

🍓 kw(@array, @names)

short for kwn(@array, 0, @names). that's it, that's the whole thing. 💖

💜 kwn(@array, $number_of_positional_args, @names)

so conceptually: it shifts off n positional arguments from array, then figures out whether the rest of the array is a list of key-value pairs or a single argument (usually — but not necessarily — a hashref).

if you passed in any @names, those get used as keys into the hash, and the values at those keys get appended to any positional arguments and returned. 🌈

if you do not pass @names, you get a hashref back — or whatever the single argument was, like a tied object. your call, bestie.

⚠️ heads up: if the single argument cannot be dereferenced as a hashref, this can die. no attempt is made by this module to handle the exception. it just. perishes. 🙈 so know what you're passing, okay?

---

🌟 AUTHOR 🌟

Paul Driver <frodwith@cpan.org> — king behavior, ty for your service 🫡

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2011 by Paul Driver <frodwith@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, babe ✨ this was Kwargs(3pm) from the User Contributed Perl Documentation, generated under perl v5.32.0 and dated 2021-01-02 — stay hydrated, read your manpages, and remember: named arguments are good 💖💅🌸