Commit | Line | Data |
54310121 |
1 | package constant; |
2 | |
3 | $VERSION = '1.00'; |
4 | |
5 | =head1 NAME |
6 | |
7 | constant - Perl pragma to declare constants |
8 | |
9 | =head1 SYNOPSIS |
10 | |
11 | use constant BUFFER_SIZE => 4096; |
12 | use constant ONE_YEAR => 365.2425 * 24 * 60 * 60; |
13 | use constant PI => 4 * atan2 1, 1; |
14 | use constant DEBUGGING => 0; |
15 | use constant ORACLE => 'oracle@cs.indiana.edu'; |
16 | use constant USERNAME => scalar getpwuid($<); |
17 | use constant USERINFO => getpwuid($<); |
18 | |
19 | sub deg2rad { PI * $_[0] / 180 } |
20 | |
21 | print "This line does nothing" unless DEBUGGING; |
22 | |
779c5bc9 |
23 | # references can be declared constant |
24 | use constant CHASH => { foo => 42 }; |
25 | use constant CARRAY => [ 1,2,3,4 ]; |
26 | use constant CPSEUDOHASH => [ { foo => 1}, 42 ]; |
27 | use constant CCODE => sub { "bite $_[0]\n" }; |
28 | |
29 | print CHASH->{foo}; |
30 | print CARRAY->[$i]; |
31 | print CPSEUDOHASH->{foo}; |
32 | print CCODE->("me"); |
33 | print CHASH->[10]; # compile-time error |
34 | |
54310121 |
35 | =head1 DESCRIPTION |
36 | |
37 | This will declare a symbol to be a constant with the given scalar |
38 | or list value. |
39 | |
40 | When you declare a constant such as C<PI> using the method shown |
41 | above, each machine your script runs upon can have as many digits |
42 | of accuracy as it can use. Also, your program will be easier to |
43 | read, more likely to be maintained (and maintained correctly), and |
44 | far less likely to send a space probe to the wrong planet because |
45 | nobody noticed the one equation in which you wrote C<3.14195>. |
46 | |
47 | =head1 NOTES |
48 | |
49 | The value or values are evaluated in a list context. You may override |
50 | this with C<scalar> as shown above. |
51 | |
52 | These constants do not directly interpolate into double-quotish |
53 | strings, although you may do so indirectly. (See L<perlref> for |
54 | details about how this works.) |
55 | |
56 | print "The value of PI is @{[ PI ]}.\n"; |
57 | |
58 | List constants are returned as lists, not as arrays. |
59 | |
60 | $homedir = USERINFO[7]; # WRONG |
61 | $homedir = (USERINFO)[7]; # Right |
62 | |
63 | The use of all caps for constant names is merely a convention, |
64 | although it is recommended in order to make constants stand out |
65 | and to help avoid collisions with other barewords, keywords, and |
66 | subroutine names. Constant names must begin with a letter. |
67 | |
68 | Constant symbols are package scoped (rather than block scoped, as |
69 | C<use strict> is). That is, you can refer to a constant from package |
70 | Other as C<Other::CONST>. |
71 | |
72 | As with all C<use> directives, defining a constant happens at |
73 | compile time. Thus, it's probably not correct to put a constant |
74 | declaration inside of a conditional statement (like C<if ($foo) |
75 | { use constant ... }>). |
76 | |
77 | Omitting the value for a symbol gives it the value of C<undef> in |
78 | a scalar context or the empty list, C<()>, in a list context. This |
79 | isn't so nice as it may sound, though, because in this case you |
80 | must either quote the symbol name, or use a big arrow, (C<=E<gt>>), |
81 | with nothing to point to. It is probably best to declare these |
82 | explicitly. |
83 | |
84 | use constant UNICORNS => (); |
85 | use constant LOGFILE => undef; |
86 | |
87 | The result from evaluating a list constant in a scalar context is |
88 | not documented, and is B<not> guaranteed to be any particular value |
89 | in the future. In particular, you should not rely upon it being |
90 | the number of elements in the list, especially since it is not |
91 | B<necessarily> that value in the current implementation. |
92 | |
93 | Magical values, tied values, and references can be made into |
94 | constants at compile time, allowing for way cool stuff like this. |
7e5dee47 |
95 | (These error numbers aren't totally portable, alas.) |
54310121 |
96 | |
97 | use constant E2BIG => ($! = 7); |
98 | print E2BIG, "\n"; # something like "Arg list too long" |
99 | print 0+E2BIG, "\n"; # "7" |
100 | |
779c5bc9 |
101 | Errors in dereferencing constant references are trapped at compile-time. |
102 | |
54310121 |
103 | =head1 TECHNICAL NOTE |
104 | |
105 | In the current implementation, scalar constants are actually |
106 | inlinable subroutines. As of version 5.004 of Perl, the appropriate |
107 | scalar constant is inserted directly in place of some subroutine |
108 | calls, thereby saving the overhead of a subroutine call. See |
109 | L<perlsub/"Constant Functions"> for details about how and when this |
110 | happens. |
111 | |
112 | =head1 BUGS |
113 | |
114 | In the current version of Perl, list constants are not inlined |
115 | and some symbols may be redefined without generating a warning. |
116 | |
117 | It is not possible to have a subroutine or keyword with the same |
118 | name as a constant. This is probably a Good Thing. |
119 | |
120 | Unlike constants in some languages, these cannot be overridden |
121 | on the command line or via environment variables. |
122 | |
a3cb178b |
123 | You can get into trouble if you use constants in a context which |
124 | automatically quotes barewords (as is true for any subroutine call). |
125 | For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will |
126 | be interpreted as a string. Use C<$hash{CONSTANT()}> or |
127 | C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from |
128 | kicking in. Similarly, since the C<=E<gt>> operator quotes a bareword |
129 | immediately to its left you have to say C<CONSTANT() =E<gt> 'value'> |
130 | instead of C<CONSTANT =E<gt> 'value'>. |
131 | |
54310121 |
132 | =head1 AUTHOR |
133 | |
134 | Tom Phoenix, E<lt>F<rootbeer@teleport.com>E<gt>, with help from |
135 | many other folks. |
136 | |
137 | =head1 COPYRIGHT |
138 | |
139 | Copyright (C) 1997, Tom Phoenix |
140 | |
141 | This module is free software; you can redistribute it or modify it |
142 | under the same terms as Perl itself. |
143 | |
144 | =cut |
145 | |
146 | use strict; |
147 | use Carp; |
148 | use vars qw($VERSION); |
149 | |
150 | #======================================================================= |
151 | |
152 | # Some of this stuff didn't work in version 5.003, alas. |
7e5dee47 |
153 | require 5.003_96; |
54310121 |
154 | |
155 | #======================================================================= |
156 | # import() - import symbols into user's namespace |
157 | # |
158 | # What we actually do is define a function in the caller's namespace |
159 | # which returns the value. The function we create will normally |
160 | # be inlined as a constant, thereby avoiding further sub calling |
161 | # overhead. |
162 | #======================================================================= |
163 | sub import { |
164 | my $class = shift; |
165 | my $name = shift or return; # Ignore 'use constant;' |
166 | croak qq{Can't define "$name" as constant} . |
167 | qq{ (name contains invalid characters or is empty)} |
168 | unless $name =~ /^[^\W_0-9]\w*$/; |
169 | |
170 | my $pkg = caller; |
171 | { |
172 | no strict 'refs'; |
173 | if (@_ == 1) { |
174 | my $scalar = $_[0]; |
175 | *{"${pkg}::$name"} = sub () { $scalar }; |
176 | } elsif (@_) { |
177 | my @list = @_; |
178 | *{"${pkg}::$name"} = sub () { @list }; |
179 | } else { |
180 | *{"${pkg}::$name"} = sub () { }; |
181 | } |
182 | } |
183 | |
184 | } |
185 | |
186 | 1; |