Re: [PATCH 5.005_61] "our" declarations

	Message-Id: <199909250459.VAA27506@kiev.wall.org>

p4raw-id: //depot/perl@4227

10 files changed, 43 insertions, 34 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 551f0590aa..ec41894048 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1840,8 +1840,8 @@ have a name with which they can be found.
 
 (W) Typographical errors often show up as unique variable names.
 If you had a good reason for having a unique name, then just mention
-it again somehow to suppress the message.  The C<use vars> pragma is
-provided for just this purpose.
+it again somehow to suppress the message.  The C<our> declaration is
+provided for this purpose.
 
 =item Negative length
 
diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index db5aab0052..3ea173688f 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -656,7 +656,7 @@ with L<perlfunc/my> whenever possible.
  #persistent.pl
 
  use strict;
- use vars '%Cache';
+ our %Cache;
  use Symbol qw(delete_package);
 
  sub valid_package_name {
diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod
index d2e83be460..26f7a693f3 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -53,7 +53,7 @@ Have you used C<-w>?  It enables warnings for dubious practices.
 Have you tried C<use strict>?  It prevents you from using symbolic
 references, makes you predeclare any subroutines that you call as bare
 words, and (probably most importantly) forces you to predeclare your
-variables with C<my> or C<use vars>.
+variables with C<my> or C<our> or C<use vars>.
 
 Did you check the returns of each and every system call?  The operating
 system (and thus Perl) tells you whether they worked or not, and if not
diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod
index 070d9653d4..72f4bb74ab 100644
--- a/pod/perlfaq7.pod
+++ b/pod/perlfaq7.pod
@@ -171,7 +171,7 @@ own module.  Make sure to change the names appropriately.
 
     BEGIN {
 	use Exporter   ();
-	use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+	our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
 
 	## set the version for version checking; uncomment to use
 	## $VERSION     = 1.00;
@@ -188,10 +188,11 @@ own module.  Make sure to change the names appropriately.
 	# as well as any optionally exported functions
 	@EXPORT_OK   = qw($Var1 %Hashit);
     }
-    use vars      @EXPORT_OK;
+    our @EXPORT_OK;
 
     # non-exported package globals go here
-    use vars      qw( @more $stuff );
+    our @more;
+    our $stuff;
 
     # initialize package globals, first exported ones
     $Var1   = '';
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 237a38ddf8..82c052148b 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2700,6 +2700,18 @@ Returns the numeric (ASCII or Unicode) value of the first character of EXPR.  If
 EXPR is omitted, uses C<$_>.  For the reverse, see L</chr>.
 See L<utf8> for more about Unicode.
 
+=item our EXPR
+
+An C<our> declares the listed variables to be valid globals within
+the enclosing block, file, or C<eval>.  That is, it has the same
+scoping rules as a "my" declaration, but does not create a local
+variable.  If more than one value is listed, the list must be placed
+in parentheses.  The C<our> declaration has no semantic effect unless
+"use strict vars" is in effect, in which case it lets you use the
+declared global variable without qualifying it with a package name.
+(But only within the lexical scope of the C<our> declaration.  In this
+it differs from "use vars", which is package scoped.)
+
 =item pack TEMPLATE,LIST
 
 Takes a list of values and packs it into a binary structure,
diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 0031d6e0e6..fc81fdfaae 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -279,7 +279,7 @@ create a file called F<Some/Module.pm> and start with this template:
 
     BEGIN {
         use Exporter   ();
-        use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+        our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
 
         # set the version for version checking
         $VERSION     = 1.00;
@@ -294,10 +294,11 @@ create a file called F<Some/Module.pm> and start with this template:
         # as well as any optionally exported functions
         @EXPORT_OK   = qw($Var1 %Hashit &func3);
     }
-    use vars      @EXPORT_OK;
+    our @EXPORT_OK;
 
     # non-exported package globals go here
-    use vars      qw(@more $stuff);
+    our @more;
+    our $stuff;
 
     # initialize package globals, first exported ones
     $Var1   = '';
diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod
index bfc5223819..99d31bd6e1 100644
--- a/pod/perlmodlib.pod
+++ b/pod/perlmodlib.pod
@@ -36,7 +36,7 @@ which lasts until the end of that BLOCK.
 
 Some pragmas are lexically scoped--typically those that affect the
 C<$^H> hints variable.  Others affect the current package instead,
-like C<use vars> and C<use subs>, whic allow you to predeclare a
+like C<use vars> and C<use subs>, which allow you to predeclare a
 variables or subroutines within a particular I<file> rather than
 just a block.  Such declarations are effective for the entire file
 for which they were declared.  You cannot rescind them with C<no
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 2beb3dea55..4abdc39529 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -353,7 +353,7 @@ which are always global, if you say
 
 then any variable mentioned from there to the end of the enclosing
 block must either refer to a lexical variable, be predeclared via
-C<use vars>, or else must be fully qualified with the package name.
+C<our> or C<use vars>, or else must be fully qualified with the package name.
 A compilation error results otherwise.  An inner block may countermand
 this with C<no strict 'vars'>.
 
diff --git a/pod/perltoot.pod b/pod/perltoot.pod
index 89e5cbe993..3062f5924d 100644
--- a/pod/perltoot.pod
+++ b/pod/perltoot.pod
@@ -1124,8 +1124,7 @@ it happens when you say
 If you wanted to add version checking to your Person class explained
 above, just add this to Person.pm:
 
-    use vars qw($VERSION);
-    $VERSION = '1.1';
+    our $VERSION = '1.1';
 
 and then in Employee.pm could you can say
 
@@ -1363,7 +1362,7 @@ constructor will look like when taking this approach:
 
     package Person;
     use Carp;
-    use vars qw($AUTOLOAD);  # it's a package global
+    our $AUTOLOAD;  # it's a package global
 
     my %fields = (
 	name        => undef,
@@ -1433,8 +1432,7 @@ Here's how to be careful:
     package Employee;
     use Person;
     use strict;
-    use vars qw(@ISA);
-    @ISA = qw(Person);
+    our @ISA = qw(Person);
 
     my %fields = (
 	id          => undef,
@@ -1560,16 +1558,15 @@ Here's the whole implementation:
 
     BEGIN {
 	use Exporter   ();
-	use vars       qw(@EXPORT @EXPORT_OK %EXPORT_TAGS);
-	@EXPORT      = qw(gethostbyname gethostbyaddr gethost);
-	@EXPORT_OK   = qw(
-			   $h_name         @h_aliases
-			   $h_addrtype     $h_length
-			   @h_addr_list    $h_addr
-		       );
-	%EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
+	our @EXPORT      = qw(gethostbyname gethostbyaddr gethost);
+	our @EXPORT_OK   = qw(
+			       $h_name         @h_aliases
+			       $h_addrtype     $h_length
+			       @h_addr_list    $h_addr
+			   );
+	our %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
     }
-    use vars      @EXPORT_OK;
+    our @EXPORT_OK;
 
     # Class::Struct forbids use of @ISA
     sub import { goto &Exporter::import }
@@ -1661,7 +1658,7 @@ update value fields in the hash.  Convenient, eh?
     }
 
     use Alias qw(attr);
-    use vars qw($NAME $AGE $PEERS);
+    our ($NAME, $AGE, $PEERS);
 
     sub name {
 	my $self = attr shift;
@@ -1692,7 +1689,7 @@ update value fields in the hash.  Convenient, eh?
         return ++$AGE;
     }
 
-The need for the C<use vars> declaration is because what Alias does
+The need for the C<our> declaration is because what Alias does
 is play with package globals with the same name as the fields.  To use
 globals while C<use strict> is in effect, you have to predeclare them.
 These package variables are localized to the block enclosing the attr()
diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod
index 4200140833..632f417496 100644
--- a/pod/perlxstut.pod
+++ b/pod/perlxstut.pod
@@ -92,19 +92,18 @@ The file Mytest.pm should start with something like this:
 	package Mytest;
 
 	use strict;
-	use vars qw($VERSION @ISA @EXPORT);
 
 	require Exporter;
 	require DynaLoader;
 
-	@ISA = qw(Exporter DynaLoader);
+	our @ISA = qw(Exporter DynaLoader);
 	# Items to export into callers namespace by default. Note: do not export
 	# names by default without a very good reason. Use EXPORT_OK instead.
 	# Do not simply export all your public functions/methods/constants.
-	@EXPORT = qw(
+	our @EXPORT = qw(
 
 	);
-	$VERSION = '0.01';
+	our $VERSION = '0.01';
 
 	bootstrap Mytest $VERSION;
 
@@ -563,8 +562,7 @@ the following three lines:
 	mylib/mylib.h
 
 To keep our namespace nice and unpolluted, edit the .pm file and change
-the variable C<@EXPORT> to C<@EXPORT_OK> (there are two: one in the line
-beginning "use vars" and one setting the array itself).  Finally, in the
+the variable C<@EXPORT> to C<@EXPORT_OK>.  Finally, in the
 .xs file, edit the #include line to read:
 
 	#include "mylib/mylib.h"