Iterator::IO - Filesystem and stream iterators.
This documentation describes version 0.02 of Iterator::IO.pm, August 23, 2005.
use Iterator::IO; # Return the names of files in a directory (except . and ..) $iter = idir_listing ($path); # Return all the files in a directory tree, one at a time. # Like File::Find, in slow motion. $iter = idir_walk ($path); # Return the lines of a file, one at a time. $iter = ifile ($filename, \%options); # Return the lines of a file, in reverse order $iter = ifile_reverse ($filename, \%options);
This module provides filesystem and stream iterator functions. See the Iterator module for more information about how to use iterators.
$iter = idir_listing ($path);
Iterator that returns the names of the files in the $path directory. If $path is omitted, defaults to the current directory. Does not return the . and .. files (under unix).
$path
.
..
Requires IO::Dir and Cwd.
Example:
To return only certain files, combine this with an igrep:
$iter = igrep {-s && -M < 1} idir "/some/path";
(Returns non-empty files modified less than a day ago). (igrep) is defined in the Iterator::Util module).
$iter = idir_walk ($path);
Returns the files in a directory tree, one by one. It's sort of like File::Find in slow motion.
$iter = ifile ($filename, \%options);
Opens a file, generates an iterator to return the lines of the file.
\%options is a reference to a hash of options. Currently, two options are supported:
\%options
chomp => boolean indicates whether lines should be chomped before being returned by the iterator. The default is true.
chomp => boolean
chomp
'$/' => value specifies what string to use as the record separator. If not specified, the current value of $/ is used.
'$/' => value
$/
"rs" or "input_record_separator" may be used as option names instead of "$/", if you find that to be more readable. See the English module.
rs
input_record_separator
Option names are case-insensitive.
ifile requires IO::File.
ifile
$iter = ifile_reverse ($filename, \%options);
Exactly the same as "ifile", but reads the lines of the file backwards.
The input_record_separator option values undef (slurp whole file) and scalar references (fixed-length records) are not currently supported.
undef
In version 0.01 of Iterator::IO, the "ifile" and ifile_reverse functions accepted their options in a different manner. This has now changed to operate via a hash reference of options. The old way will still work, but is deprecated and will be removed in a future release.
This module exports all function names to the caller's namespace by default.
Iterator::IO uses Exception::Class objects for throwing exceptions. If you're not familiar with Exception::Class, don't worry; these exception objects work just like $@ does with die and croak, but they are easier to work with if you are trapping errors.
$@
die
croak
See the Iterator module documentation for more information on how to trap and handle these exception objects.
Parameter Errors
Class: Iterator::X::Parameter_Error
Iterator::X::Parameter_Error
You called an Iterator::IO function with one or more bad parameters. Since this is almost certainly a coding error, there is probably not much use in handling this sort of exception.
As a string, this exception provides a human-readable message about what the problem was.
Exhausted Iterators
Class: Iterator::X::Exhausted
Iterator::X::Exhausted
You called value on an iterator that is exhausted; that is, there are no more values in the sequence to return.
value
As a string, this exception is "Iterator is exhausted."
I/O Errors
Class: Iterator::X::IO_Error
Iterator::X::IO_Error
This exception is thrown when any sort of I/O error occurs; this only happens with the filesystem iterators.
This exception has one method, os_error, which returns the original $! that was trapped by the Iterator object.
os_error
$!
As a string, this exception provides some human-readable information along with $!.
Internal Errors
Class: Iterator::X::Internal_Error
Iterator::X::Internal_Error
Something happened that I thought couldn't possibly happen. I would appreciate it if you could send me an email message detailing the circumstances of the error.
Requires the following additional modules:
Iterator
IO::Dir and Cwd are required if you use "idir_listing" or "idir_walk".
IO::File is required if you use "ifile" or "ifile_reverse"
Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.
http://perl.plover.com/hop/
Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in general) for suggestions for the pre-release version.
Eric J. Roode, roode@cpan.org
Copyright (c) 2005 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To avoid my spam filter, please include "Perl", "module", or this module's name in the message's subject line, and/or GPG-sign your message.
To install Iterator::IO, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Iterator::IO
CPAN shell
perl -MCPAN -e shell install Iterator::IO
For more information on module installation, please visit the detailed CPAN module installation guide.