X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDevel%2FDeclare.pm;h=20372a9e2da33fbc72fbf79a8587091db8197273;hb=1adc7e7cd9698280d2288b79f9cb28dfaeda3786;hp=ec79d0128a7d3850649156e308771c26aac1c9ec;hpb=1795217cf8c82770d98159af3d315d0f56e15d34;p=p5sagit%2FDevel-Declare.git diff --git a/lib/Devel/Declare.pm b/lib/Devel/Declare.pm index ec79d01..20372a9 100644 --- a/lib/Devel/Declare.pm +++ b/lib/Devel/Declare.pm @@ -1,10 +1,11 @@ package Devel::Declare; +# ABSTRACT: (DEPRECATED) Adding keywords to perl, in perl use strict; use warnings; use 5.008001; -our $VERSION = '0.003005'; +our $VERSION = '0.006019'; use constant DECLARE_NAME => 1; use constant DECLARE_PROTO => 2; @@ -14,12 +15,14 @@ use constant DECLARE_PACKAGE => 8+1; # name implicit use vars qw(%declarators %declarator_handlers @ISA); use base qw(DynaLoader); use Scalar::Util 'set_prototype'; -use B::Hooks::OP::Check; +use B::Hooks::OP::Check 0.19; bootstrap Devel::Declare; @ISA = (); +initialize(); + sub import { my ($class, %args) = @_; my $target = caller; @@ -306,6 +309,36 @@ over Perl's parser, allowing the creation of new syntax. This document describes how to create a simple declarator. +=head1 WARNING + +=for comment mst wrote this warning for MooseX::Declare, and ether adapted it for here: + +B Devel::Declare is a giant bag of crack +originally implemented by mst with the goal of upsetting the perl core +developers so much by its very existence that they implemented proper +keyword handling in the core. + +As of perl5 version 14, this goal has been achieved, and modules such +as L, L, and L provide +mechanisms to mangle perl syntax that don't require hallucinogenic +drugs to interpret the error messages they produce. + +If you are using something that uses Devel::Declare, please for the love +of kittens use something else: + +=over 4 + +=item * + +Instead of L, use L + +=item * + +Instead of L, use +L (requires perl 5.22) or L + +=back + =head1 USAGE We'll demonstrate the usage of C with a motivating example: a new @@ -469,6 +502,10 @@ This builtin returns the full text of the current line of the source document. =head4 C This builtin sets the full text of the current line of the source document. +Beware that injecting a newline into the middle of the line is likely +to fail in surprising ways. Generally, Perl's parser can rely on the +`current line' actually being only a single line. Use other kinds of +whitespace instead, in the code that you inject. =head3 C @@ -513,8 +550,25 @@ things like C). Also it Does The Right Thing with nested delimiters (like C). -It returns the length of the expression matched. Use C to -get the actual matched text. +It returns the effective length of the expression matched. Really, what +it returns is the difference in position between where the string started, +within the buffer, and where it finished. If the string extended across +multiple lines then the contents of the buffer may have been completely +replaced by the new lines, so this position difference is not the same +thing as the actual length of the expression matched. However, because +moving backward in the buffer causes problems, the function arranges +for the effective length to always be positive, padding the start of +the buffer if necessary. + +Use C to get the actual matched text, the content of +the string. Because of the behaviour around multiline strings, you +can't reliably get this from the buffer. In fact, after the function +returns, you can't rely on any content of the buffer preceding the end +of the string. + +If the string being scanned is not well formed (has no closing delimiter), +C returns C. In this case you cannot rely on the +contents of the buffer. =head4 C @@ -580,10 +634,9 @@ These will then get rewritten as where 'method' is a subroutine that takes a code block. Spot the problem? The first one doesn't have a semicolon at the end of it! Unlike 'sub' which is a builtin, this is just a normal statement, so we need to terminate it. -Luckily, using the bastard spawn of L and some hints hash -hackery, we can do this! +Luckily, using C, we can do this! - use Scope::Guard; + use B::Hooks::EndOfScope; We'll add this to what gets 'injected' at the beginning of the method source. @@ -591,18 +644,17 @@ We'll add this to what gets 'injected' at the beginning of the method source. return ' BEGIN { MethodHandlers::inject_scope }; '; } -So at the beginning of every method, we assing a callback that will get invoked +So at the beginning of every method, we are passing a callback that will get invoked at the I of the method's compilation... i.e. exactly then the closing C<'}'> is compiled. sub inject_scope { - $^H |= 0x120000; - $^H{DD_METHODHANDLERS} = Scope::Guard->new(sub { + on_scope_end { my $linestr = Devel::Declare::get_linestr; my $offset = Devel::Declare::get_linestr_offset; substr($linestr, $offset, 0) = ';'; Devel::Declare::set_linestr($linestr); - }); + }; } =head2 Shadowing each method. @@ -651,19 +703,28 @@ L. =head1 AUTHORS -Matt S Trout - - original author +Matt S Trout - Emst@shadowcat.co.ukE - original author Company: http://www.shadowcat.co.uk/ Blog: http://chainsawblues.vox.com/ Florian Ragwitz Erafl@debian.orgE - maintainer -osfameron Eosfameron@cpan.org - first draft of documentation +osfameron Eosfameron@cpan.orgE - first draft of documentation -=head1 LICENSE +=head1 COPYRIGHT AND LICENSE This library is free software under the same terms as perl itself +Copyright (c) 2007, 2008, 2009 Matt S Trout + +Copyright (c) 2008, 2009 Florian Ragwitz + +stolen_chunk_of_toke.c based on toke.c from the perl core, which is + +Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, by Larry Wall and others + =cut 1;