X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDevel%2FDeclare.pm;h=bcaafb57782fb128043a3288de581a99fd3eea33;hb=48e462a5dd0ef3ea8737474654f033b8e971869b;hp=ea3b47e4bca75c79d8f3c3c9c2e0c7b38a39c727;hpb=4eeccf399bfe40aede5c2bc638eed248c96081f8;p=p5sagit%2FDevel-Declare.git

diff --git a/lib/Devel/Declare.pm b/lib/Devel/Declare.pm
index ea3b47e..bcaafb5 100644
--- a/lib/Devel/Declare.pm
+++ b/lib/Devel/Declare.pm
@@ -4,20 +4,21 @@ use strict;
 use warnings;
 use 5.008001;
 
-our $VERSION = '0.006008';
+our $VERSION = '0.006_021';
+
+bootstrap Devel::Declare;
+$VERSION =~ tr/_//d;
 
 use constant DECLARE_NAME => 1;
 use constant DECLARE_PROTO => 2;
 use constant DECLARE_NONE => 4;
 use constant DECLARE_PACKAGE => 8+1; # name implicit
 
-use vars qw(%declarators %declarator_handlers @ISA);
+our (%declarators, %declarator_handlers, @ISA);
 use base qw(DynaLoader);
 use Scalar::Util 'set_prototype';
 use B::Hooks::OP::Check 0.19;
 
-bootstrap Devel::Declare;
-
 @ISA = ();
 
 initialize();
@@ -287,7 +288,7 @@ sub linestr_callback {
 
 =head1 NAME
 
-Devel::Declare - Adding keywords to perl, in perl
+Devel::Declare - (DEPRECATED) Adding keywords to perl, in perl
 
 =head1 SYNOPSIS
 
@@ -308,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<Warning:> 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<Devel::CallParser>, L<Function::Parameters>, and L<Keyword::Simple> 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<TryCatch>, use L<Try::Tiny>
+
+=item *
+
+Instead of L<Method::Signatures>, use
+L<real subroutine signatures|perlsub/Signatures> (requires perl 5.22) or L<Moops>
+
+=back
+
 =head1 USAGE
 
 We'll demonstrate the usage of C<Devel::Declare> with a motivating example: a new
@@ -471,6 +502,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>