NAME

IO::ExplicitHandle - force I/O handles to be explicitly specified

SYNOPSIS

    use IO::ExplicitHandle;

    no IO::ExplicitHandle;

DESCRIPTION

This module provides a lexically-scoped pragma that prohibits I/O operations that implicitly default to an I/O handle determined at runtime. For example, print 123 implicitly uses the "currently selected" I/O handle (controlled by select). Within the context of the pragma, I/O operations must be explicitly told which handle they are to operate on. For example, print STDOUT 123 explicitly uses the program's standard output stream.

The affected operations are those that use either the "currently selected" I/O handle or the "last read" I/O handle. The affected operations that use the "currently selected" I/O handle are print, printf, say, close, write, and the magic variables $|, $^, $~, $=, $-, and $%. The affected operations that use the "last read" I/O handle are eof, tell, and the magic variable $..

One form of the .. operator can implicitly read $., but it cannot be reliably distinguished at compile time from the more common list-generating form, so it is not affected by this module.

The select function returns the "currently selected" I/O handle, and similarly the magic variable ${^LAST_FH} refers to the "last read" I/O handle. Such explicit retrieval of the I/O handles to which some operations default isn't itself considered an operation on the handle, and so is not affected by this module.

The readline function when called without arguments, and its syntactic sugar alias <>, default to the ARGV I/O handle. Because this is a fixed default, rather than using a hidden runtime variable, it is considered explicit enough, and so is not affected by this module. Relatedly, when the eof function is called with an empty parenthesised argument list (as opposed to calling it with no parentheses), it performs a unique operation which is concerned with the ARGV I/O handle but is not the same as eof(ARGV). This operation doesn't amount to defaulting an I/O handle argument at all, and is also not affected by this module. Likewise, the <<>> operator performs a unique operation on the ARGV handle, and is also not affected by this module.

PACKAGE METHODS

IO::ExplicitHandle->import

Turns on the I/O handle stricture in the lexical environment that is currently compiling.

IO::ExplicitHandle->unimport

Turns off the I/O handle stricture in the lexical environment that is currently compiling.

BUGS

The .. operator decides only at runtime whether it will read from $., and hence implicitly use the "last read" I/O handle. It does this if called in scalar context. If the same expression is called in list context, it generates a list of numbers, unrelated to $.. This semantic overloading prevents the problematic use of .. being detected at compile time.

SEE ALSO

strict

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2012, 2017, 2023 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.