diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/constant.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/constant.3pm | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/constant.3pm b/upstream/mageia-cauldron/man3pm/constant.3pm new file mode 100644 index 00000000..9b947233 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/constant.3pm @@ -0,0 +1,312 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "constant 3pm" +.TH constant 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +constant \- Perl pragma to declare constants +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& use constant PI => 4 * atan2(1, 1); +\& use constant DEBUG => 0; +\& +\& print "Pi equals ", PI, "...\en" if DEBUG; +\& +\& use constant { +\& SEC => 0, +\& MIN => 1, +\& HOUR => 2, +\& MDAY => 3, +\& MON => 4, +\& YEAR => 5, +\& WDAY => 6, +\& YDAY => 7, +\& ISDST => 8, +\& }; +\& +\& use constant WEEKDAYS => qw( +\& Sunday Monday Tuesday Wednesday Thursday Friday Saturday +\& ); +\& +\& print "Today is ", (WEEKDAYS)[ (localtime)[WDAY] ], ".\en"; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This pragma allows you to declare constants at compile-time. +.PP +When you declare a constant such as \f(CW\*(C`PI\*(C'\fR using the method shown +above, each machine your script runs upon can have as many digits +of accuracy as it can use. Also, your program will be easier to +read, more likely to be maintained (and maintained correctly), and +far less likely to send a space probe to the wrong planet because +nobody noticed the one equation in which you wrote \f(CW3.14195\fR. +.PP +When a constant is used in an expression, Perl replaces it with its +value at compile time, and may then optimize the expression further. +In particular, any code in an \f(CW\*(C`if (CONSTANT)\*(C'\fR block will be optimized +away if the constant is false. +.SH NOTES +.IX Header "NOTES" +As with all \f(CW\*(C`use\*(C'\fR directives, defining a constant happens at +compile time. Thus, it's probably not correct to put a constant +declaration inside of a conditional statement (like \f(CW\*(C`if ($foo) +{ use constant ... }\*(C'\fR). +.PP +Constants defined using this module cannot be interpolated into +strings like variables. However, concatenation works just fine: +.PP +.Vb 2 +\& print "Pi equals PI...\en"; # WRONG: does not expand "PI" +\& print "Pi equals ".PI."...\en"; # right +.Ve +.PP +Even though a reference may be declared as a constant, the reference may +point to data which may be changed, as this code shows. +.PP +.Vb 4 +\& use constant ARRAY => [ 1,2,3,4 ]; +\& print ARRAY\->[1]; +\& ARRAY\->[1] = " be changed"; +\& print ARRAY\->[1]; +.Ve +.PP +Constants belong to the package they are defined in. To refer to a +constant defined in another package, specify the full package name, as +in \f(CW\*(C`Some::Package::CONSTANT\*(C'\fR. Constants may be exported by modules, +and may also be called as either class or instance methods, that is, +as \f(CW\*(C`Some::Package\->CONSTANT\*(C'\fR or as \f(CW\*(C`$obj\->CONSTANT\*(C'\fR where +\&\f(CW$obj\fR is an instance of \f(CW\*(C`Some::Package\*(C'\fR. Subclasses may define +their own constants to override those in their base class. +.PP +As of version 1.32 of this module, constants can be defined in packages +other than the caller, by including the package name in the name of the +constant: +.PP +.Vb 2 +\& use constant "OtherPackage::FWIBBLE" => 7865; +\& constant\->import("Other::FWOBBLE",$value); # dynamically at run time +.Ve +.PP +The use of all caps for constant names is merely a convention, +although it is recommended in order to make constants stand out +and to help avoid collisions with other barewords, keywords, and +subroutine names. Constant names must begin with a letter or +underscore. Names beginning with a double underscore are reserved. Some +poor choices for names will generate warnings, if warnings are enabled at +compile time. +.SS "List constants" +.IX Subsection "List constants" +Constants may be lists of more (or less) than one value. A constant +with no values evaluates to \f(CW\*(C`undef\*(C'\fR in scalar context. Note that +constants with more than one value do \fInot\fR return their last value in +scalar context as one might expect. They currently return the number +of values, but \fBthis may change in the future\fR. Do not use constants +with multiple values in scalar context. +.PP +\&\fBNOTE:\fR This implies that the expression defining the value of a +constant is evaluated in list context. This may produce surprises: +.PP +.Vb 2 +\& use constant TIMESTAMP => localtime; # WRONG! +\& use constant TIMESTAMP => scalar localtime; # right +.Ve +.PP +The first line above defines \f(CW\*(C`TIMESTAMP\*(C'\fR as a 9\-element list, as +returned by \f(CWlocaltime()\fR in list context. To set it to the string +returned by \f(CWlocaltime()\fR in scalar context, an explicit \f(CW\*(C`scalar\*(C'\fR +keyword is required. +.PP +List constants are lists, not arrays. To index or slice them, they +must be placed in parentheses. +.PP +.Vb 2 +\& my @workdays = WEEKDAYS[1 .. 5]; # WRONG! +\& my @workdays = (WEEKDAYS)[1 .. 5]; # right +.Ve +.SS "Defining multiple constants at once" +.IX Subsection "Defining multiple constants at once" +Instead of writing multiple \f(CW\*(C`use constant\*(C'\fR statements, you may define +multiple constants in a single statement by giving, instead of the +constant name, a reference to a hash where the keys are the names of +the constants to be defined. Obviously, all constants defined using +this method must have a single value. +.PP +.Vb 4 +\& use constant { +\& FOO => "A single value", +\& BAR => "This", "won\*(Aqt", "work!", # Error! +\& }; +.Ve +.PP +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. +.PP +When defining multiple constants, you cannot use the values of other +constants defined in the same declaration. This is because the +calling package doesn't know about any constant within that group +until \fIafter\fR the \f(CW\*(C`use\*(C'\fR statement is finished. +.PP +.Vb 4 +\& use constant { +\& BITMASK => 0xAFBAEBA8, +\& NEGMASK => ~BITMASK, # Error! +\& }; +.Ve +.SS "Magic constants" +.IX Subsection "Magic constants" +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.) +.PP +.Vb 3 +\& use constant E2BIG => ($! = 7); +\& print E2BIG, "\en"; # something like "Arg list too long" +\& print 0+E2BIG, "\en"; # "7" +.Ve +.PP +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. +.SH "TECHNICAL NOTES" +.IX Header "TECHNICAL NOTES" +In the current implementation, scalar constants are actually +inlinable subroutines. As of version 5.004 of Perl, the appropriate +scalar constant is inserted directly in place of some subroutine +calls, thereby saving the overhead of a subroutine call. See +"Constant Functions" in perlsub for details about how and when this +happens. +.PP +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 +this function to examine the hash \f(CW%constant::declared\fR. If the given +constant name does not include a package name, the current package is +used. +.PP +.Vb 8 +\& sub declared ($) { +\& use constant 1.01; # don\*(Aqt omit this! +\& my $name = shift; +\& $name =~ s/^::/main::/; +\& my $pkg = caller; +\& my $full_name = $name =~ /::/ ? $name : "${pkg}::$name"; +\& $constant::declared{$full_name}; +\& } +.Ve +.SH CAVEATS +.IX Header "CAVEATS" +List constants are not inlined unless you are using Perl v5.20 or higher. +In v5.20 or higher, they are still not read-only, but that may change in +future versions. +.PP +It is not possible to have a subroutine or a keyword with the same +name as a constant in the same package. This is probably a Good Thing. +.PP +A constant with a name in the list \f(CW\*(C`STDIN STDOUT STDERR ARGV ARGVOUT +ENV INC SIG\*(C'\fR is not allowed anywhere but in package \f(CW\*(C`main::\*(C'\fR, for +technical reasons. +.PP +Unlike constants in some languages, these cannot be overridden +on the command line or via environment variables. +.PP +You can get into trouble if you use constants in a context which +automatically quotes barewords (as is true for any subroutine call). +For example, you can't say \f(CW$hash{CONSTANT}\fR because \f(CW\*(C`CONSTANT\*(C'\fR will +be interpreted as a string. Use \f(CW$hash{CONSTANT()}\fR or +\&\f(CW$hash{+CONSTANT}\fR to prevent the bareword quoting mechanism from +kicking in. Similarly, since the \f(CW\*(C`=>\*(C'\fR operator quotes a bareword +immediately to its left, you have to say \f(CW\*(C`CONSTANT() => \*(Aqvalue\*(Aq\*(C'\fR +(or simply use a comma in place of the big arrow) instead of +\&\f(CW\*(C`CONSTANT => \*(Aqvalue\*(Aq\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Readonly \- Facility for creating read-only scalars, arrays, hashes. +.PP +Attribute::Constant \- Make read-only variables via attribute +.PP +Scalar::Readonly \- Perl extension to the \f(CW\*(C`SvREADONLY\*(C'\fR scalar flag +.PP +Hash::Util \- A selection of general-utility hash subroutines (mostly +to lock/unlock keys and values) +.SH BUGS +.IX Header "BUGS" +Please report any bugs or feature requests via the \fBperlbug\fR\|(1) utility. +.SH AUTHORS +.IX Header "AUTHORS" +Tom Phoenix, <\fIrootbeer@redcat.com\fR>, with help from +many other folks. +.PP +Multiple constant declarations at once added by Casey West, +<\fIcasey@geeknest.com\fR>. +.PP +Documentation mostly rewritten by Ilmari Karonen, +<\fIperl@itz.pp.sci.fi\fR>. +.PP +This program is maintained by the Perl 5 Porters. +The CPAN distribution is maintained by Sébastien Aperghis-Tramoni +<\fIsebastien@aperghis.net\fR>. +.SH "COPYRIGHT & LICENSE" +.IX Header "COPYRIGHT & LICENSE" +Copyright (C) 1997, 1999 Tom Phoenix +.PP +This module is free software; you can redistribute it or modify it +under the same terms as Perl itself. |