1Path::Iter(3)         User Contributed Perl Documentation        Path::Iter(3)
2
3
4

NAME

6       Path::Iter - Simple Efficient Path Iteration
7

VERSION

9       This document describes Path::Iter version 0.2
10

SYNOPSIS

12           use Path::Iter;
13
14           my $fetch = Path::Iter::get_iterator('foo');
15
16           while ( my $next_path = $fetch->() ) {
17               # do something with $next_path
18           }
19

DESCRIPTION

21       Iterate through the contents of a given path without having to build
22       the entire list first.
23

INTERFACE

25   Path::Iter::get_iterator()
26       This returns an code reference that when called returns the next path.
27
28       When there are no more (or a directory can't be opened and you have
29       told it to stop as soon as that happens) it returns false.
30
31       It takes one or more paths to process and an optional argument hashref
32       as the last argument (See "%ARGS")
33
34       The paths returned contain the initial argument and its contents (if
35       any).
36
37       Assuming 'foo' in the SYNOPSIS:
38
39           is a symlink:   you'd iterate through foo
40           is a file:      you'd iterate through foo
41           is a directory: you'd iterate through foo, foo/bar, foo/wop, foo/bar/baz,
42
43   %ARGS
44       These are all optional.
45
46       errors
47
48       This is an array of hashref's where any errors get put.
49
50           my @err;
51           my $iter = Path::Iter::get_iterator($path, {errors => \@err});
52           while(my $next = $iter->()) {
53               ...
54           }
55           if (@err) {
56               ... handle error ...
57           }
58
59       The keys for each error in the array are as follows:
60
61           'path'     => $path,
62           'function' => 'opendir',
63           'args'     => [\*DIR, $path],
64           'errno'    => int($!),
65           'error'    => int($!) . ": $!",
66
67       stop_when_opendir_fails
68
69       Boolean, when, if true will short circuit the iteration if an opendir()
70       call fails.
71
72       readdir_handler
73
74       A coderef to be used to process and return directory contents (IE
75       readdir() results)
76
77           sub {
78               my($working_path, @contents) = @_;
79
80               if ($working_path eq '.data') {
81                   @contents = grep !/^\.private\-.*/, @contents; # ignore .private-... files in .data/ dir
82               }
83
84               return sort { $a cmp $b } @contents; # return what is left in sorted order
85           }
86
87       The first argument is the directory and the rest is its contents.
88
89       The @contents have already had the $working_path prepended.
90
91       It should return the contents how you wish them to appear in the
92       iteration.
93
94       symlink_handler
95
96       By default syminks are not followed.
97
98       This is a coderef that can control how symlinks are handled.
99
100       !! IF YOU ALTER THE DEFAULT BEHAVIOR YOU WILL NEED TO CHECK FOR LINK
101       LOOPS AND INFINITE RECURSION !!
102
103       It receives two arguments: the path and a boolean of if it was an
104       initial argument or not.
105
106       If it returns true the path will be followed. If the true value is '2'
107       it will be tranformed into its target.
108
109       !! IF YOU ALTER THE DEFAULT BEHAVIOR YOU WILL NEED TO CHECK FOR LINK
110       LOOPS AND INFINITE RECURSION !!
111
112       Assume we have a link named 'link' whose target is 'path':
113
114           sub {
115               my ($path, $is_initial_arg) = @_;
116               ...
117               return; # default behavior = link
118           }
119
120           sub {
121               my ($path, $is_initial_arg) = @_;
122               ...
123               return 1; # link link/dir link/file link/dir/etc
124           }
125
126           sub {
127               my ($path, $is_initial_arg) = @_;
128               ...
129               return 2; # path path/dir path/file path/dir/etc
130           }
131
132       !! IF YOU ALTER THE DEFAULT BEHAVIOR YOU WILL NEED TO CHECK FOR LINK
133       LOOPS AND INFINITE RECURSION !!
134
135       initial
136
137       This is a hashref used internally as a lookup of initial args as they
138       are after any initialization.
139

DIAGNOSTICS

141       Throws no warnings or errors of its own. You can catch internal opendir
142       failures. See "errors" and "stop_when_opendir_fails"
143

CONFIGURATION AND ENVIRONMENT

145       Path::Iter requires no configuration files or environment variables.
146

DEPENDENCIES

148       File::Spec
149

INCOMPATIBILITIES

151       None reported.
152

BUGS AND LIMITATIONS

154       No bugs have been reported.
155
156       Please report any bugs or feature requests to
157       "bug-path-iter@rt.cpan.org", or through the web interface at
158       <http://rt.cpan.org>.
159

AUTHOR

161       Daniel Muey  "<http://drmuey.com/cpan_contact.pl>"
162

164       Copyright (c) 2008, Daniel Muey "<http://drmuey.com/cpan_contact.pl>".
165       All rights reserved.
166
167       This module is free software; you can redistribute it and/or modify it
168       under the same terms as Perl itself. See perlartistic.
169

DISCLAIMER OF WARRANTY

171       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
172       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
173       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
174       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
175       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
176       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
177       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
178       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
179       NECESSARY SERVICING, REPAIR, OR CORRECTION.
180
181       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
182       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
183       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
184       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
185       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
186       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
187       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
188       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
189       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
190       DAMAGES.
191
192
193
194perl v5.36.0                      2023-01-20                     Path::Iter(3)
Impressum