Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Keyword::Simple - define new keywords in pure Perl


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';



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

This module lets you implement new keywords in pure Perl. To do this, you need to write a module and call Keyword::Simple::define in your import method. Any keywords defined this way will be available in the lexical scope that's currently being compiled.


  • Keyword::Simple::define

    Takes two arguments, the name of a keyword and a coderef. Injects the keyword in the lexical scope currently being compiled. For every occurrence of the keyword, your coderef will be called with one argument: A reference to a scalar holding the rest of the source code (following the keyword).

    You can modify this scalar in any way you like and after your coderef returns, perl will continue parsing from that scalar as if its contents had been the real source code in the first place.

  • Keyword::Simple::undefine

    Takes one argument, the name of a keyword. Disables that keyword in the lexical scope that's currently being compiled. You can call this from your unimport method to make the no Foo; syntax work.


This module depends on the pluggable keyword API introduced in perl 5.12. Older versions of perl are not supported.

Every new keyword is actually a complete statement by itself. The parsing magic only happens afterwards. This means that e.g. the code in the "SYNOPSIS" actually does this:

provided ($foo > 2) {

# expands to

; if
($foo > 2) {

The ; represents a no-op statement, the if was injected by the Perl code, and the rest of the file is unchanged.

This also means your new keywords can only occur at the beginning of a statement, not embedded in an expression.

Keywords in the replacement part of a s//.../e substitution aren't handled correctly and break parsing.

There are barely any tests.


After installing, you can find documentation for this module with the perldoc command.

perldoc Keyword::Simple

You can also look for information at

To see a list of open bugs, visit

To report a new bug, send an email to bug-Keyword-Simple [at]


Lukas Mai, <l.mai at>


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 for more information.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.