develooper Front page | perl.perl5.porters | Postings from July 2001

[PATCH] fixes to constant.pm documentation

Thread Next
From:
Ilmari Karonen
Date:
July 25, 2001 15:54
Subject:
[PATCH] fixes to constant.pm documentation
Message ID:
Pine.SOL.3.96.1010724163055.6822A-100000@simpukka

Here's a patch that corrects some documentation bugs in constant.pm.

The only change I made to the code itself was to bump the version by
0.01 and to change the perl version requirement.  (Which might still be
too low, as I have no v5.6.0 installed to check it with.)

There is one part in the changes -- documenting the use of constants as
methods -- which could be potentially controversial, as the behavior it
documents could be considered an artifact of the current implementation.
However, it seems to me that this implementation is highly unlikely to
change in Perl 5, and that in any case this is a useful feature that
should be documented and retained even if the implementation did change.

(Note: Please Cc replies to me, I'm not currently subscribed to p5p.)


--- lib/constant.pm.orig	Tue Jul 24 15:36:26 2001
+++ lib/constant.pm	Tue Jul 24 16:41:24 2001
@@ -1,11 +1,11 @@
 package constant;
 
 use strict;
-use 5.005_64;
+use 5.006_00;
 use warnings::register;
 
 our($VERSION, %declared);
-$VERSION = '1.03';
+$VERSION = '1.04';
 
 #=======================================================================
 
@@ -158,8 +158,8 @@
 	PI		=> 4 * atan2( 1, 1 ),
 	DEBUGGING	=> 0,
 	ORACLE		=> 'oracle@cs.indiana.edu',
-	USERNAME	=> scalar getpwuid($<),
-	USERINFO	=> getpwuid($<),
+	USERNAME	=> scalar getpwuid($<),      # this works
+	USERINFO	=> getpwuid($<),             # THIS IS A BUG!
     };
 
 =head1 DESCRIPTION
@@ -200,7 +200,9 @@
 
 Constant symbols are package scoped (rather than block scoped, as
 C<use strict> is). That is, you can refer to a constant from package
-Other as C<Other::CONST>.
+Other as C<Other::CONST>.  You may also use constants as either class
+or object methods, ie. C<< Other->CONST() >> or C<< $obj->CONST() >>.
+Such constant methods will be inherited as usual.
 
 As with all C<use> directives, defining a constant happens at
 compile time. Thus, it's probably not correct to put a constant
@@ -218,39 +220,63 @@
     [...]
     use constant PERSON => { age => AGE }; # Right
 
-Omitting the value for a symbol gives it the value of C<undef> in
-a scalar context or the empty list, C<()>, in a list context. This
-isn't so nice as it may sound, though, because in this case you
-must either quote the symbol name, or use a big arrow, (C<=E<gt>>),
-with nothing to point to. It is also illegal to do when defining
-multiple constants at once, you must declare them explicitly.  It
-is probably best to declare these explicitly.
-
-    use constant UNICORNS	=> ();
-    use constant LOGFILE	=> undef;
-
-The result from evaluating a list constant in a scalar context is
-not documented, and is B<not> guaranteed to be any particular value
-in the future. In particular, you should not rely upon it being
-the number of elements in the list, especially since it is not
-B<necessarily> that value in the current implementation.
-
-Magical values, tied values, and references can be made into
-constants at compile time, allowing for way cool stuff like this.
-(These error numbers aren't totally portable, alas.)
+Giving an empty list, C<()>, as the value for a symbol makes it return
+C<undef> in scalar context and the empty list in list context.
+
+    use constant UNICORNS => ();
+
+    print "Impossible!\n"  if defined UNICORNS;    
+    my @unicorns = UNICORNS;  # there are no unicorns
+
+The same effect can be achieved by omitting the value and the big
+arrow entirely, but then the symbol name must be put in quotes.
+
+    use constant "UNICORNS";
+
+The result from evaluating a list constant with more than one element
+in a scalar context is not documented, and is B<not> guaranteed to be
+any particular value in the future. In particular, you should not rely
+upon it being the number of elements in the list, especially since it
+is not B<necessarily> that value in the current implementation.
+
+Magical values and references can be made into constants at compile
+time, allowing for way cool stuff like this.  (These error numbers
+aren't totally portable, alas.)
 
     use constant E2BIG => ($! = 7);
     print   E2BIG, "\n";	# something like "Arg list too long"
     print 0+E2BIG, "\n";	# "7"
 
+You can't produce a tied constant by giving a tied scalar as the
+value.  References to tied variables, however, can be used as
+constants without any problems.
+
 Dereferencing constant references incorrectly (such as using an array
 subscript on a constant hash reference, or vice versa) will be trapped at
 compile time.
 
-When declaring multiple constants, all constant values will be a scalar.
-This is because C<constant> can't guess the intent of the programmer
-correctly all the time since values must be expressed in scalar context
-within a hash ref.
+When declaring multiple constants, all constant values B<must be
+scalars>.  If you accidentally try to use a list with more (or less)
+than one value, every second value will be treated as a symbol name.
+
+    use constant {
+        EMPTY => (),                    # WRONG!
+        MANY => ("foo", "bar", "baz"),  # WRONG!
+    };
+
+This will get interpreted as below, which is probably not what you
+wanted.
+
+    use constant {
+        EMPTY => "MANY",  # oops.
+        foo => "bar",     # oops!
+        baz => undef,     # OOPS!
+    };
+
+This is a fundamental limitation of the way hashes are constructed in
+Perl.  The error messages produced when this happens will often be
+quite cryptic -- in the worst case there may be none at all, and
+you'll only later find that something is broken.
 
 In the rare case in which you need to discover at run time whether a
 particular constant has been declared via this module, you may use
@@ -316,6 +342,9 @@
 
 Multiple constant declarations at once added by Casey West,
 E<lt>F<casey@geeknest.com>E<gt>.
+
+Assorted documentation fixes by Ilmari Karonen,
+E<lt>F<perl@itz.pp.sci.fi>E<gt>.
 
 =head1 COPYRIGHT
 


Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About