X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FDevel-Declare.git;a=blobdiff_plain;f=lib%2FDevel%2FDeclare.pm;h=6e5e1e1dcf28bb785496a1d0b0331927eff351da;hp=5f43590375478ed4c983128d1180dc5ab3c02e51;hb=b968549dde4c8a36fccca7aca22bcd092242b099;hpb=09addf7ad2f5b782a3e64d3b380cc3db10199fa2

diff --git a/lib/Devel/Declare.pm b/lib/Devel/Declare.pm
index 5f43590..6e5e1e1 100644
--- a/lib/Devel/Declare.pm
+++ b/lib/Devel/Declare.pm
@@ -1,10 +1,11 @@
 package Devel::Declare;
+# ABSTRACT: Adding keywords to perl, in perl
 
 use strict;
 use warnings;
 use 5.008001;
 
-our $VERSION = '0.005002';
+our $VERSION = '0.006015';
 
 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;
@@ -469,6 +472,10 @@ This builtin returns the full text of the current line of the source document.
 =head4 C<set_linestr>
 
 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<skipspace>
 
@@ -513,8 +520,25 @@ things like C<q(this is a quote)>).
 
 Also it Does The Right Thing with nested delimiters (like C<q(this (is (a) quote))>).
 
-It returns the length of the expression matched.  Use C<get_lex_stuff> 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<get_lex_stuff> 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<toke_scan_str> returns C<undef>.  In this case you cannot rely on the
+contents of the buffer.
 
 =head4 C<get_lex_stuff>