P e r l d o c B r o w s e r
●
5 . 6 . 0
L a t e s t
5 . 4 0 . 0
5 . 3 8 . 2
5 . 3 8 . 1
5 . 3 8 . 0
5 . 3 6 . 3
5 . 3 6 . 2
5 . 3 6 . 1
5 . 3 6 . 0
5 . 3 4 . 3
5 . 3 4 . 2
5 . 3 4 . 1
5 . 3 4 . 0
5 . 3 2 . 1
5 . 3 2 . 0
5 . 3 0 . 3
5 . 3 0 . 2
5 . 3 0 . 1
5 . 3 0 . 0
5 . 2 8 . 3
5 . 2 8 . 2
5 . 2 8 . 1
5 . 2 8 . 0
5 . 2 6 . 3
5 . 2 6 . 2
5 . 2 6 . 1
5 . 2 6 . 0
5 . 2 4 . 4
5 . 2 4 . 3
5 . 2 4 . 2
5 . 2 4 . 1
5 . 2 4 . 0
5 . 2 2 . 4
5 . 2 2 . 3
5 . 2 2 . 2
5 . 2 2 . 1
5 . 2 2 . 0
5 . 2 0 . 3
5 . 2 0 . 2
5 . 2 0 . 1
5 . 2 0 . 0
5 . 1 8 . 4
5 . 1 8 . 3
5 . 1 8 . 2
5 . 1 8 . 1
5 . 1 8 . 0
5 . 1 6 . 3
5 . 1 6 . 2
5 . 1 6 . 1
5 . 1 6 . 0
5 . 1 4 . 4
5 . 1 4 . 3
5 . 1 4 . 2
5 . 1 4 . 1
5 . 1 4 . 0
5 . 1 2 . 5
5 . 1 2 . 4
5 . 1 2 . 3
5 . 1 2 . 2
5 . 1 2 . 1
5 . 1 2 . 0
5 . 1 0 . 1
5 . 1 0 . 0
5 . 8 . 9
5 . 8 . 8
5 . 8 . 7
5 . 8 . 6
5 . 8 . 5
5 . 8 . 4
5 . 8 . 3
5 . 8 . 2
5 . 8 . 1
5 . 8 . 0
5 . 6 . 2
5 . 6 . 1
5 . 6 . 0
5 . 0 0 5 _ 0 4
5 . 0 0 5 _ 0 3
5 . 0 0 5 _ 0 2
5 . 0 0 5 _ 0 1
5 . 0 0 5
●
D e v
b l e a d
5 . 4 1 . 2
5 . 4 1 . 1
5 . 4 0 . 0 - R C 2
5 . 4 0 . 0 - R C 1
5 . 3 9 . 1 0
5 . 3 9 . 9
5 . 3 9 . 8
5 . 3 9 . 6
5 . 3 9 . 5
5 . 3 9 . 4
5 . 3 9 . 3
5 . 3 9 . 2
5 . 3 9 . 1
5 . 3 7 . 1 1
5 . 3 7 . 1 0
5 . 3 7 . 9
5 . 3 7 . 8
5 . 3 7 . 7
5 . 3 7 . 6
5 . 3 7 . 5
5 . 3 7 . 4
5 . 3 7 . 3
5 . 3 7 . 2
5 . 3 7 . 1
5 . 3 7 . 0
●
D o c u m e n t a t i o n
P e r l
I n t r o
T u t o r i a l s
F A Q s
R e f e r e n c e
O p e r a t o r s
F u n c t i o n s
V a r i a b l e s
M o d u l e s
U t i l i t i e s
C o m m u n i t y
H i s t o r y
E x p a n d
p e r l l e x w a r n
( s o u r c e ,
C P A N )
Y o u a r e v i e w i n g t h e v e r s i o n o f t h i s d o c u m e n t a t i o n f r o m P e r l 5 . 6 . 0 .
V i e w t h e l a t e s t v e r s i o n
●
N A M E
●
D E S C R I P T I O N
●
D e f a u l t W a r n i n g s a n d O p t i o n a l W a r n i n g s
●
W h a t ' s w r o n g w i t h - w a n d $ ^ W
●
C o n t r o l l i n g W a r n i n g s f r o m t h e C o m m a n d L i n e
●
B a c k w a r d C o m p a t i b i l i t y
●
C a t e g o r y H i e r a r c h y
●
F a t a l W a r n i n g s
●
R e p o r t i n g W a r n i n g s f r o m a M o d u l e
●
T O D O
●
S E E A L S O
●
A U T H O R
# N A M E
p e r l l e x w a r n - P e r l L e x i c a l W a r n i n g s
# D E S C R I P T I O N
T h e u s e w a r n i n g s
p r a g m a i s a r e p l a c e m e n t f o r b o t h t h e c o m m a n d l i n e f l a g - w a n d t h e e q u i v a l e n t P e r l v a r i a b l e , $ ^ W
.
T h e p r a g m a w o r k s j u s t l i k e t h e e x i s t i n g " s t r i c t " p r a g m a . T h i s m e a n s t h a t t h e s c o p e o f t h e w a r n i n g p r a g m a i s l i m i t e d t o t h e e n c l o s i n g b l o c k . I t a l s o m e a n s t h a t t h a t t h e p r a g m a s e t t i n g w i l l n o t l e a k a c r o s s f i l e s ( v i a u s e
, r e q u
i r e
or do
) . T h i s a l l o w s a u t h o r s t o i n d e p e n d e n t l y d e f i n e t h e d e g r e e o f w a r n i n g c h e c k s t h a t w i l l b e a p p l i e d t o t h e i r m o d u l e .
B y d e f a u l t , o p t i o n a l w a r n i n g s a r e d i s a b l e d , s o a n y l e g a c y c o d e t h a t d o e s n ' t a t t e m p t t o c o n t r o l t h e w a r n i n g s w i l l w o r k u n c h a n g e d .
A l l w a r n i n g s a r e e n a b l e d i n a b l o c k b y e i t h e r o f t h e s e :
use warnings ;
use warnings 'all' ;
S i m i l a r l y a l l w a r n i n g s a r e d i s a b l e d i n a b l o c k b y e i t h e r o f t h e s e :
no warnings ;
no warnings 'all' ;
F o r e x a m p l e , c o n s i d e r t h e c o d e b e l o w :
use warnings ;
my $a ;
my $b ;
{
no warnings ;
$b = 2 if $a EQ 3 ;
}
$b = 1 if $a NE 3 ;
T h e c o d e i n t h e e n c l o s i n g b l o c k h a s w a r n i n g s e n a b l e d , b u t t h e i n n e r b l o c k h a s t h e m d i s a b l e d . I n t h i s c a s e t h a t m e a n s t h a t t h e u s e o f t h e EQ
o p e r a t o r w o n ' t t r i p a " U s e o f E Q i s d e p r e c a t e d "
w a r n i n g , b u t t h e u s e o f NE
w i l l p r o d u c e a " U s e o f N E i s d e p r e c a t e d "
w a r n i n g .
# D e f a u l t W a r n i n g s a n d O p t i o n a l W a r n i n g s
B e f o r e t h e i n t r o d u c t i o n o f l e x i c a l w a r n i n g s , P e r l h a d t w o c l a s s e s o f w a r n i n g s : m a n d a t o r y a n d o p t i o n a l .
A s i t s n a m e s u g g e s t s , i f y o u r c o d e t r i p p e d a m a n d a t o r y w a r n i n g , y o u w o u l d g e t a w a r n i n g w h e t h e r y o u w a n t e d i t o r n o t . F o r e x a m p l e , t h e c o d e b e l o w w o u l d a l w a y s p r o d u c e a n " i s n ' t n u m e r i c "
w a r n i n g a b o u t t h e " 2 : " .
my $a = "2:" + 3;
W i t h t h e i n t r o d u c t i o n o f l e x i c a l w a r n i n g s , m a n d a t o r y w a r n i n g s n o w b e c o m e d e f a u l t w a r n i n g s . T h e d i f f e r e n c e i s t h a t a l t h o u g h t h e p r e v i o u s l y m a n d a t o r y w a r n i n g s a r e s t i l l e n a b l e d b y d e f a u l t , t h e y c a n t h e n b e s u b s e q u e n t l y e n a b l e d o r d i s a b l e d w i t h t h e l e x i c a l w a r n i n g p r a g m a . F o r e x a m p l e , i n t h e c o d e b e l o w , a n " i s n ' t n u m e r i c "
w a r n i n g w i l l o n l y b e r e p o r t e d f o r t h e $ a
v a r i a b l e .
my $a = "2:" + 3;
no warnings ;
my $b = "2:" + 3;
N o t e t h a t n e i t h e r t h e - w f l a g o r t h e $ ^ W
c a n b e u s e d t o d i s a b l e / e n a b l e d e f a u l t w a r n i n g s . T h e y a r e s t i l l m a n d a t o r y i n t h i s c a s e .
# W h a t ' s w r o n g w i t h - w a n d $ ^ W
A l t h o u g h v e r y u s e f u l , t h e b i g p r o b l e m w i t h u s i n g - w o n t h e c o m m a n d l i n e t o e n a b l e w a r n i n g s i s t h a t i t i s a l l o r n o t h i n g . T a k e t h e t y p i c a l s c e n a r i o w h e n y o u a r e w r i t i n g a P e r l p r o g r a m . P a r t s o f t h e c o d e y o u w i l l w r i t e y o u r s e l f , b u t i t ' s v e r y l i k e l y t h a t y o u w i l l m a k e u s e o f p r e - w r i t t e n P e r l m o d u l e s . I f y o u u s e t h e - w f l a g i n t h i s c a s e , y o u e n d u p e n a b l i n g w a r n i n g s i n p i e c e s o f c o d e t h a t y o u h a v e n ' t w r i t t e n .
S i m i l a r l y , u s i n g $ ^ W
t o e i t h e r d i s a b l e o r e n a b l e b l o c k s o f c o d e i s f u n d a m e n t a l l y f l a w e d . F o r a s t a r t , s a y y o u w a n t t o d i s a b l e w a r n i n g s i n a b l o c k o f c o d e . Y o u m i g h t e x p e c t t h i s t o b e e n o u g h t o d o t h e t r i c k :
{
local ($^W) = 0 ;
my $a =+ 2 ;
my $b ; chop $b ;
}
W h e n t h i s c o d e i s r u n w i t h t h e - w f l a g , a w a r n i n g w i l l b e p r o d u c e d f o r t h e $ a
l i n e - - " R e v e r s e d
+ = o p e r a t o r "
.
T h e p r o b l e m i s t h a t P e r l h a s b o t h c o m p i l e - t i m e a n d r u n - t i m e w a r n i n g s . T o d i s a b l e c o m p i l e - t i m e w a r n i n g s y o u n e e d t o r e w r i t e t h e c o d e l i k e t h i s :
{
BEGIN { $^W = 0 }
my $a =+ 2 ;
my $b ; chop $b ;
}
T h e o t h e r b i g p r o b l e m w i t h $ ^ W
i s t h a t w a y y o u c a n i n a d v e r t e n t l y c h a n g e t h e w a r n i n g s e t t i n g i n u n e x p e c t e d p l a c e s i n y o u r c o d e . F o r e x a m p l e , w h e n t h e c o d e b e l o w i s r u n ( w i t h o u t t h e - w f l a g ) , t h e s e c o n d c a l l t o d o i t
w i l l t r i p a " U s e o f u n i n i t i a l i z e d v a l u e "
w a r n i n g , w h e r e a s t h e f i r s t w i l l n o t .
sub doit
{
my $b ; chop $b ;
}
doit() ;
{
local ($^W) = 1 ;
doit()
}
T h i s i s a s i d e - e f f e c t o f $ ^ W
b e i n g d y n a m i c a l l y s c o p e d .
L e x i c a l w a r n i n g s g e t a r o u n d t h e s e l i m i t a t i o n s b y a l l o w i n g f i n e r c o n t r o l o v e r w h e r e w a r n i n g s c a n o r c a n ' t b e t r i p p e d .
# C o n t r o l l i n g W a r n i n g s f r o m t h e C o m m a n d L i n e
T h e r e a r e t h r e e C o m m a n d L i n e f l a g s t h a t c a n b e u s e d t o c o n t r o l w h e n w a r n i n g s a r e ( o r a r e n ' t ) p r o d u c e d :
# - w
T h i s i s t h e e x i s t i n g f l a g . I f t h e l e x i c a l w a r n i n g s p r a g m a i s n o t u s e d i n a n y o f y o u c o d e , o r a n y o f t h e m o d u l e s t h a t y o u u s e , t h i s f l a g w i l l e n a b l e w a r n i n g s e v e r y w h e r e . S e e " B a c k w a r d C o m p a t i b i l i t y " f o r d e t a i l s o f h o w t h i s f l a g i n t e r a c t s w i t h l e x i c a l w a r n i n g s .
# - W
I f t h e - W f l a g i s u s e d o n t h e c o m m a n d l i n e , i t w i l l e n a b l e a l l w a r n i n g s t h r o u g h o u t t h e p r o g r a m r e g a r d l e s s o f w h e t h e r w a r n i n g s w e r e d i s a b l e d l o c a l l y u s i n g n
o w a r n i n g s
or $ ^ W = 0
. T h i s i n c l u d e s a l l f i l e s t h a t g e t i n c l u d e d v i a u s e
, r e q u i r e
or do
. T h i n k o f i t a s t h e P e r l e q u i v a l e n t o f t h e " l i n t " c o m m a n d .
# - X
D o e s t h e e x a c t o p p o s i t e t o t h e - W f l a g , i . e . i t d i s a b l e s a l l w a r n i n g s .
# B a c k w a r d C o m p a t i b i l i t y
I f y o u a r e u s e d w i t h w o r k i n g w i t h a v e r s i o n o f P e r l p r i o r t o t h e i n t r o d u c t i o n o f l e x i c a l l y s c o p e d w a r n i n g s , o r h a v e c o d e t h a t u s e s b o t h l e x i c a l w a r n i n g s a n d $ ^ W
, t h i s s e c t i o n w i l l d e s c r i b e h o w t h e y i n t e r a c t .
H o w L e x i c a l W a r n i n g s i n t e r a c t w i t h - w / $ ^ W
:
I f n o n e o f t h e t h r e e c o m m a n d l i n e f l a g s ( - w , - W or - X ) t h a t c o n t r o l w a r n i n g s i s u s e d a n d n e i t h e r $ ^ W
o r t h e w a r n i n g s
p r a g m a a r e u s e d , t h e n d e f a u l t w a r n i n g s w i l l b e e n a b l e d a n d o p t i o n a l w a r n i n g s d i s a b l e d . T h i s m e a n s t h a t l e g a c y c o d e t h a t d o e s n ' t a t t e m p t t o c o n t r o l t h e w a r n i n g s w i l l w o r k u n c h a n g e d .
T h e - w f l a g j u s t s e t s t h e g l o b a l $ ^ W
v a r i a b l e a s i n 5 . 0 0 5 - - t h i s m e a n s t h a t a n y l e g a c y c o d e t h a t c u r r e n t l y r e l i e s o n m a n i p u l a t i n g $ ^ W
t o c o n t r o l w a r n i n g b e h a v i o r w i l l s t i l l w o r k a s i s .
A p a r t f r o m n o w b e i n g a b o o l e a n , t h e $ ^ W
v a r i a b l e o p e r a t e s i n e x a c t l y t h e s a m e h o r r i b l e u n c o n t r o l l e d g l o b a l w a y , e x c e p t t h a t i t c a n n o t d i s a b l e / e n a b l e d e f a u l t w a r n i n g s .
I f a p i e c e o f c o d e i s u n d e r t h e c o n t r o l o f t h e w a r n i n g s
p r a g m a , b o t h t h e $ ^ W
v a r i a b l e a n d t h e - w f l a g w i l l b e i g n o r e d f o r t h e s c o p e o f t h e l e x i c a l w a r n i n g .
T h e o n l y w a y t o o v e r r i d e a l e x i c a l w a r n i n g s s e t t i n g i s w i t h t h e - W or - X c o m m a n d l i n e f l a g s .
T h e c o m b i n e d e f f e c t o f 3 & 4 i s t h a t i t w i l l w i l l a l l o w c o d e w h i c h u s e s t h e w a r n i n g s
p r a g m a t o c o n t r o l t h e w a r n i n g b e h a v i o r o f $ ^ W - t y p e c o d e ( u s i n g a l o c a l $ ^ W =
0
) i f i t r e a l l y w a n t s t o , b u t n o t v i c e - v e r s a .
# C a t e g o r y H i e r a r c h y
A h i e r a r c h y o f " c a t e g o r i e s " h a v e b e e n d e f i n e d t o a l l o w g r o u p s o f w a r n i n g s t o b e e n a b l e d / d i s a b l e d i n i s o l a t i o n .
T h e c u r r e n t h i e r a r c h y i s :
all -+
|
+- chmod
|
+- closure
|
+- exiting
|
+- glob
|
+- io -----------+
| |
| +- closed
| |
| +- exec
| |
| +- newline
| |
| +- pipe
| |
| +- unopened
|
+- misc
|
+- numeric
|
+- once
|
+- overflow
|
+- pack
|
+- portable
|
+- recursion
|
+- redefine
|
+- regexp
|
+- severe -------+
| |
| +- debugging
| |
| +- inplace
| |
| +- internal
| |
| +- malloc
|
+- signal
|
+- substr
|
+- syntax -------+
| |
| +- ambiguous
| |
| +- bareword
| |
| +- deprecated
| |
| +- digit
| |
| +- parenthesis
| |
| +- precedence
| |
| +- printf
| |
| +- prototype
| |
| +- qw
| |
| +- reserved
| |
| +- semicolon
|
+- taint
|
+- umask
|
+- uninitialized
|
+- unpack
|
+- untie
|
+- utf8
|
+- void
|
+- y2k
J u s t l i k e t h e " s t r i c t " p r a g m a a n y o f t h e s e c a t e g o r i e s c a n b e c o m b i n e d
use warnings qw(void redefine) ;
no warnings qw(io syntax untie) ;
A l s o l i k e t h e " s t r i c t " p r a g m a , i f t h e r e i s m o r e t h a n o n e i n s t a n c e o f t h e w a r n i n g s
p r a g m a i n a g i v e n s c o p e t h e c u m u l a t i v e e f f e c t i s a d d i t i v e .
use warnings qw(void) ; # only "void" warnings enabled
...
use warnings qw(io ) ; # only "void" & "io" warnings enabled
...
no warnings qw(void) ; # only "io" warnings enabled
T o d e t e r m i n e w h i c h c a t e g o r y a s p e c i f i c w a r n i n g h a s b e e n a s s i g n e d t o s e e p e r l d i a g .
# F a t a l W a r n i n g s
T h e p r e s e n c e o f t h e w o r d " F A T A L " i n t h e c a t e g o r y l i s t w i l l e s c a l a t e a n y w a r n i n g s d e t e c t e d f r o m t h e c a t e g o r i e s s p e c i f i e d i n t h e l e x i c a l s c o p e i n t o f a t a l e r r o r s . I n t h e c o d e b e l o w , t h e r e a r e 3 p l a c e s w h e r e a d e p r e c a t e d w a r n i n g w i l l b e d e t e c t e d , t h e m i d d l e o n e w i l l p r o d u c e a f a t a l e r r o r .
use warnings ;
$a = 1 if $a EQ $b ;
{
use warnings FATAL => qw(deprecated) ;
$a = 1 if $a EQ $b ;
}
$a = 1 if $a EQ $b ;
# R e p o r t i n g W a r n i n g s f r o m a M o d u l e
T h e w a r n i n g s
p r a g m a p r o v i d e s a n u m b e r o f f u n c t i o n s t h a t a r e u s e f u l f o r m o d u l e a u t h o r s . T h e s e a r e u s e d w h e n y o u w a n t t o r e p o r t a m o d u l e - s p e c i f i c w a r n i n g w h e n t h e c a l l i n g m o d u l e h a s e n a b l e d w a r n i n g s v i a t h e w a r n i n g s
p r a g m a .
C o n s i d e r t h e m o d u l e M y M o d : : A b c
b e l o w .
package MyMod::Abc;
use warnings::register;
sub open {
my $path = shift ;
if (warnings::enabled() && $path !~ m#^/#) {
warnings::warn("changing relative path to /tmp/");
$path = "/tmp/$path" ;
}
}
1 ;
T h e c a l l t o w a r n i n g s : : r e g i s t e r
w i l l c r e a t e a n e w w a r n i n g s c a t e g o r y c a l l e d " M y M o d : : a b c " , i . e . t h e n e w c a t e g o r y n a m e m a t c h e s t h e m o d u l e n a m e . T h e o p e n
f u n c t i o n i n t h e m o d u l e w i l l d i s p l a y a w a r n i n g m e s s a g e i f i t g e t s g i v e n a r e l a t i v e p a t h a s a p a r a m e t e r . T h i s w a r n i n g s w i l l o n l y b e d i s p l a y e d i f t h e c o d e t h a t u s e s M y M o d : : A b
c
h a s a c t u a l l y e n a b l e d t h e m w i t h t h e w a r n i n g s
p r a g m a l i k e b e l o w .
use MyMod::Abc;
use warnings 'MyMod::Abc';
...
abc::open("../fred.txt");
I t i s a l s o p o s s i b l e t o t e s t w h e t h e r t h e p r e - d e f i n e d w a r n i n g s c a t e g o r i e s a r e s e t i n t h e c a l l i n g m o d u l e w i t h t h e w a r n i n g s : : e n a b l e d
f u n c t i o n . C o n s i d e r t h i s s n i p p e t o f c o d e :
package MyMod::Abc;
sub open {
if (warnings::enabled("deprecated")) {
warnings::warn("deprecated",
"open is deprecated, use new instead") ;
}
new(@_) ;
}
sub new
...
1 ;
T h e f u n c t i o n o p e n
h a s b e e n d e p r e c a t e d , s o c o d e h a s b e e n i n c l u d e d t o d i s p l a y a w a r n i n g m e s s a g e w h e n e v e r t h e c a l l i n g m o d u l e h a s ( a t l e a s t ) t h e " d e p r e c a t e d " w a r n i n g s c a t e g o r y e n a b l e d . S o m e t h i n g l i k e t h i s , s a y .
use warnings 'deprecated';
use MyMod::Abc;
...
MyMod::Abc::open($filename) ;
T h e w a r n i n g s : : w a r n
f u n c t i o n s h o u l d b e u s e d t o a c t u a l l y d i s p l a y t h e w a r n i n g s m e s s a g e . T h i s i s b e c a u s e t h e y c a n m a k e u s e o f t h e f e a t u r e t h a t a l l o w s w a r n i n g s t o b e e s c a l a t e d i n t o f a t a l e r r o r s . S o i n t h i s c a s e
use MyMod::Abc;
use warnings FATAL => 'MyMod::Abc';
...
MyMod::Abc::open('../fred.txt');
t h e w a r n i n g s : : w a r n
f u n c t i o n w i l l d e t e c t t h i s a n d d i e a f t e r d i s p l a y i n g t h e w a r n i n g m e s s a g e .
# T O D O
perl5db.pl
The debugger saves and restores C<$^W> at runtime. I haven't checked
whether the debugger will still work with the lexical warnings
patch applied.
diagnostics.pm
I *think* I've got diagnostics to work with the lexical warnings
patch, but there were design decisions made in diagnostics to work
around the limitations of C<$^W>. Now that those limitations are gone,
the module should be revisited.
# S E E A L S O
w a r n i n g s , p e r l d i a g .
# A U T H O R
P a u l M a r q u e s s
P e r l d o c B r o w s e r i s m a i n t a i n e d b y D a n B o o k ( D B O O K ) . P l e a s e c o n t a c t h i m v i a t h e G i t H u b i s s u e t r a c k e r or e m a i l r e g a r d i n g a n y i s s u e s w i t h t h e s i t e i t s e l f , s e a r c h , o r r e n d e r i n g o f d o c u m e n t a t i o n .
T h e P e r l d o c u m e n t a t i o n i s m a i n t a i n e d b y t h e P e r l 5 P o r t e r s i n t h e d e v e l o p m e n t o f P e r l . P l e a s e c o n t a c t t h e m v i a t h e P e r l i s s u e t r a c k e r , t h e m a i l i n g l i s t , o r I R C t o r e p o r t a n y i s s u e s w i t h t h e c o n t e n t s o r f o r m a t o f t h e d o c u m e n t a t i o n .