Keyword::Simple(3pm)

💖 Keyword::Simple 💖

okay bestie, gather round, because we're about to talk about Keyword::Simple — that's the Keyword::Simple(3pm) page, part of the User Contributed Perl Documentation, and it's literally about defining your own keywords in pure Perl. no XS, no C, no vibes-ruining compiler nonsense. just Perl. iconic.

---

✨ NAME ✨

Keyword::Simple — define new keywords in pure Perl 💅

---

🌸 SYNOPSIS 🌸

package Some::Module;

use Keyword::Simple;

sub import {
    # create keyword 'provided', expand it to 'if' at parse time
    Keyword::Simple::define 'provided', sub {
        my ($ref) = @_;
        substr($$ref, 0, 0) = 'if';  # inject 'if' at beginning of parse buffer
    };
}

sub unimport {
    # lexically disable keyword again
    Keyword::Simple::undefine 'provided';
}

'ok'

---

🦋 DESCRIPTION 🦋

⚠️ Warning: This module is still new and experimental. The API may change in future versions. The code may be buggy.

not me telling you the module is basically a baby 😭 but fr fr, it's experimental, the API might shift under your feet, and the code may be buggy. we said it, you heard it, moving on.

So here's the tea: this module lets you implement new keywords in pure Perl. To pull it off, you write a module and call Keyword::Simple::define inside your import method. Any keyword you define this way becomes available in the lexical scope that's currently being compiled. cute, right? scoped, local, no global chaos. periodt.

🎀 Functions 🎀

• Keyword::Simple::define — takes two arguments: the name of a keyword and a coderef. It injects the keyword into the lexical scope that's currently being compiled. For every single occurrence of that keyword, your coderef gets called with one argument: a reference to a scalar holding the rest of the source code (everything following the keyword). You can modify that scalar literally any way you like, and after your coderef returns, perl keeps parsing from that scalar as if its contents had been the real source code all along. the way that works?? sorcery. 🔥
• Keyword::Simple::undefine — takes one argument: the name of a keyword. It disables that keyword in the lexical scope that's currently being compiled. call this from your unimport method and boom, the no Foo; syntax just works. slay. ✨

---

💀 BUGS AND LIMITATIONS 💀

okay this is the part where we hold hands 🫶 because there are some things you need to know.

This module depends on the pluggable keyword API introduced in perl 5.12. Older versions of perl are not supported. if you're on ancient perl, this is not giving. 🙈

Every new keyword is actually a complete statement by itself. The parsing magic only happens afterwards. Which means the code in the SYNOPSIS is actually doing this:

provided ($foo > 2) {
  ...
}

# expands to

; if
($foo > 2) {
  ...
}

So: the ; is a no-op statement, the if was injected by the Perl code, and the rest of the file is unchanged. love that for us.

This also means your new keywords can only occur at the beginning of a statement, not embedded in an expression. no mid-expression jumpscares, bestie, sorry. 💅

Keywords in the replacement part of a s//.../e substitution aren't handled correctly and break parsing. that's not a vibe check, that's a genuine "don't do it" — it breaks. 😭

There are barely any tests. yeah. we said it. the test suite is running on hopes and dreams and a single sparkle emoji. ⭐

---

🌈 SUPPORT AND DOCUMENTATION 🌈

Once you've installed it, you can find the docs for this module with the perldoc command:

perldoc Keyword::Simple

You can also go hunting for information at:

https://metacpan.org/pod/Keyword::Simple

Wanna see a list of open bugs? They live here:

https://rt.cpan.org/Public/Dist/Display.html?Name=Keyword-Simple

And to report a brand-new bug, send an email to:

bug-Keyword-Simple [at] rt.cpan.org

---

👑 AUTHOR 👑

Lukas Mai, <l.mai at web.de> — the main character who built this whole thing. bow down. 🫶

---

💜 COPYRIGHT & LICENSE 💜

Copyright (C) 2012, 2013 Lukas Mai.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

---

and that's the whole page, bestie!! 🎀 it's perl v5.42.3, dated 2026-08-19, and it goes by Keyword::Simple(3pm). go forth and define keywords responsibly — you got this, iykyk 💖✨