.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers 3pm" .TH Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers 3pm "2015-08-11" "perl v5.20.2" "User Contributed Perl Documentation" .\" 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" Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers \- Don't use values that don't explain themselves. .SH "AFFILIATION" .IX Header "AFFILIATION" This Policy is part of the core Perl::Critic distribution. .SH "DESCRIPTION" .IX Header "DESCRIPTION" What is a \*(L"magic number\*(R"? A magic number is a number that appears in code without any explanation; e.g. \f(CW\*(C`$bank_account_balance *= 57.492;\*(C'\fR. You look at that number and have to wonder where that number came from. Since you don't understand the significance of the number, you don't understand the code. .PP In general, numeric literals other than \f(CW0\fR or \f(CW1\fR in should not be used. Use the constant pragma or the Readonly or Const::Fast modules to give a descriptive name to the number. .PP There are, of course, exceptions to when this rule should be applied. One good example is positioning of objects in some container like shapes on a blueprint or widgets in a user interface. In these cases, the significance of a number can readily be determined by context. .PP The maximum number of violations per document for this policy defaults to 10. .SS "Ways in which this module applies this rule." .IX Subsection "Ways in which this module applies this rule." By default, this rule is relaxed in that \f(CW2\fR is permitted to allow for common things like alternation, the \s-1STDERR\s0 file handle, etc.. .PP Numeric literals are allowed in \f(CW\*(C`use\*(C'\fR and \f(CW\*(C`require\*(C'\fR statements to allow for things like Perl version restrictions and Test::More plans. Declarations of \f(CW$VERSION\fR package variables are permitted. Use of \f(CW\*(C`Readonly\*(C'\fR, \f(CW\*(C`Readonly::Scalar\*(C'\fR, \&\f(CW\*(C`Readonly::Array\*(C'\fR, and \f(CW\*(C`Readonly::Hash\*(C'\fR from the Readonly module are obviously valid, but use of \&\f(CW\*(C`Readonly::Scalar1\*(C'\fR, \f(CW\*(C`Readonly::Array1\*(C'\fR, and \f(CW\*(C`Readonly::Hash1\*(C'\fR are specifically not supported. .PP Use of binary, exponential, hexadecimal, octal, and version numbers, even for \f(CW0\fR and \f(CW1\fR, outside of \f(CW\*(C`use\*(C'\fR/\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`Readonly\*(C'\fR statements aren't permitted (but you can change this). .PP There is a special exemption for accessing the last element of an array, i.e. \f(CW$x[\-1]\fR. .PP .Vb 10 \& $x = 0; # ok \& $x = 0.0; # ok \& $x = 1; # ok \& $x = 1.0; # ok \& $x = 1.5; # not ok \& $x = 0b0 # not ok \& $x = 0b1 # not ok \& $x = 0x00 # not ok \& $x = 0x01 # not ok \& $x = 000 # not ok \& $x = 001 # not ok \& $x = 0e1 # not ok \& $x = 1e1 # not ok \& \& $frobnication_factor = 42; # not ok \& use constant FROBNICATION_FACTOR => 42; # ok \& \& \& use 5.6.1; # ok \& use Test::More plan => 57; # ok \& plan tests => 39; # ok \& our $VERSION = 0.22; # ok \& \& \& $x = $y[\-1] # ok \& $x = $y[\-2] # not ok \& \& \& \& foreach my $solid (1..5) { # not ok \& ... \& } \& \& \& use Readonly; \& \& Readonly my $REGULAR_GEOMETRIC_SOLIDS => 5; \& \& foreach my $solid (1..$REGULAR_GEOMETRIC_SOLIDS) { #ok \& ... \& } .Ve .SH "CONFIGURATION" .IX Header "CONFIGURATION" This policy has four options: \f(CW\*(C`allowed_values\*(C'\fR, \f(CW\*(C`allowed_types\*(C'\fR, \&\f(CW\*(C`allow_to_the_right_of_a_fat_comma\*(C'\fR, and \f(CW\*(C`constant_creator_subroutines\*(C'\fR. .ie n .SS """allowed_values""" .el .SS "\f(CWallowed_values\fP" .IX Subsection "allowed_values" The \f(CW\*(C`allowed_values\*(C'\fR parameter is a whitespace delimited set of permitted number \fIvalues\fR; this does not affect the permitted formats for numbers. The defaults are equivalent to having the following in your \fI.perlcriticrc\fR: .PP .Vb 2 \& [ValuesAndExpressions::ProhibitMagicNumbers] \& allowed_values = 0 1 2 .Ve .PP Note that this policy forces the values \f(CW0\fR and \f(CW1\fR into the permitted values. Thus, specifying no values, .PP .Vb 1 \& allowed_values = .Ve .PP is the same as simply listing \f(CW0\fR and \f(CW1\fR: .PP .Vb 1 \& allowed_values = 0 1 .Ve .PP The special \f(CW\*(C`all_integers\*(C'\fR value, not surprisingly, allows all integral values to pass, subject to the restrictions on number types. .PP Ranges can be specified as two (possibly fractional) numbers separated by two periods, optionally suffixed with an increment using the Perl 6 \&\f(CW\*(C`:by()\*(C'\fR syntax. E.g. .PP .Vb 1 \& allowed_values = 7..10 .Ve .PP will allow 0, 1, 7, 8, 9, and 10 as literal values. Using fractional values like so .PP .Vb 1 \& allowed_values = \-3.5..\-0.5:by(0.5) .Ve .PP will permit \-3.5, \-3, \-2.5, \-2, \-2.5, \-1, \-0.5, 0, and 1. Unsurprisingly, the increment defaults to 1, which means that .PP .Vb 1 \& allowed_values = \-3.5..\-0.5 .Ve .PP will make \-3.5, \-2.5, \-2.5, \-0.5, 0, and 1 valid. .PP Ranges are not lazy, i.e. you'd better have a lot of memory available if you use a range of \f(CW\*(C`1..1000:by(0.01)\*(C'\fR. Also remember that all of this is done using floating-point math, which means that \&\f(CW\*(C`1..10:by(0.3333)\*(C'\fR is probably not going to be very useful. .PP Specifying an upper limit that is less than the lower limit will result in no values being produced by that range. Negative increments are not permitted. .PP Multiple ranges are permitted. .PP To put this all together, the following is a valid, though not likely to be used, \fI.perlcriticrc\fR entry: .PP .Vb 2 \& [ValuesAndExpressions::ProhibitMagicNumbers] \& allowed_values = 3.1415269 82..103 \-507.4..57.8:by(0.2) all_integers .Ve .ie n .SS """allowed_types""" .el .SS "\f(CWallowed_types\fP" .IX Subsection "allowed_types" The \f(CW\*(C`allowed_types\*(C'\fR parameter is a whitespace delimited set of subclasses of PPI::Token::Number. .PP Decimal integers are always allowed. By default, floating-point numbers are also allowed. .PP For example, to allow hexadecimal literals, you could configure this policy like .PP .Vb 2 \& [ValuesAndExpressions::ProhibitMagicNumbers] \& allowed_types = Hex .Ve .PP but without specifying anything for \f(CW\*(C`allowed_values\*(C'\fR, the allowed hexadecimal literals will be \f(CW0x00\fR, \f(CW0x01\fR, and \f(CW0x02\fR. Note, also, as soon as you specify a value for this parameter, you must include \f(CW\*(C`Float\*(C'\fR in the list to continue to be able to use floating point literals. This effect can be used to restrict literals to only decimal integers: .PP .Vb 2 \& [ValuesAndExpressions::ProhibitMagicNumbers] \& allowed_types = .Ve .PP If you permit exponential notation, you automatically also allow floating point values because an exponential is a subclass of floating-point in \s-1PPI\s0. .ie n .SS """allow_to_the_right_of_a_fat_comma""" .el .SS "\f(CWallow_to_the_right_of_a_fat_comma\fP" .IX Subsection "allow_to_the_right_of_a_fat_comma" If this is set, you can put any number to the right of a fat comma. .PP .Vb 3 \& my %hash = ( a => 4512, b => 293 ); # ok \& my $hash_ref = { a => 4512, b => 293 }; # ok \& some_subroutine( a => 4512, b => 293 ); # ok .Ve .PP Currently, this only means \fIdirectly\fR to the right of the fat comma. By default, this value is \fItrue\fR. .ie n .SS """constant_creator_subroutines""" .el .SS "\f(CWconstant_creator_subroutines\fP" .IX Subsection "constant_creator_subroutines" This parameter allows you to specify the names of subroutines that create constants, in addition to \f(CW\*(C`Readonly\*(C'\fR, \f(CW\*(C`Const::Fast\*(C'\fR, and friends. For example, if you use a custom \f(CW\*(C`Const::Fast\*(C'\fR\-like module that supports a \&\f(CW\*(C`create_constant\*(C'\fR subroutine to create constants, you could add something like the following to your \fI.perlcriticrc\fR: .PP .Vb 2 \& [ValuesAndExpressions::ProhibitMagicNumbers] \& constant_creator_subroutines = create_constant .Ve .PP If you have more than one name to add, separate them by whitespace. .PP The subroutine name should appear exactly as it is in your code. For example, if your code does not import the creating subroutine subroutine, you would need to configure this policy as something like .PP .Vb 2 \& [ValuesAndExpressions::ProhibitMagicNumbers] \& constant_creator_subroutines = create_constant Constant::Create::create_constant .Ve .SH "BUGS" .IX Header "BUGS" There is currently no way to permit version numbers in regular code, even if you include them in the \f(CW\*(C`allowed_types\*(C'\fR. Some may actually consider this a feature. .SH "AUTHOR" .IX Header "AUTHOR" Elliot Shank \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2006\-2011 Elliot Shank. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the \s-1LICENSE\s0 file included with this module.