GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  ITERATOR::IO (3)

.ds Aq ’

NAME

Iterator::IO - Filesystem and stream iterators.

CONTENTS

VERSION

This documentation describes version 0.02 of Iterator::IO.pm, August 23, 2005.

SYNOPSIS



 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);



DESCRIPTION

This module provides filesystem and stream iterator functions. See the Iterator module for more information about how to use iterators.

FUNCTIONS

idir_listing


 $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).

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).

idir_walk


 $iter = idir_walk ($path);



Returns the files in a directory tree, one by one. It’s sort of like File::Find in slow motion.

Requires IO::Dir and Cwd.

ifile


 $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:
chomp chomp => boolean indicates whether lines should be chomped before being returned by the iterator. The default is true.
$/ $/ => value specifies what string to use as the record separator. If not specified, the current value of $/ is used.

"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.

Option names are case-insensitive.

ifile requires IO::File.

ifile_reverse


 $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.

INTERFACE CHANGE

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.

EXPORTS

This module exports all function names to the caller’s namespace by default.

DIAGNOSTICS

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.

See the Iterator module documentation for more information on how to trap and handle these exception objects.
o Parameter Errors

Class: 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.

o Exhausted Iterators

Class: Iterator::X::Exhausted

You called value on an iterator that is exhausted; that is, there are no more values in the sequence to return.

As a string, this exception is Iterator is exhausted.

o I/O Errors

Class: 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.

As a string, this exception provides some human-readable information along with $!.

o Internal Errors

Class: 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.

REQUIREMENTS

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

SEE ALSO

Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.

<http://perl.plover.com/hop/>

THANKS

Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in general) for suggestions for the pre-release version.

AUTHOR / COPYRIGHT

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 IO (3) 2005-08-23

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.