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); |
60f3865b |
13 | our @EXPORT_OK = qw(blessed dualvar reftype weaken isweak tainted readonly openhandle refaddr isvstring); |
ee4ffb48 |
14 | our $VERSION = $List::Util::VERSION; |
f4a2945e |
15 | |
c0f790df |
16 | sub openhandle ($) { |
17 | my $fh = shift; |
18 | my $rt = reftype($fh) || ''; |
19 | |
20 | return defined(fileno($fh)) ? $fh : undef |
21 | if $rt eq 'IO'; |
22 | |
23 | if (reftype(\$fh) eq 'GLOB') { # handle openhandle(*DATA) |
24 | $fh = \(my $tmp=$fh); |
25 | } |
26 | elsif ($rt ne 'GLOB') { |
27 | return undef; |
28 | } |
29 | |
30 | (tied(*$fh) or defined(fileno($fh))) |
31 | ? $fh : undef; |
32 | } |
33 | |
f4a2945e |
34 | 1; |
35 | |
36 | __END__ |
37 | |
38 | =head1 NAME |
39 | |
40 | Scalar::Util - A selection of general-utility scalar subroutines |
41 | |
42 | =head1 SYNOPSIS |
43 | |
60f3865b |
44 | use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted weaken); |
f4a2945e |
45 | |
46 | =head1 DESCRIPTION |
47 | |
48 | C<Scalar::Util> contains a selection of subroutines that people have |
49 | expressed would be nice to have in the perl core, but the usage would |
50 | not really be high enough to warrant the use of a keyword, and the size |
51 | so small such that being individual extensions would be wasteful. |
52 | |
53 | By default C<Scalar::Util> does not export any subroutines. The |
54 | subroutines defined are |
55 | |
56 | =over 4 |
57 | |
58 | =item blessed EXPR |
59 | |
60 | If EXPR evaluates to a blessed reference the name of the package |
61 | that it is blessed into is returned. Otherwise C<undef> is returned. |
62 | |
c29e891d |
63 | $scalar = "foo"; |
64 | $class = blessed $scalar; # undef |
65 | |
66 | $ref = []; |
67 | $class = blessed $ref; # undef |
68 | |
69 | $obj = bless [], "Foo"; |
70 | $class = blessed $obj; # "Foo" |
71 | |
f4a2945e |
72 | =item dualvar NUM, STRING |
73 | |
74 | Returns a scalar that has the value NUM in a numeric context and the |
75 | value STRING in a string context. |
76 | |
77 | $foo = dualvar 10, "Hello"; |
c29e891d |
78 | $num = $foo + 2; # 12 |
79 | $str = $foo . " world"; # Hello world |
f4a2945e |
80 | |
60f3865b |
81 | =item isvstring EXPR |
82 | |
83 | If EXPR is a scalar which was coded as a vstring the result is true. |
84 | |
85 | $vs = v49.46.48; |
86 | $fmt = isvstring($vs) ? "%vd" : "%s"; #true |
87 | printf($fmt,$vs); |
88 | |
f4a2945e |
89 | =item isweak EXPR |
90 | |
91 | If EXPR is a scalar which is a weak reference the result is true. |
92 | |
c29e891d |
93 | $ref = \$foo; |
94 | $weak = isweak($ref); # false |
95 | weaken($ref); |
96 | $weak = isweak($ref); # true |
97 | |
c0f790df |
98 | =item openhandle FH |
99 | |
100 | Returns FH if FH may be used as a filehandle and is open, or FH is a tied |
101 | handle. Otherwise C<undef> is returned. |
102 | |
103 | $fh = openhandle(*STDIN); # \*STDIN |
104 | $fh = openhandle(\*STDIN); # \*STDIN |
105 | $fh = openhandle(*NOTOPEN); # undef |
106 | $fh = openhandle("scalar"); # undef |
107 | |
ee4ffb48 |
108 | =item readonly SCALAR |
109 | |
110 | Returns true if SCALAR is readonly. |
111 | |
c29e891d |
112 | sub foo { readonly($_[0]) } |
113 | |
114 | $readonly = foo($bar); # false |
115 | $readonly = foo(0); # true |
116 | |
60f3865b |
117 | =item refaddr EXPR |
118 | |
119 | If EXPR evaluates to a reference the internal memory address of |
120 | the referenced value is returned. Otherwise C<undef> is returned. |
121 | |
122 | $addr = refaddr "string"; # undef |
123 | $addr = refaddr \$var; # eg 12345678 |
124 | $addr = refaddr []; # eg 23456784 |
125 | |
126 | $obj = bless {}, "Foo"; |
127 | $addr = refaddr $obj; # eg 88123488 |
128 | |
f4a2945e |
129 | =item reftype EXPR |
130 | |
131 | If EXPR evaluates to a reference the type of the variable referenced |
132 | is returned. Otherwise C<undef> is returned. |
133 | |
c29e891d |
134 | $type = reftype "string"; # undef |
135 | $type = reftype \$var; # SCALAR |
136 | $type = reftype []; # ARRAY |
137 | |
138 | $obj = bless {}, "Foo"; |
139 | $type = reftype $obj; # HASH |
140 | |
ee4ffb48 |
141 | =item tainted EXPR |
142 | |
143 | Return true if the result of EXPR is tainted |
144 | |
c29e891d |
145 | $taint = tainted("constant"); # false |
146 | $taint = tainted($ENV{PWD}); # true if running under -T |
147 | |
f4a2945e |
148 | =item weaken REF |
149 | |
150 | REF will be turned into a weak reference. This means that it will not |
151 | hold a reference count on the object it references. Also when the reference |
152 | count on that object reaches zero, REF will be set to undef. |
153 | |
154 | This is useful for keeping copies of references , but you don't want to |
022735b4 |
155 | prevent the object being DESTROY-ed at its usual time. |
f4a2945e |
156 | |
c29e891d |
157 | { |
158 | my $var; |
159 | $ref = \$var; |
160 | weaken($ref); # Make $ref a weak reference |
161 | } |
162 | # $ref is now undef |
163 | |
f4a2945e |
164 | =back |
165 | |
9c3c560b |
166 | =head1 KNOWN BUGS |
167 | |
168 | There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will |
169 | show up as tests 8 and 9 of dualvar.t failing |
170 | |
f4a2945e |
171 | =head1 COPYRIGHT |
172 | |
c29e891d |
173 | Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved. |
174 | This program is free software; you can redistribute it and/or modify it |
f4a2945e |
175 | under the same terms as Perl itself. |
176 | |
c29e891d |
177 | Except weaken and isweak which are |
f4a2945e |
178 | |
179 | Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved. |
180 | This program is free software; you can redistribute it and/or modify it |
181 | under the same terms as perl itself. |
182 | |
183 | =head1 BLATANT PLUG |
184 | |
185 | The weaken and isweak subroutines in this module and the patch to the core Perl |
186 | were written in connection with the APress book `Tuomas J. Lukka's Definitive |
187 | Guide to Object-Oriented Programming in Perl', to avoid explaining why certain |
188 | things would have to be done in cumbersome ways. |
189 | |
190 | =cut |