Integrate with Sarathy.

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

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index ed3de62..ddf64d0 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -512,8 +512,8 @@ With EXPR, it returns some extra information that the debugger uses to
 print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
 
-    ($package, $filename, $line, $subroutine,
-     $hasargs, $wantarray, $evaltext, $is_require) = caller($i);
+    ($package, $filename, $line, $subroutine, $hasargs,
+    $wantarray, $evaltext, $is_require, $hints) = caller($i);
 
 Here $subroutine may be C<"(eval)"> if the frame is not a subroutine
 call, but an C<eval>.  In such a case additional elements $evaltext and
@@ -522,7 +522,9 @@ C<require> or C<use> statement, $evaltext contains the text of the
 C<eval EXPR> statement.  In particular, for a C<eval BLOCK> statement,
 $filename is C<"(eval)">, but $evaltext is undefined.  (Note also that
 each C<use> statement creates a C<require> frame inside an C<eval EXPR>)
-frame.
+frame.  C<$hints> contains pragmatic hints that the caller was
+compiled with.  It currently only reflects the hint corresponding to
+C<use utf8>.
 
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
@@ -879,10 +881,17 @@ doesn't I<necessarily> indicate an exceptional condition: C<pop>
 returns C<undef> when its argument is an empty array, I<or> when the
 element to return happens to be C<undef>.
 
-You may also use C<defined> to check whether a subroutine exists, by
-saying C<defined &func> without parentheses.  On the other hand, use
-of C<defined> upon aggregates (hashes and arrays) is not guaranteed to
-produce intuitive results, and should probably be avoided.
+You may also use C<defined(&func)> to check whether subroutine C<&func>
+has ever been defined.  The return value is unaffected by any forward
+declarations of C<&foo>.
+
+Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
+used to report whether memory for that aggregate has ever been
+allocated.  This behavior may disappear in future versions of Perl.
+You should instead use a simple test for size:
+
+    if (@an_array) { print "has array elements\n" }
+    if (%a_hash)   { print "has hash members\n"   }
 
 When used on a hash element, it tells you whether the value is defined,
 not whether the key exists in the hash.  Use L</exists> for the latter
@@ -912,24 +921,6 @@ should use C<defined> only when you're questioning the integrity of what
 you're trying to do.  At other times, a simple comparison to C<0> or C<""> is
 what you want.
 
-Currently, using C<defined> on an entire array or hash reports whether
-memory for that aggregate has ever been allocated.  So an array you set
-to the empty list appears undefined initially, and one that once was full
-and that you then set to the empty list still appears defined.  You
-should instead use a simple test for size:
-
-    if (@an_array) { print "has array elements\n" }
-    if (%a_hash)   { print "has hash members\n"   }
-
-Using C<undef> on these, however, does clear their memory and then report
-them as not defined anymore, but you shouldn't do that unless you don't
-plan to use them again, because it saves time when you load them up
-again to have memory already ready to be filled.  The normal way to 
-free up space used by an aggregate is to assign the empty list.
-
-This counterintuitive behavior of C<defined> on aggregates may be
-changed, fixed, or broken in a future release of Perl.
-
 See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR
@@ -4769,6 +4760,7 @@ are also implemented this way.  Currently implemented pragmas are:
     use sigtrap qw(SEGV BUS);
     use strict  qw(subs vars refs);
     use subs    qw(afunc blurfl);
+    use warning qw(all);
 
 Some of these pseudo-modules import semantics into the current
 block scope (like C<strict> or C<integer>, unlike ordinary modules,
@@ -4780,6 +4772,7 @@ by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
 
     no integer;
     no strict 'refs';
+    no warning;
 
 If no C<unimport> method can be found the call fails with a fatal error.