.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Keyword::Simple 3pm"
.TH Keyword::Simple 3pm "2014-10-19" "perl v5.24.1" "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"
Keyword::Simple \- define new keywords in pure Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package Some::Module;
\& 
\& use Keyword::Simple;
\& 
\& sub import {
\&     # create keyword \*(Aqprovided\*(Aq, expand it to \*(Aqif\*(Aq at parse time
\&     Keyword::Simple::define \*(Aqprovided\*(Aq, sub {
\&         my ($ref) = @_;
\&         substr($$ref, 0, 0) = \*(Aqif\*(Aq;  # inject \*(Aqif\*(Aq at beginning of parse buffer
\&     };
\& }
\& 
\& sub unimport {
\&     # lexically disable keyword again
\&     Keyword::Simple::undefine \*(Aqprovided\*(Aq;
\& }
\&
\& \*(Aqok\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Warning: This module is still new and experimental. The \s-1API\s0 may change in
future versions. The code may be buggy.
.PP
This module lets you implement new keywords in pure Perl. To do this, you need
to write a module and call
\&\f(CW\*(C`Keyword::Simple::define\*(C'\fR in your \f(CW\*(C`import\*(C'\fR
method. Any keywords defined this way will be available in the lexical scope
that's currently being compiled.
.SS "Functions"
.IX Subsection "Functions"
.ie n .IP """Keyword::Simple::define""" 4
.el .IP "\f(CWKeyword::Simple::define\fR" 4
.IX Item "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).
.Sp
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.
.ie n .IP """Keyword::Simple::undefine""" 4
.el .IP "\f(CWKeyword::Simple::undefine\fR" 4
.IX Item "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 \f(CW\*(C`unimport\*(C'\fR
method to make the \f(CW\*(C`no Foo;\*(C'\fR syntax work.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
This module depends on the pluggable keyword
\&\s-1API\s0 introduced in perl 5.12. Older versions of perl are not supported.
.PP
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 \*(L"\s-1SYNOPSIS\*(R"\s0
actually does this:
.PP
.Vb 3
\&  provided ($foo > 2) {
\&    ...
\&  }
\&
\&  # expands to
\&
\&  ; if
\&  ($foo > 2) {
\&    ...
\&  }
.Ve
.PP
The \f(CW\*(C`;\*(C'\fR represents a no-op statement, the \f(CW\*(C`if\*(C'\fR was injected by the Perl code,
and the rest of the file is unchanged.
.PP
This also means your new keywords can only occur at the beginning of a
statement, not embedded in an expression.
.PP
There are barely any tests.
.SH "AUTHOR"
.IX Header "AUTHOR"
Lukas Mai, \f(CW\*(C`<l.mai at web.de>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2012, 2013 Lukas Mai.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.