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