nailed "our" declarations, and better warnings on duplicate

[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 4e38db2..d730b43 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2788,6 +2788,34 @@ 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.)
 
+An C<our> declaration declares a global variable that will be visible
+across its entire lexical scope, even across package boundaries.  The
+package in which the variable is entered is determined at the point
+of the declaration, not at the point of use.  This means the following
+behavior holds:
+
+    package Foo;
+    our $bar;          # declares $Foo::bar for rest of lexical scope
+    $bar = 20;
+
+    package Bar;
+    print $bar;                # prints 20
+
+Multiple C<our> declarations in the same lexical scope are allowed
+if they are in different packages.  If they happened to be in the same
+package, Perl will emit warnings if you have asked for them.
+
+    use warnings;
+    package Foo;
+    our $bar;          # declares $Foo::bar for rest of lexical scope
+    $bar = 20;
+
+    package Bar;
+    our $bar = 30;     # declares $Bar::bar for rest of lexical scope
+    print $bar;                # prints 30
+
+    our $bar;          # emits warning
+
 =item pack TEMPLATE,LIST
 
 Takes a LIST of values and converts it into a string using the rules