File Coverage

blib/lib/IO/ExplicitHandle.pm
Criterion Covered Total %
statement 11 11 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 15 15 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             IO::ExplicitHandle - force I/O handles to be explicitly specified
4              
5             =head1 SYNOPSIS
6              
7             use IO::ExplicitHandle;
8              
9             no IO::ExplicitHandle;
10              
11             =head1 DESCRIPTION
12              
13             This module provides a lexically-scoped pragma that prohibits I/O
14             operations that use an implicit default I/O handle. For example, C
15             123> implicitly uses the "currently selected" I/O handle (controlled
16             by L). Within the context of the pragma, I/O
17             operations must be explicitly told which handle they are to operate on.
18             For example, C explicitly uses the program's standard
19             output stream.
20              
21             The affected operations that use the "currently selected" I/O handle are
22             L, L, L,
23             L, L, and the magic variables
24             L<$E|perlvar/$E>, L<$^|perlvar/$^>, L<$~|perlvar/$~>,
25             L<$=|perlvar/$=>, L<$-|perlvar/$->, and L<$%|perlvar/$%>. The affected
26             operations that use the "last read" I/O handle are L,
27             L, and the magic variable L<$.|perlvar/$.>. One form
28             of the L<..|perlop/..> operator can implicitly read L<$.|perlvar/$.>,
29             but it cannot be reliably distinguished at compile time from the more
30             common list-generating form, so it is not affected by this module.
31              
32             =cut
33              
34             package IO::ExplicitHandle;
35              
36 2     2   115032 { use 5.006; }
  2         10  
37 2     2   936 use Lexical::SealRequireHints 0.008;
  2         2070  
  2         17  
38 2     2   82 use warnings;
  2         6  
  2         93  
39 2     2   16 use strict;
  2         6  
  2         168  
40              
41             our $VERSION = "0.001";
42              
43             require XSLoader;
44             XSLoader::load(__PACKAGE__, $VERSION);
45              
46             =head1 PACKAGE METHODS
47              
48             =over
49              
50             =item IO::ExplicitHandle->import
51              
52             Turns on the I/O handle stricture in the lexical environment that is
53             currently compiling.
54              
55             =item IO::ExplicitHandle->unimport
56              
57             Turns off the I/O handle stricture in the lexical environment that is
58             currently compiling.
59              
60             =back
61              
62             =head1 BUGS
63              
64             The L<..|perlop/..> operator decides only at runtime whether it will
65             read from L<$.|perlvar/$.>, and hence implicitly use the "last read"
66             I/O handle. It does this if called in scalar context. If the same
67             expression is called in list context, it generates a list of numbers,
68             unrelated to L<$.|perlvar/$.>. This semantic overloading prevents the
69             problematic use of L<..|perlop/..> being detected at compile time.
70              
71             =head1 SEE ALSO
72              
73             L
74              
75             =head1 AUTHOR
76              
77             Andrew Main (Zefram)
78              
79             =head1 COPYRIGHT
80              
81             Copyright (C) 2012, 2017 Andrew Main (Zefram)
82              
83             =head1 LICENSE
84              
85             This module is free software; you can redistribute it and/or modify it
86             under the same terms as Perl itself.
87              
88             =cut
89              
90             1;