The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
File-List-Object-0.202
River stage one • 1 direct dependent • 2 total dependents
++
/ File::List::Object

NAME

File::List::Object - Object containing a list of files (filelist, packlist).

VERSION

This document describes File::List::Object version 0.200.

DESCRIPTION

This package provides for creating a list of files (from different sources) and performing arithmetic and other applicable operations on said lists.

SYNOPSIS

        # Since this module is object-oriented, it does not matter if you
        # use or require the module, because there are no imports.
        require File::List::Object;

        # Cheate a File::List::Object
        my $filelist = File::List::Object->new();

        # Clones the filelist passed in;
        $filelist3 = File::List::Object->clone($filelist);

        # Add an individual file to a filelist.
        $filelist->add_file('/usr/bin/perl5'); 

        # Load a filelist from an array of files.
        $filelist2 = File::List::Object->new();
        $filelist2->load_array(@files);

        # Adds the files in $filelist2 to $filelist
        $filelist->add($filelist2);

        # Subtracts the files in $filelist2 from $filelist
        $filelist->subtract($filelist2);

        # Filters out the files with these strings at the
        # beginnning of their name.
        $filelist->filter(['/excluded', '/bad']);

        # Filters out the files on drive D.
        $filelist->filter(['D:\']);

        # Gets the number of files in the list.
        $filelist->count();

        # Moves a file within the filelist.
        $filelist->move('file.txt', 'file2.txt');

        # Moves a directory within the filelist.
        $filelist->move_dir('\test1', '\test2');

        # Loads the filelist from a file with filenames in it.
        $filelist->load_file($packlist_file);

        # Returns the list of files, sorted.
        # Useful for debugging purposes.
        $filelist->as_string();

        # Most operations return the original object, so they can be chained.
        # count and as_string stop a chain, new and clone can only start one.
        $filelist->load_file($packlist_file)->add_file($file)->as_string();

DESCRIPTION

This module provides an object-oriented interface to manipulate a list of files.

It was made to manipulate Perl .packlist files in memory, but the filelist does not have to be loaded from disk.

INTERFACE

new

        $filelist = File::List::Object->new();

Creates an empty object. To load the object with files, call add_file, load_array, or load_packlist.

clone

        $filelist2 = File::List::Object->clone($filelist);

Creates a new object that is a copy of the one passed to it. It performs a deep copy, so that the original object is not modified when the new one is.

debug

        $filelist->debug();

Sets the "debug state" of the object (currently only used in load_file).

count

        $number = $filelist->count();

Returns the number of files in the list.

clear

        $filelist = $filelist->clear();

Empties an object.

files

        @filelist = $filelist->files();

Returns a sorted list of the files in this object.

readdir

        $filelist = $filelist->readdir('C:\');

Adds the files in the directory passed in to the filelist.

This includes all files within subdirectories of this directory.

load_file

        $filelist = $filelist->load_file('C:\perl\.packlist');

Adds the files listed in the file passed in to the filelist.

This includes files that do not exist.

load_array

add_files

        $filelist = $filelist->load_array(@files_list);
        $filelist = $filelist->add_files(@files_list);

Adds the files listed in the array passed in to the filelist.

add_files is an alias for load_array.

add_file

        $filelist = $filelist->add_file('C:\readme.txt');

Adds the file passed in to the filelist.

The file being added must exist.

remove_files

remove_file

        $filelist = $filelist->remove_file('C:\readme.txt');
        $filelist = $filelist->remove_files('C:\readme.txt', 'C:\LICENSE');
        $filelist = $filelist->remove_files(@files);

Removes the file(s) passed in to the filelist.

remove_file is an alias for remove_files.

subtract

        $filelist = $filelist->subtract($filelist2);

Removes the files listed in the filelist object passed in.

add

        $filelist = $filelist->add($filelist2);

Adds the files listed in the filelist object passed in.

move

        $filelist = $filelist->move($file1, $file2);

Removes the first file passed in, and adds the second one to the filelist.

The second file need not exist yet.

move_dir

        $filelist = $filelist->move_dir($dir1, $dir2);

Moves the files that would be in the first directory passed in into the second directory within the filelist.

This does not modify the files on disk, and the second directory and the files in it need not exist yet.

filter

        $filelist = $filelist->filter([$string1, $string2, ...]);

Removes the files from the list whose names begin with the strings listed.

as_string

        $string = $filelist->as_string();
        print $filelist2->as_string();

Prints out the files contained in the list, sorted, one per line.

DIAGNOSTICS

All diagnostics are returned as Exception::Class::Base subclasses in the File::List::Object::Exception subtree.

File::List::Object error: Parameter missing or invalid: %s

An invalid parameter was passed in. More information about why it was invalid may be returned.

(Returned as a File::List::Object::Exception::Parameter object)

Error reading directory %s: %s

For some reason, the directory exists, but it could not be read.

CONFIGURATION AND ENVIRONMENT

File::List::Object requires no configuration files or environment variables.

DEPENDENCIES

Dependencies of this module that are non-core in perl 5.8.1 (which is the minimum version of Perl required) include Moose version 0.90, Exception::Class version 1.29, and Params::Util version 0.35.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS (SUPPORT)

The clone() routine did not work in versions previous to 0.189.

Bugs should be reported via:

1) The CPAN bug tracker at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-List-Object if you have an account there.

2) Email to <bug-File-List-Object@rt.cpan.org> if you do not.

For other issues, contact the topmost author.

AUTHOR

Curtis Jewell, <csjewell@cpan.org>

SEE ALSO

http://csjewell.comyr.com/perl/

LICENSE AND COPYRIGHT

Copyright (c) 2009, Curtis Jewell <csjewell@cpan.org>.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either version 5.8.1 or any later version. See perlartistic and perlgpl.

The full text of the license can be found in the LICENSE file included with this module.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.