1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
package builtin 0.001;
use strict;
use warnings;
# All code, including &import, is implemented by always-present functions in
# the perl interpreter itself.
# See also `builtin.c` in perl source
1;
__END__
=head1 NAME
builtin - Perl pragma to import built-in utility functions
=head1 SYNOPSIS
use builtin qw(
true false isbool
weaken unweaken isweak
blessed refaddr reftype
);
=head1 DESCRIPTION
Perl provides several utility functions in the C<builtin> package. These are
plain functions, and look and behave just like regular user-defined functions
do. They do not provide new syntax or require special parsing. These functions
are always present in the interpreter and can be called at any time by their
fully-qualified names. By default they are not available as short names, but
can be requested for convenience.
Individual named functions can be imported by listing them as import
parameters on the C<use> statement for this pragma.
The overall C<builtin> mechanism, as well as every individual function it
provides, are currently B<experimental>.
=head2 Lexical Import
This pragma module creates I<lexical> aliases in the currently-compiling scope
to these builtin functions. This is similar to the lexical effect of other
pragmas such as L<strict> and L<feature>.
sub classify
{
my $sv = shift;
use builtin 'isbool';
return isbool($sv) ? "boolean" : "not a boolean";
}
# the isbool() function is no longer visible here
# but may still be called by builtin::isbool()
Because these functions are imported lexically, rather than by package
symbols, the user does not need to take any special measures to ensure they
don't accidentally appear as object methods from a class.
package An::Object::Class {
use builtin 'true', 'false';
...
}
# does not appear as a method
An::Object::Class->true;
# Can't locate object method "true" via package "An::Object::Class"
# at ...
=head1 FUNCTIONS
=head2 true
$val = true;
Returns the boolean truth value. While any scalar value can be tested for
truth and most defined, non-empty and non-zero values are considered "true"
by perl, this one is special in that L</isbool> considers it to be a
distinguished boolean value.
This gives an equivalent value to expressions like C<!!1> or C<!0>.
=head2 false
$val = false;
Returns the boolean fiction value. While any non-true scalar value is
considered "false" by perl, this one is special in that L</isbool> considers
it to be a distinguished boolean value.
This gives an equivalent value to expressions like C<!!0> or C<!1>.
=head2 isbool
$bool = isbool($val);
Returns true when given a distinguished boolean value, or false if not. A
distinguished boolean value is the result of any boolean-returning builtin
function (such as C<true> or C<isbool> itself), boolean-returning operator
(such as the C<eq> or C<==> comparison tests or the C<!> negation operator),
or any variable containing one of these results.
=head2 weaken
weaken($ref);
Weakens a reference. A weakened reference does not contribute to the reference
count of its referent. If only weakened references to a referent remain, it
will be disposed of, and all remaining weak references to it will have their
value set to C<undef>.
=head2 unweaken
unweaken($ref);
Strengthens a reference, undoing the effects of a previous call to L</weaken>.
=head2 isweak
$bool = isweak($ref);
Returns true when given a weakened reference, or false if not a reference or
not weak.
=head2 blessed
$str = blessed($ref);
Returns the package name for an object reference, or C<undef> for a
non-reference or reference that is not an object.
=head2 refaddr
$num = refaddr($ref);
Returns the memory address for a reference, or C<undef> for a non-reference.
This value is not likely to be very useful for pure Perl code, but is handy as
a means to test for referential identity or uniqueness.
=head2 reftype
$str = reftype($ref);
Returns the basic container type of the referent of a reference, or C<undef>
for a non-reference. This is returned as a string in all-capitals, such as
C<ARRAY> for array references, or C<HASH> for hash references.
=head1 SEE ALSO
L<perlop>, L<perlfunc>, L<Scalar::Util>
=cut
|
