Commit | Line | Data |
f4a2945e |
1 | # Scalar::Util.pm |
2 | # |
c29e891d |
3 | # Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved. |
f4a2945e |
4 | # This program is free software; you can redistribute it and/or |
5 | # modify it under the same terms as Perl itself. |
6 | |
7 | package Scalar::Util; |
8 | |
9 | require Exporter; |
10 | require List::Util; # List::Util loads the XS |
11 | |
ee4ffb48 |
12 | our @ISA = qw(Exporter); |
13 | our @EXPORT_OK = qw(blessed dualvar reftype weaken isweak tainted readonly); |
14 | our $VERSION = $List::Util::VERSION; |
f4a2945e |
15 | |
f4a2945e |
16 | 1; |
17 | |
18 | __END__ |
19 | |
20 | =head1 NAME |
21 | |
22 | Scalar::Util - A selection of general-utility scalar subroutines |
23 | |
24 | =head1 SYNOPSIS |
25 | |
c29e891d |
26 | use Scalar::Util qw(blessed dualvar isweak readonly reftype tainted weaken); |
f4a2945e |
27 | |
28 | =head1 DESCRIPTION |
29 | |
30 | C<Scalar::Util> contains a selection of subroutines that people have |
31 | expressed would be nice to have in the perl core, but the usage would |
32 | not really be high enough to warrant the use of a keyword, and the size |
33 | so small such that being individual extensions would be wasteful. |
34 | |
35 | By default C<Scalar::Util> does not export any subroutines. The |
36 | subroutines defined are |
37 | |
38 | =over 4 |
39 | |
40 | =item blessed EXPR |
41 | |
42 | If EXPR evaluates to a blessed reference the name of the package |
43 | that it is blessed into is returned. Otherwise C<undef> is returned. |
44 | |
c29e891d |
45 | $scalar = "foo"; |
46 | $class = blessed $scalar; # undef |
47 | |
48 | $ref = []; |
49 | $class = blessed $ref; # undef |
50 | |
51 | $obj = bless [], "Foo"; |
52 | $class = blessed $obj; # "Foo" |
53 | |
f4a2945e |
54 | =item dualvar NUM, STRING |
55 | |
56 | Returns a scalar that has the value NUM in a numeric context and the |
57 | value STRING in a string context. |
58 | |
59 | $foo = dualvar 10, "Hello"; |
c29e891d |
60 | $num = $foo + 2; # 12 |
61 | $str = $foo . " world"; # Hello world |
f4a2945e |
62 | |
63 | =item isweak EXPR |
64 | |
65 | If EXPR is a scalar which is a weak reference the result is true. |
66 | |
c29e891d |
67 | $ref = \$foo; |
68 | $weak = isweak($ref); # false |
69 | weaken($ref); |
70 | $weak = isweak($ref); # true |
71 | |
ee4ffb48 |
72 | =item readonly SCALAR |
73 | |
74 | Returns true if SCALAR is readonly. |
75 | |
c29e891d |
76 | sub foo { readonly($_[0]) } |
77 | |
78 | $readonly = foo($bar); # false |
79 | $readonly = foo(0); # true |
80 | |
f4a2945e |
81 | =item reftype EXPR |
82 | |
83 | If EXPR evaluates to a reference the type of the variable referenced |
84 | is returned. Otherwise C<undef> is returned. |
85 | |
c29e891d |
86 | $type = reftype "string"; # undef |
87 | $type = reftype \$var; # SCALAR |
88 | $type = reftype []; # ARRAY |
89 | |
90 | $obj = bless {}, "Foo"; |
91 | $type = reftype $obj; # HASH |
92 | |
ee4ffb48 |
93 | =item tainted EXPR |
94 | |
95 | Return true if the result of EXPR is tainted |
96 | |
c29e891d |
97 | $taint = tainted("constant"); # false |
98 | $taint = tainted($ENV{PWD}); # true if running under -T |
99 | |
f4a2945e |
100 | =item weaken REF |
101 | |
102 | REF will be turned into a weak reference. This means that it will not |
103 | hold a reference count on the object it references. Also when the reference |
104 | count on that object reaches zero, REF will be set to undef. |
105 | |
106 | This is useful for keeping copies of references , but you don't want to |
022735b4 |
107 | prevent the object being DESTROY-ed at its usual time. |
f4a2945e |
108 | |
c29e891d |
109 | { |
110 | my $var; |
111 | $ref = \$var; |
112 | weaken($ref); # Make $ref a weak reference |
113 | } |
114 | # $ref is now undef |
115 | |
f4a2945e |
116 | =back |
117 | |
9c3c560b |
118 | =head1 KNOWN BUGS |
119 | |
120 | There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will |
121 | show up as tests 8 and 9 of dualvar.t failing |
122 | |
f4a2945e |
123 | =head1 COPYRIGHT |
124 | |
c29e891d |
125 | Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved. |
126 | This program is free software; you can redistribute it and/or modify it |
f4a2945e |
127 | under the same terms as Perl itself. |
128 | |
c29e891d |
129 | Except weaken and isweak which are |
f4a2945e |
130 | |
131 | Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved. |
132 | This program is free software; you can redistribute it and/or modify it |
133 | under the same terms as perl itself. |
134 | |
135 | =head1 BLATANT PLUG |
136 | |
137 | The weaken and isweak subroutines in this module and the patch to the core Perl |
138 | were written in connection with the APress book `Tuomas J. Lukka's Definitive |
139 | Guide to Object-Oriented Programming in Perl', to avoid explaining why certain |
140 | things would have to be done in cumbersome ways. |
141 | |
142 | =cut |