argra****@users*****
argra****@users*****
2011年 9月 10日 (土) 05:38:41 JST
Index: docs/modules/constant-1.17/constant.pod
diff -u /dev/null docs/modules/constant-1.17/constant.pod:1.1
--- /dev/null Sat Sep 10 05:38:41 2011
+++ docs/modules/constant-1.17/constant.pod Sat Sep 10 05:38:41 2011
@@ -0,0 +1,582 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+constant - Perl pragma to declare constants
+
+=end original
+
+constant - 定数を宣言するための Perl プラグマ
+
+=head1 SYNOPSIS
+
+ use constant PI => 4 * atan2(1, 1);
+ use constant DEBUG => 0;
+
+ print "Pi equals ", PI, "...\n" 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] ], ".\n";
+
+=head1 DESCRIPTION
+
+=begin original
+
+This pragma allows you to declare constants at compile-time.
+
+=end original
+
+このプラグマは、コンパイル時に定数を宣言できるようにします。
+
+=begin original
+
+When you declare a constant such as C<PI> 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 C<3.14195>.
+
+=end original
+
+上述の C<PI> のようにメソッドを使った定数を宣言すると、マシン毎に
+利用可能なだけの精度でスクリプトを実行します。
+さらに、プログラムが読みやすくなり、それどころか保守しやすく
+(そして正しく保守しやすく)なり、C<3.14195> と書いた一つの方程式に
+誰も気付かなかったために宇宙探査機を間違った星に送り込む可能性が
+遥かに小さくなります。
+
+=begin original
+
+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 C<if (CONSTANT)> block will be optimized
+away if the constant is false.
+
+=end original
+
+定数を式で使ったとき、Perl はこれをコンパイル時に値に置き換え、それから
+さらに式を最適化します。
+特に、C<if (CONSTANT)> ブロックにあるコードは、定数が偽の時には最適化されて
+なくなります。
+
+=head1 NOTES
+
+(注意)
+
+=begin original
+
+As with all C<use> 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 C<if ($foo)
+{ use constant ... }>).
+
+=end original
+
+As with all C<use> 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 C<if ($foo)
+{ use constant ... }>).
+(TBT)
+
+=begin original
+
+Constants defined using this module cannot be interpolated into
+strings like variables. However, concatenation works just fine:
+
+=end original
+
+Constants defined using this module cannot be interpolated into
+strings like variables. However, concatenation works just fine:
+(TBT)
+
+ print "Pi equals PI...\n"; # WRONG: does not expand "PI"
+ print "Pi equals ".PI."...\n"; # right
+
+=begin original
+
+Even though a reference may be declared as a constant, the reference may
+point to data which may be changed, as this code shows.
+
+=end original
+
+Even though a reference may be declared as a constant, the reference may
+point to data which may be changed, as this code shows.
+(TBT)
+
+ use constant ARRAY => [ 1,2,3,4 ];
+ print ARRAY->[1];
+ ARRAY->[1] = " be changed";
+ print ARRAY->[1];
+
+=begin original
+
+Dereferencing constant references incorrectly (such as using an array
+subscript on a constant hash reference, or vice versa) will be trapped at
+compile time.
+
+=end original
+
+Dereferencing constant references incorrectly (such as using an array
+subscript on a constant hash reference, or vice versa) will be trapped at
+compile time.
+(TBT)
+
+=begin original
+
+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 C<Some::Package::CONSTANT>. Constants may be exported by modules,
+and may also be called as either class or instance methods, that is,
+as C<< Some::Package->CONSTANT >> or as C<< $obj->CONSTANT >> where
+C<$obj> is an instance of C<Some::Package>. Subclasses may define
+their own constants to override those in their base class.
+
+=end original
+
+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 C<Some::Package::CONSTANT>. Constants may be exported by modules,
+and may also be called as either class or instance methods, that is,
+as C<< Some::Package->CONSTANT >> or as C<< $obj->CONSTANT >> where
+C<$obj> is an instance of C<Some::Package>. Subclasses may define
+their own constants to override those in their base class.
+(TBT)
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=head2 List constants
+
+(リスト定数)
+
+=begin original
+
+Constants may be lists of more (or less) than one value. A constant
+with no values evaluates to C<undef> in scalar context. Note that
+constants with more than one value do I<not> return their last value in
+scalar context as one might expect. They currently return the number
+of values, but B<this may change in the future>. Do not use constants
+with multiple values in scalar context.
+
+=end original
+
+Constants may be lists of more (or less) than one value. A constant
+with no values evaluates to C<undef> in scalar context. Note that
+constants with more than one value do I<not> return their last value in
+scalar context as one might expect. They currently return the number
+of values, but B<this may change in the future>. Do not use constants
+with multiple values in scalar context.
+(TBT)
+
+=begin original
+
+B<NOTE:> This implies that the expression defining the value of a
+constant is evaluated in list context. This may produce surprises:
+
+=end original
+
+B<NOTE:> This implies that the expression defining the value of a
+constant is evaluated in list context. This may produce surprises:
+(TBT)
+
+ use constant TIMESTAMP => localtime; # WRONG!
+ use constant TIMESTAMP => scalar localtime; # right
+
+=begin original
+
+The first line above defines C<TIMESTAMP> as a 9-element list, as
+returned by C<localtime()> in list context. To set it to the string
+returned by C<localtime()> in scalar context, an explicit C<scalar>
+keyword is required.
+
+=end original
+
+The first line above defines C<TIMESTAMP> as a 9-element list, as
+returned by C<localtime()> in list context. To set it to the string
+returned by C<localtime()> in scalar context, an explicit C<scalar>
+keyword is required.
+(TBT)
+
+=begin original
+
+List constants are lists, not arrays. To index or slice them, they
+must be placed in parentheses.
+
+=end original
+
+List constants are lists, not arrays. To index or slice them, they
+must be placed in parentheses.
+(TBT)
+
+ my @workdays = WEEKDAYS[1 .. 5]; # WRONG!
+ my @workdays = (WEEKDAYS)[1 .. 5]; # right
+
+=head2 Defining multiple constants at once
+
+(一度に複数の定数を定義する)
+
+=begin original
+
+Instead of writing multiple C<use constant> 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.
+
+=end original
+
+Instead of writing multiple C<use constant> 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.
+(TBT)
+
+ use constant {
+ FOO => "A single value",
+ BAR => "This", "won't", "work!", # Error!
+ };
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=begin original
+
+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 I<after> the C<use> statement is finished.
+
+=end original
+
+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 I<after> the C<use> statement is finished.
+(TBT)
+
+ use constant {
+ BITMASK => 0xAFBAEBA8,
+ NEGMASK => ~BITMASK, # Error!
+ };
+
+=head2 Magic constants
+
+(マジック定数)
+
+=begin original
+
+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.)
+
+=end original
+
+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.)
+(TBT)
+
+ use constant E2BIG => ($! = 7);
+ print E2BIG, "\n"; # something like "Arg list too long"
+ print 0+E2BIG, "\n"; # "7"
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=head1 TECHNICAL NOTES
+
+(技術的な注意)
+
+=begin original
+
+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
+L<perlsub/"Constant Functions"> for details about how and when this
+happens.
+
+=end original
+
+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
+L<perlsub/"Constant Functions"> for details about how and when this
+happens.
+(TBT)
+
+=begin original
+
+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 C<%constant::declared>. If the given
+constant name does not include a package name, the current package is
+used.
+
+=end original
+
+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 C<%constant::declared>. If the given
+constant name does not include a package name, the current package is
+used.
+(TBT)
+
+ sub declared ($) {
+ use constant 1.01; # don't omit this!
+ my $name = shift;
+ $name =~ s/^::/main::/;
+ my $pkg = caller;
+ my $full_name = $name =~ /::/ ? $name : "${pkg}::$name";
+ $constant::declared{$full_name};
+ }
+
+=head1 CAVEATS
+
+(警告)
+
+=begin original
+
+In the current version of Perl, list constants are not inlined
+and some symbols may be redefined without generating a warning.
+
+=end original
+
+In the current version of Perl, list constants are not inlined
+and some symbols may be redefined without generating a warning.
+(TBT)
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=begin original
+
+A constant with a name in the list C<STDIN STDOUT STDERR ARGV ARGVOUT
+ENV INC SIG> is not allowed anywhere but in package C<main::>, for
+technical reasons.
+
+=end original
+
+A constant with a name in the list C<STDIN STDOUT STDERR ARGV ARGVOUT
+ENV INC SIG> is not allowed anywhere but in package C<main::>, for
+technical reasons.
+(TBT)
+
+=begin original
+
+Unlike constants in some languages, these cannot be overridden
+on the command line or via environment variables.
+
+=end original
+
+Unlike constants in some languages, these cannot be overridden
+on the command line or via environment variables.
+(TBT)
+
+=begin original
+
+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 C<$hash{CONSTANT}> because C<CONSTANT> will
+be interpreted as a string. Use C<$hash{CONSTANT()}> or
+C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from
+kicking in. Similarly, since the C<< => >> operator quotes a bareword
+immediately to its left, you have to say C<< CONSTANT() => 'value' >>
+(or simply use a comma in place of the big arrow) instead of
+C<< CONSTANT => 'value' >>.
+
+=end original
+
+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 C<$hash{CONSTANT}> because C<CONSTANT> will
+be interpreted as a string. Use C<$hash{CONSTANT()}> or
+C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from
+kicking in. Similarly, since the C<< => >> operator quotes a bareword
+immediately to its left, you have to say C<< CONSTANT() => 'value' >>
+(or simply use a comma in place of the big arrow) instead of
+C<< CONSTANT => 'value' >>.
+(TBT)
+
+=head1 SEE ALSO
+
+=begin original
+
+L<Readonly> - Facility for creating read-only scalars, arrays, hashes.
+
+=end original
+
+L<Readonly> - 読み込み専用のスカラ、配列、ハッシュを作る機能。
+
+=begin original
+
+L<Const> - Facility for creating read-only variables. Similar to C<Readonly>,
+but uses C<SvREADONLY> instead of C<tie>.
+
+=end original
+
+L<Const> - 読み込み専用の変数を作る機能。
+C<Readonly> と似ていますが、C<tie> ではなく C<SvREADONLY> を使います。
+
+=begin original
+
+L<Attribute::Constant> - Make read-only variables via attribute
+
+=end original
+
+L<Attribute::Constant> - 属性経由で読み込み専用変数を作る。
+
+=begin original
+
+L<Scalar::Readonly> - Perl extension to the C<SvREADONLY> scalar flag
+
+=end original
+
+L<Scalar::Readonly> - C<SvREADONLY> スカラフラグのための Perl エクステンション
+
+=begin original
+
+L<Hash::Util> - A selection of general-utility hash subroutines (mostly
+to lock/unlock keys and values)
+
+=end original
+
+L<Hash::Util> - 汎用ハッシュサブルーチンの集合 (ほとんどはキーと値を
+ロック/アンロックするもの)
+
+=head1 BUGS
+
+=begin original
+
+Please report any bugs or feature requests via the perlbug(1) utility.
+
+=end original
+
+バグや機能追加リクエストは perlbug(1) ユーティリティを使って送って下さい。
+
+=head1 AUTHORS
+
+=begin original
+
+Tom Phoenix, E<lt>F<rootb****@redca*****>E<gt>, with help from
+many other folks.
+
+=end original
+
+Tom Phoenix, E<lt>F<rootb****@redca*****>E<gt>, with help from
+many other folks.
+(TBT)
+
+=begin original
+
+Multiple constant declarations at once added by Casey West,
+E<lt>F<casey****@geekn*****>E<gt>.
+
+=end original
+
+Multiple constant declarations at once added by Casey West,
+E<lt>F<casey****@geekn*****>E<gt>.
+(TBT)
+
+=begin original
+
+Documentation mostly rewritten by Ilmari Karonen,
+E<lt>F<perl****@itz*****>E<gt>.
+
+=end original
+
+Documentation mostly rewritten by Ilmari Karonen,
+E<lt>F<perl****@itz*****>E<gt>.
+(TBT)
+
+=begin original
+
+This program is maintained by the Perl 5 Porters.
+The CPAN distribution is maintained by SE<eacute>bastien Aperghis-Tramoni
+E<lt>F<sebas****@aperg*****>E<gt>.
+
+=end original
+
+This program is maintained by the Perl 5 Porters.
+The CPAN distribution is maintained by SE<eacute>bastien Aperghis-Tramoni
+E<lt>F<sebas****@aperg*****>E<gt>.
+(TBT)
+
+=head1 COPYRIGHT & LICENSE
+
+Copyright (C) 1997, 1999 Tom Phoenix
+
+This module is free software; you can redistribute it or modify it
+under the same terms as Perl itself.
+
+=cut
+