(tl)perl 5.18.2 for windows from siep

git-svn-id: svn://tug.org/texlive/trunk@33648 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 65 insertions, 23 deletions

diff --git a/Master/tlpkg/tlperl/lib/Scalar/Util.pm b/Master/tlpkg/tlperl/lib/Scalar/Util.pm
index ab97fe5446b..da229893495 100644
--- a/Master/tlpkg/tlperl/lib/Scalar/Util.pm
+++ b/Master/tlpkg/tlperl/lib/Scalar/Util.pm
@@ -11,8 +11,22 @@ require Exporter;
 require List::Util; # List::Util loads the XS
 
 our @ISA       = qw(Exporter);
-our @EXPORT_OK = qw(blessed dualvar reftype weaken isweak tainted readonly openhandle refaddr isvstring looks_like_number set_prototype);
-our $VERSION    = "1.25";
+our @EXPORT_OK = qw(
+  blessed
+  dualvar
+  isdual
+  isvstring
+  isweak
+  looks_like_number
+  openhandle
+  readonly
+  refaddr
+  reftype
+  set_prototype
+  tainted
+  weaken
+);
+our $VERSION    = "1.27";
 $VERSION   = eval $VERSION;
 
 our @EXPORT_FAIL;
@@ -51,8 +65,9 @@ Scalar::Util - A selection of general-utility scalar subroutines
 
 =head1 SYNOPSIS
 
-    use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
-                        weaken isvstring looks_like_number set_prototype);
+    use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
+                        tainted weaken isweak isvstring looks_like_number
+                        set_prototype);
                         # and other useful utils appearing below
 
 =head1 DESCRIPTION
@@ -90,27 +105,40 @@ value STRING in a string context.
     $num = $foo + 2;                    # 12
     $str = $foo . " world";             # Hello world
 
-=item isvstring EXPR
+=item isdual EXPR
 
-If EXPR is a scalar which was coded as a vstring the result is true.
+If EXPR is a scalar that is a dualvar, the result is true.
 
-    $vs   = v49.46.48;
-    $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
-    printf($fmt,$vs);
+    $foo = dualvar 86, "Nix";
+    $dual = isdual($foo);               # true
 
-=item isweak EXPR
+Note that a scalar can be made to have both string and numeric content
+through numeric operations:
 
-If EXPR is a scalar which is a weak reference the result is true.
+    $foo = "10";
+    $dual = isdual($foo);               # false
+    $bar = $foo + 0;
+    $dual = isdual($foo);               # true
 
-    $ref  = \$foo;
-    $weak = isweak($ref);               # false
-    weaken($ref);
-    $weak = isweak($ref);               # true
+Note that although C<$!> appears to be dual-valued variable, it is
+actually implemented using a tied scalar:
 
-B<NOTE>: Copying a weak reference creates a normal, strong, reference.
+    $! = 1;
+    print("$!\n");                      # "Operation not permitted"
+    $dual = isdual($!);                 # false
 
-    $copy = $ref;
-    $weak = isweak($copy);              # false
+You can capture its numeric and string content using:
+
+    $err = dualvar $!, $!;
+    $dual = isdual($err);               # true
+
+=item isvstring EXPR
+
+If EXPR is a scalar which was coded as a vstring the result is true.
+
+    $vs   = v49.46.48;
+    $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
+    printf($fmt,$vs);
 
 =item looks_like_number EXPR
 
@@ -122,11 +150,11 @@ L<perlapi/looks_like_number>.
 Returns FH if FH may be used as a filehandle and is open, or FH is a tied
 handle. Otherwise C<undef> is returned.
 
-    $fh = openhandle(*STDIN);		# \*STDIN
-    $fh = openhandle(\*STDIN);		# \*STDIN
-    $fh = openhandle(*NOTOPEN);		# undef
-    $fh = openhandle("scalar");		# undef
-    
+    $fh = openhandle(*STDIN);           # \*STDIN
+    $fh = openhandle(\*STDIN);          # \*STDIN
+    $fh = openhandle(*NOTOPEN);         # undef
+    $fh = openhandle("scalar");         # undef
+
 =item readonly SCALAR
 
 Returns true if SCALAR is readonly.
@@ -209,6 +237,20 @@ references to objects will be strong, causing the remaining objects to never
 be destroyed because there is now always a strong reference to them in the
 @object array.
 
+=item isweak EXPR
+
+If EXPR is a scalar which is a weak reference the result is true.
+
+    $ref  = \$foo;
+    $weak = isweak($ref);               # false
+    weaken($ref);
+    $weak = isweak($ref);               # true
+
+B<NOTE>: Copying a weak reference creates a normal, strong, reference.
+
+    $copy = $ref;
+    $weak = isweak($copy);              # false
+
 =back
 
 =head1 DIAGNOSTICS