diff options
Diffstat (limited to 'lib/Parse/Keyword.pm')
-rw-r--r-- | lib/Parse/Keyword.pm | 97 |
1 files changed, 81 insertions, 16 deletions
diff --git a/lib/Parse/Keyword.pm b/lib/Parse/Keyword.pm index 7b2f72c..afb2079 100644 --- a/lib/Parse/Keyword.pm +++ b/lib/Parse/Keyword.pm @@ -14,36 +14,99 @@ XSLoader::load( =head1 SYNOPSIS + use Parse::Keyword { try => \&try_parser }; + + sub try { + my ($try, $catch) = @_; + &Try::Tiny::try($try, ($catch ? (&Try::Tiny::catch($catch)) : ())); + } + + sub try_parser { + lex_read_space; + die "syntax error" unless lex_peek eq '{'; + my $try = parse_block; + lex_read_space; + + my $catch; + if (lex_peek(6) =~ /^catch\b/) { + lex_read(5); + lex_read_space; + die "syntax error" unless lex_peek eq '{'; + $catch = parse_block; + } + + return (sub { ($try, $catch) }, 1); + } + =head1 DESCRIPTION -=cut +This module allows you to write keyword-based syntax extensions without +requiring you to write any C code yourself. It is similar to L<Devel::Declare>, +except that it uses the Perl parser API introduced in Perl 5.14 in order to +allow you to parse parts of things using perl's own parser, rather than having +to fake it with balanced brace matching or other fragile things. -=func lex_peek +To use this module, you should pass a hashref to the C<use> statement. The keys +of this hashref are subroutines in the current package which should have +special parsing behavior attached to them, and the values are coderefs which +should be used to implement the custom parsing behavior. -=func lex_read +The parsing coderefs will be called when perl encounters a call to the keyword +that you attached custom parsing to. The current parser state will be directly +after parsing the keyword. Your parser function should return a coderef which, +when called at runtime, will produce the arguments to the function. In +addition, if your keyword should be parsed as a statement (for instance, if you +don't want to require a trailing semicolon), you can return a second, true +value. -=func lex_read_space +In order to actually handle the parsing itself, this module also exports +various parsing functions, which you can call. See below for details. + +=cut + +=func lex_peek($n) -=func lex_stuff +Returns a string consisting of the next C<$n> characters in the input (or next +one character, if C<$n> isn't given). This string may be shorter than C<$n> +characters if there are fewer than C<$n> characters remaining to read. The +current position in the buffer to be parsed is not moved. See L<< +perlapi/PL_parser->linestr >> and L<perlapi/lex_next_chunk> for more +information. -=func parse_block +=func lex_read($n) -=func parse_stmtseq +Moves the current position in the parsing buffer forward by C<$n> characters +(or one character, if C<$n> isn't given). See L<perlapi/lex_read_to> for more +details. -=func parse_fullstmt +=func lex_read_space -=func parse_barestmt +Moves the current position in the parsing buffer forward past any whitespace or +comments. See L<perlapi/lex_read_space> for more details. -=func parse_fullexpr +=func lex_stuff($str) -=func parse_listexpr +Inserts C<$str> into the current parsing buffer at the current location, so +that future calls to C<lex_peek> and such will see it. Note that this does not +move the current position in the parsing buffer, so multiple calls to +C<lex_stuff> at the same location will end up inserted into the buffer in +reverse order. See L<perlapi/lex_stuff_sv> for more information. -=func parse_termexpr +=func parse_block, parse_stmtseq, parse_fullstmt, parse_barestmt, +parse_fullexpr, parse_listexpr, parse_termexpr, parse_arithexpr -=func parse_arithexpr +These functions parse the specified amount of Perl code, and return a coderef +which will evaluate that code when executed. See L<perlapi/parse_block>, +L<perlapi/parse_stmtseq>, L<perlapi/parse_fullstmt>, L<perlapi/parse_barestmt>, +L<perlapi/parse_fullexpr>, L<parse_listexpr>, L<parse_termexpr>, and +L<perlapi/parse_arithexpr> for more details. =func compiling_package +Returns the name of the package that the keyword which is currently being +parsed was called in. This should be used instead of C<caller> if you want to +do something like install a subroutine in the calling package. + =cut sub import { @@ -84,17 +147,19 @@ sub import { =head1 BUGS -No known bugs. +This module inherits the limitation from L<Devel::CallParser> that custom +parsing is only triggered if the keyword is called by its unqualified name +(C<try>, not C<Try::try>, for instance). Please report any bugs to GitHub Issues at L<https://github.com/doy/parse-keyword/issues>. =head1 SEE ALSO -L<Devel::Declare> - L<Devel::CallParser> +L<Devel::Declare> + =head1 SUPPORT You can find this documentation for this module with the perldoc command. |