File::Find::Object - An object oriented File::Find replacement

- NAME
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS

- new

- options

- next
- item
- next_obj
- item_obj
- $ff->`set_traverse_to([@children])`
- $ff->`prune()`
- [@children] = $ff->`get_traverse_to()`
- [@files] = $ff->`get_current_node_files_list()`

- BUGS
- SEE ALSO
- LICENSE

# NAME

File::Find::Object - An object oriented File::Find replacement

Back to Top

# SYNOPSIS

        use File::Find::Object;
        my $tree = File::Find::Object->new({}, @targets);

        while (my $r = $tree->next()) {
            print $r ."\n";
        }

Back to Top

# DESCRIPTION

File::Find::Object does the same job as File::Find but works like an object and with an iterator. As File::Find is not object oriented, one cannot perform multiple searches in the same application. The second problem of File::Find is its file processing: after starting its main loop, one cannot easily wait for another event and so get the next result.

With File::Find::Object you can get the next file by calling the `next()` function, but setting a callback is still possible.

Back to Top

# FUNCTIONS

## new

        my $ffo = File::Find::Object->new( { options }, @targets);

Create a new File::Find::Object object. `@targets` is the list of directories or files which the object should explore.

### options

depth

  Boolean - returns the directory content before the directory itself.

nocrossfs

  Boolean - doesn't continue on filesystems different than the parent.

followlink

  Boolean - follow symlinks when they point to a directory.

  You can safely set this option to true as File::Find::Object does not follow the link if it detects a loop.

filter

  Function reference - should point to a function returning TRUE or FALSE. This function is called with the filename to filter, if the function return FALSE, the file is skipped.

callback

  Function reference - should point to a function, which would be called each time a new file is returned. The function is called with the current filename as an argument.

## next

Returns the next file found by the File::Find::Object. It returns undef once the scan is completed.

## item

Returns the current filename found by the File::Find::Object object, i.e: the last value returned by `next()`.

## next_obj

Like `next()` only returns the result as a convenient the File::Find::Object::Result manpage object. `$ff->next()` is equivalent to `$ff->next_obj()->path()`.

## item_obj

Like `item()` only returns the result as a convenient the File::Find::Object::Result manpage object. `$ff->item()` is equivalent to `$ff->item_obj()->path()`.

## $ff->`set_traverse_to([@children])`

Sets the children to traverse to from the current node. Useful for pruning items to traverse.

Accepts a single array reference.

Example:

        $ff->set_traverse_to([ grep { ! /\A\./ } @{ $ff->get_traverse_to }]);

## $ff->`prune()`

Prunes the current directory. Equivalent to $ff->set_traverse_to([]).

## [@children] = $ff->`get_traverse_to()`

Retrieves the children that will be traversed to. Returns a single array reference.

(Example under `set_traverse_to`).

## [@files] = $ff->`get_current_node_files_list()`

Gets all the files that appear in the current directory. This value remains constant for every node, even after traversal or calls to `set_traverse_to()` and is useful to use as the basis of the argument for `set_traverse_to()`.

Returns a single array reference.

Back to Top

# BUGS

No bugs are known, but it doesn't mean there aren't any.

Back to Top

# SEE ALSO

There's an article about this module in the Perl Advent Calendar of 2006: http://perladvent.pm.org/2006/2/.

the File::Find manpage is the core module for traversing files in perl, which has several limitations.

the File::Next manpage, the File::Find::Iterator manpage, the File::Walker manpage and the unmaintained the File::FTS manpage are alternatives to this module.

Back to Top

# LICENSE

Copyright (C) 2005, 2006 by Olivier Thauvin

This package is free software; you can redistribute it and/or modify it under the following terms:

1. The GNU General Public License Version 2.0 - http://www.opensource.org/licenses/gpl-license.php

2. The Artistic License Version 2.0 - http://www.perlfoundation.org/legal/licenses/artistic-2_0.html

3. At your option - any later version of either or both of these licenses.

Back to Top

File::Find::Object - An object oriented File::Find replacement