Subversion-Projekte lars-tiefland.php_share

<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**

 * Factory to access the most common File_Archive features

 * It uses lazy include, so you dont have to include the files from

 * File/Archive/* directories

 *

 * PHP versions 4 and 5

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this library; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330,Boston,MA 02111-1307 USA

 *

 * @category   File Formats

 * @package    File_Archive

 * @author     Vincent Lascaux <vincentlascaux@php.net>

 * @copyright  1997-2005 The PHP Group

 * @license    http://www.gnu.org/copyleft/lesser.html  LGPL

 * @version    CVS: $Id: Archive.php,v 1.90 2008/05/28 19:58:07 cbrunet Exp $

 * @link       http://pear.php.net/package/File_Archive

 */

/**

 * To have access to PEAR::isError and PEAR::raiseError

 * We should probably use lazy include and remove this inclusion...

 */

require_once "PEAR.php";

function File_Archive_cleanCache($file, $group)

{

    $file = split('_', $file);

    if (count($file) != 3) {

        return false; //not a File_Archive file, keep it

    }

    $name = $file[2];

    $name = urldecode($name);

    $group = $file[1];

    //clean the cache only for files in File_Archive groups

    return substr($group, 0, 11) == 'FileArchive' &&

           !file_exists($name); //and only if the related file no longer exists

}

/**

 * Factory to access the most common File_Archive features

 * It uses lazy include, so you dont have to include the files from

 * File/Archive/* directories

 */

class File_Archive

{

    function& _option($name)

    {

        static $container = array(

            'zipCompressionLevel' => 9,

             'gzCompressionLevel' => 9,

            'tmpDirectory' => '.',

            'cache' => null,

            'appendRemoveDuplicates' => false,

            'blockSize' => 65536,

            'cacheCondition' => false

        );

        return $container[$name];

    }

    /**

     * Sets an option that will be used by default by all readers or writers

     * Option names are case sensitive

     * Currently, the following options are used:

     *

     * "cache"

     *      Instance of a Cache_Lite object used to cache some compressed

     *      data to speed up future compressions of files

     *      Default: null (no cache used)

     *

     * "zipCompressionLevel"

     *      Value between 0 and 9 specifying the default compression level used

     *      by Zip writers (0 no compression, 9 highest compression)

     *      Default: 9

     *

     * "gzCompressionLevel"

     *      Value between 0 and 9 specifying the default compression level used

     *      by Gz writers (0 no compression, 9 highest compression)

     *      Default: 9

     *

     * "tmpDirectory"

     *      Directory where the temporary files generated by File_Archive will

     *      be created

     *      Default: '.'

     *

     * "appendRemoveDuplicates"

     *      If set to true, the appender created will by default remove the

     *      file present in the archive when adding a new one. This will slow the

     *      appending of files to archives

     *      Default: false

     *

     * "blockSize"

     *      To transfer data from a reader to a writer, some chunks a read from the

     *      source and written to the writer. This parameter controls the size of the

     *      chunks

     *      Default: 64kB

     *

     * "cacheCondition"

     *      This parameter specifies when a cache should be used. When the cache is

     *      used, the data of the reader is saved in a temporary file for future access.

     *      The cached reader will be read only once, even if you read it several times.

     *      This can be usefull to read compressed files or downloaded files (from http or ftp)

     *      The possible values for this option are

     *       - false: never use cache

     *       - a regexp: A cache will be used if the specified URL matches the regexp

     *         preg_match is used

     *      Default: false

     *      Example: '/^(http|ftp):\/\//' will cache all files downloaded via http or ftp

     *

     */

    function setOption($name, $value)

    {

        $option =& File_Archive::_option($name);

        $option = $value;

        if ($name == 'cache' && $value !== null) {

            //TODO: ask to Cache_Lite to allow that

            $value->_fileNameProtection = false;

        }

    }

    /**

     * Retrieve the value of an option

     */

    function getOption($name)

    {

        return File_Archive::_option($name);

    }

    /**

     * Create a reader to read the URL $URL.

     * If the URL is a directory, it will recursively read that directory.

     * If $uncompressionLevel is not null, the archives (files with extension

     * tar, zip, gz or tgz) will be considered as directories (up to a depth of

     * $uncompressionLevel if $uncompressionLevel > 0). The reader will only

     * read files with a directory depth of $directoryDepth. It reader will

     * replace the given URL ($URL) with $symbolic in the public filenames

     * The default symbolic name is the last filename in the URL (or '' for

     * directories)

     *

     * Examples:

     * Considere the following file system

     * <pre>

     * a.txt

     * b.tar (archive that contains the following files)

     *     c.txt

     *     d.tgz (archive that contains the following files)

     *         e.txt

     *         dir1/

     *             f.txt

     * dir2/

     *     g.txt

     *     dir3/

     *         h.tar (archive that contains the following files)

     *             i.txt

     * </pre>

     *

     * read('.') will return a reader that gives access to following

     * files (recursively read current dir):

     * <pre>

     * a.txt

     * b.tar

     * dir2/g.txt

     * dir2/dir3/h.tar

     * </pre>

     *

     * read('.', 'myBaseDir') will return the following reader:

     * <pre>

     * myBaseDir/a.txt

     * myBaseDir/b.tar

     * myBaseDir/dir2/g.txt

     * myBaseDir/dir2/dir3/h.tar

     * </pre>

     *

     * read('.', '', -1) will return the following reader (uncompress

     * everything)

     * <pre>

     * a.txt

     * b.tar/c.txt

     * b.tar/d.tgz/e.txt

     * b.tar/d.tgz/dir1/f.txt

     * dir2/g.txt

     * dir2/dir3/h.tar/i.txt

     * </pre>

     *

     * read('.', '', 1) will uncompress only one level (so d.tgz will

     * not be uncompressed):

     * <pre>

     * a.txt

     * b.tar/c.txt

     * b.tar/d.tgz

     * dir2/g.txt

     * dir2/dir3/h.tar/i.txt

     * </pre>

     *

     * read('.', '', 0, 0) will not recurse into subdirectories

     * <pre>

     * a.txt

     * b.tar

     * </pre>

     *

     * read('.', '', 0, 1) will recurse only one level in

     * subdirectories

     * <pre>

     * a.txt

     * b.tar

     * dir2/g.txt

     * </pre>

     *

     * read('.', '', -1, 2) will uncompress everything and recurse in

     * only 2 levels in subdirectories or archives

     * <pre>

     * a.txt

     * b.tar/c.txt

     * b.tar/d.tgz/e.txt

     * dir2/g.txt

     * </pre>

     *

     * The recursion level is determined by the real path, not the symbolic one.

     * So read('.', 'myBaseDir', -1, 2) will result to the same files:

     * <pre>

     * myBaseDir/a.txt

     * myBaseDir/b.tar/c.txt

     * myBaseDir/b.tar/d.tgz/e.txt (accepted because the real depth is 2)

     * myBaseDir/dir2/g.txt

     * </pre>

     *

     * Use readSource to do the same thing, reading from a specified reader instead of

     * reading from the system files

     *

     * To read a single file, you can do read('a.txt', 'public_name.txt')

     * If no public name is provided, the default one is the name of the file

     * read('dir2/g.txt') contains the single file named 'g.txt'

     * read('b.tar/c.txt') contains the single file named 'c.txt'

     *

     * Note: This function uncompress files reading their extension

     *       The compressed files must have a tar, zip, gz or tgz extension

     *       Since it is impossible for some URLs to use is_dir or is_file, this

     *       function may not work with

     *       URLs containing folders which name ends with such an extension

     */

    function readSource(&$source, $URL, $symbolic = null,

                  $uncompression = 0, $directoryDepth = -1)

    {

        return File_Archive::_readSource($source, $URL, $reachable, $baseDir,

                  $symbolic, $uncompression, $directoryDepth);

    }

    /**

     * This function performs exactly as readSource, but with two additional parameters

     * ($reachable and $baseDir) that will be set so that $reachable."/".$baseDir == $URL

     * and $reachable can be reached (in case of error)

     *

     * @access private

     */

    function _readSource(&$toConvert, $URL, &$reachable, &$baseDir, $symbolic = null,

                  $uncompression = 0, $directoryDepth = -1)

    {

        $source =& File_Archive::_convertToReader($toConvert);

        if (PEAR::isError($source)) {

            return $source;

        }

        if (is_array($URL)) {

            $converted = array();

            foreach($URL as $key => $foo) {

                $converted[] =& File_Archive::_convertToReader($URL[$key]);

            }

            return File_Archive::readMulti($converted);

        }

        //No need to uncompress more than $directoryDepth

        //That's not perfect, and some archives will still be uncompressed just

        //to be filtered out :(

        if ($directoryDepth >= 0) {

            $uncompressionLevel = min($uncompression, $directoryDepth);

        } else {

            $uncompressionLevel = $uncompression;

        }

        require_once 'File/Archive/Reader.php';

        $std = File_Archive_Reader::getStandardURL($URL);

        //Modify the symbolic name if necessary

        $slashPos = strrpos($std, '/');

        if ($symbolic === null) {

            if ($slashPos === false) {

                $realSymbolic = $std;

            } else {

                $realSymbolic = substr($std, $slashPos+1);

            }

        } else {

            $realSymbolic = $symbolic;

        }

        if ($slashPos !== false) {

            $baseFile = substr($std, 0, $slashPos+1);

            $lastFile = substr($std, $slashPos+1);

        } else {

            $baseFile = '';

            $lastFile = $std;

        }

        if (strpos($lastFile, '*')!==false ||

            strpos($lastFile, '?')!==false) {

            //We have to build a regexp here

            $regexp = str_replace(

                array('\*', '\?'),

                array('[^/]*', '[^/]'),

                preg_quote($lastFile)

            );

            $result = File_Archive::_readSource($source, $baseFile,

                                                $reachable, $baseDir, null, 0, -1);

            return File_Archive::filter(

                    File_Archive::predEreg('^'.$regexp.'$'),

                    $result

                   );

        }

        //If the URL can be interpreted as a directory, and we are reading from the file system

        if ((empty($URL) || is_dir($URL)) && $source === null) {

            require_once "File/Archive/Reader/Directory.php";

            if ($uncompressionLevel != 0) {

                require_once "File/Archive/Reader/Uncompress.php";

                $result = new File_Archive_Reader_Uncompress(

                    new File_Archive_Reader_Directory($std, '', $directoryDepth),

                    $uncompressionLevel

                );

            } else {

                $result = new File_Archive_Reader_Directory($std, '', $directoryDepth);

            }

            if ($directoryDepth >= 0) {

                require_once 'File/Archive/Reader/Filter.php';

                require_once 'File/Archive/Predicate/MaxDepth.php';

                $tmp =& File_Archive::filter(

                    new File_Archive_Predicate_MaxDepth($directoryDepth),

                    $result

                );

                unset($result);

                $result =& $tmp;

            }

            if (!empty($realSymbolic)) {

                if ($symbolic === null) {

                    $realSymbolic = '';

                }

                require_once "File/Archive/Reader/ChangeName/AddDirectory.php";

                $tmp =& new File_Archive_Reader_ChangeName_AddDirectory(

                    $realSymbolic,

                    $result

                );

                unset($result);

                $result =& $tmp;

            }

        //If the URL can be interpreted as a file, and we are reading from the file system

        } else if (is_file($URL) && substr($URL, -1)!='/' && $source === null) {

            require_once "File/Archive/Reader/File.php";

            $result = new File_Archive_Reader_File($URL, $realSymbolic);

        //Else, we will have to build a complex reader

        } else {

            require_once "File/Archive/Reader/File.php";

            $realPath = $std;

            // Try to find a file with a known extension in the path (

            // (to manage URLs like archive.tar/directory/file)

            $pos = 0;

            do {

                if ($pos+1<strlen($realPath)) {

                    $pos = strpos($realPath, '/', $pos+1);

                } else {

                    $pos = false;

                }

                if ($pos === false) {

                    $pos = strlen($realPath);

                }

                $file = substr($realPath, 0, $pos);

                $baseDir = substr($realPath, $pos+1);

                $dotPos = strrpos($file, '.');

                $extension = '';

                if ($dotPos !== false) {

                    $extension = substr($file, $dotPos+1);

                }

            } while ($pos < strlen($realPath) &&

                (!File_Archive::isKnownExtension($extension) ||

                 (is_dir($file) && $source==null)));

            $reachable = $file;

            //If we are reading from the file system

            if ($source === null) {

                //Create a file reader

                $result = new File_Archive_Reader_File($file);

            } else {

                //Select in the source the file $file

                require_once "File/Archive/Reader/Select.php";

                $result = new File_Archive_Reader_Select($file, $source);

            }

            require_once "File/Archive/Reader/Uncompress.php";

            $tmp = new File_Archive_Reader_Uncompress($result, $uncompressionLevel);

            unset($result);

            $result = $tmp;

            //Select the requested folder in the uncompress reader

            $isDir = $result->setBaseDir($std);

            if (PEAR::isError($isDir)) {

                return $isDir;

            }

            if ($isDir && $symbolic==null) {

                //Default symbolic name for directories is empty

                $realSymbolic = '';

            }

            if ($directoryDepth >= 0) {

                //Limit the maximum depth if necessary

                require_once "File/Archive/Reader/Filter.php";

                require_once "File/Archive/Predicate/MaxDepth.php";

                $tmp = new File_Archive_Reader_Filter(

                    new File_Archive_Predicate(

                        $directoryDepth +

                        substr_count(substr($std, $pos+1), '/')

                    ),

                    $result

                );

                unset($result);

                $result =& $tmp;

            }

            if ($std != $realSymbolic) {

                require_once "File/Archive/Reader/ChangeName/Directory.php";

                //Change the base name to the symbolic one if necessary

                $tmp = new File_Archive_Reader_ChangeName_Directory(

                    $std,

                    $realSymbolic,

                    $result

                );

                unset($result);

                $result =& $tmp;

            }

        }

        $cacheCondition = File_Archive::getOption('cacheCondition');

        if ($cacheCondition !== false &&

            preg_match($cacheCondition, $URL)) {

            $tmp =& File_Archive::cache($result);

            unset($result);

            $result =& $tmp;

        }

        return $result;

    }

    function read($URL, $symbolic = null,

                  $uncompression = 0, $directoryDepth = -1)

    {

        $source = null;

        return File_Archive::readSource($source, $URL, $symbolic, $uncompression, $directoryDepth);

    }

    /**

     * Create a file reader on an uploaded file. The reader will read

     * $_FILES[$name]['tmp_name'] and will have $_FILES[$name]['name']

     * as a symbolic filename.

     *

     * A PEAR error is returned if one of the following happen

     *  - $_FILES[$name] is not set

     *  - $_FILES[$name]['error'] is not 0

     *  - is_uploaded_file returns false

     *

     * @param string $name Index of the file in the $_FILES array

     * @return File_Archive_Reader File reader on the uploaded file

     */

    function readUploadedFile($name)

    {

        if (!isset($_FILES[$name])) {

            return PEAR::raiseError("File $name has not been uploaded");

        }

        switch ($_FILES[$name]['error']) {

        case 0:

            //No error

            break;

        case 1:

            return PEAR::raiseError(

                        "The upload size limit didn't allow to upload file ".

                        $_FILES[$name]['name']

                    );

        case 2:

            return PEAR::raiseError(

                        "The form size limit didn't allow to upload file ".

                        $_FILES[$name]['name']

                   );

        case 3:

            return PEAR::raiseError(

                        "The file was not entirely uploaded"

                   );

        case 4:

            return PEAR::raiseError(

                        "The uploaded file is empty"

                   );

        default:

            return PEAR::raiseError(

                        "Unknown error ".$_FILES[$name]['error']." in file upload. ".

                        "Please, report a bug"

                   );

        }

        if (!is_uploaded_file($_FILES[$name]['tmp_name'])) {

            return PEAR::raiseError("The file is not an uploaded file");

        }

        require_once "File/Archive/Reader/File.php";

        return new File_Archive_Reader_File(

                    $_FILES[$name]['tmp_name'],

                    $_FILES[$name]['name'],

                    $_FILES[$name]['type']

               );

    }

    /**

     * Adds a cache layer above the specified reader

     * The data of the reader is saved in a temporary file for future access.

     * The cached reader will be read only once, even if you read it several times.

     * This can be usefull to read compressed files or downloaded files (from http or ftp)

     *

     * @param mixed $toConvert The reader to cache

     *        It can be a File_Archive_Reader or a string, which will be converted using the

     *        read function

     */

    function cache(&$toConvert)

    {

        $source =& File_Archive::_convertToReader($toConvert);

        if (PEAR::isError($source)) {

            return $source;

        }

        require_once 'File/Archive/Reader/Cache.php';

        return new File_Archive_Reader_Cache($source);

    }

    /**

     * Try to interpret the object as a reader

     * Strings are converted to readers using File_Archive::read

     * Arrays are converted to readers using File_Archive::readMulti

     *

     * @access private

     */

    function &_convertToReader(&$source)

    {

        if (is_string($source)) {

            $cacheCondition = File_Archive::getOption('cacheCondition');

            if ($cacheCondition !== false &&

                preg_match($cacheCondition, $source)) {

                $obj = File_Archive::cache(File_Archive::read($source));

                return $obj;

            } else {

                $obj = File_Archive::read($source);

                return $obj;

            }

        } else if (is_array($source)) {

            return File_Archive::readMulti($source);

        } else {

            return $source;

        }

     }

    /**

     * Try to interpret the object as a writer

     * Strings are converted to writers using File_Archive::appender

     * Arrays are converted to writers using a multi writer

     *

     * @access private

     */

    function &_convertToWriter(&$dest)

    {

        if (is_string($dest)) {

            $obj =& File_Archive::appender($dest);

            return $obj;

        } else if (is_array($dest)) {

            require_once 'File/Archive/Writer/Multi.php';

            $writer = new File_Archive_Writer_Multi();

            foreach($dest as $key => $foo) {

                $writer->addWriter($dest[$key]);

            }

            return $writer;

        } else {

            return $dest;

        }

    }

    /**

     * Check if a file with a specific extension can be read as an archive

     * with File_Archive::read*

     * This function is case sensitive.

     *

     * @param string $extension the checked extension

     * @return bool whether this file can be understood reading its extension

     *         Currently, supported extensions are tar, zip, jar, gz, tgz,

     *         tbz, bz2, bzip2, ar, deb

     */

    function isKnownExtension($extension)

    {

        return $extension == 'tar'   ||

               $extension == 'zip'   ||

               $extension == 'jar'   ||

               $extension == 'gz'    ||

               $extension == 'tgz'   ||

               $extension == 'tbz'   ||

               $extension == 'bz2'   ||

               $extension == 'bzip2' ||

               $extension == 'ar'    ||

               $extension == 'deb'   /* ||

               $extension == 'cab'   ||

               $extension == 'rar' */;

    }

    /**

     * Create a reader that will read the single file source $source as

     * a specific archive

     *

     * @param string $extension determines the kind of archive $source contains

     *        $extension is case sensitive

     * @param File_Archive_Reader $source stores the archive

     * @param bool $sourceOpened specifies if the archive is already opened

     *        if false, next will be called on source

     *        Closing the returned archive will close $source iif $sourceOpened

     *        is true

     * @return A File_Archive_Reader that uncompresses the archive contained in

     *         $source interpreting it as a $extension archive

     *         If $extension is not handled return false

     */

    function readArchive($extension, &$toConvert, $sourceOpened = false)

    {

        $source =& File_Archive::_convertToReader($toConvert);

        if (PEAR::isError($source)) {

            return $source;

        }

        switch($extension) {

        case 'tgz':

            return File_Archive::readArchive('tar',

                    File_Archive::readArchive('gz', $source, $sourceOpened)

                    );

        case 'tbz':

            return File_Archive::readArchive('tar',

                    File_Archive::readArchive('bz2', $source, $sourceOpened)

                    );

        case 'tar':

            require_once 'File/Archive/Reader/Tar.php';

            return new File_Archive_Reader_Tar($source, $sourceOpened);

        case 'gz':

        case 'gzip':

            require_once 'File/Archive/Reader/Gzip.php';

            return new File_Archive_Reader_Gzip($source, $sourceOpened);

        case 'zip':

        case 'jar':

            require_once 'File/Archive/Reader/Zip.php';

            return new File_Archive_Reader_Zip($source, $sourceOpened);

        case 'bz2':

        case 'bzip2':

            require_once 'File/Archive/Reader/Bzip2.php';

            return new File_Archive_Reader_Bzip2($source, $sourceOpened);

        case 'deb':

        case 'ar':

            require_once 'File/Archive/Reader/Ar.php';

            return new File_Archive_Reader_Ar($source, $sourceOpened);

/*        case 'cab':

            require_once 'File/Archive/Reader/Cab.php';

            return new File_Archive_Reader_Cab($source, $sourceOpened);

        case 'rar':

            require_once "File/Archive/Reader/Rar.php";

            return new File_Archive_Reader_Rar($source, $sourceOpened); */

        default:

            return false;

        }

    }

    /**

     * Contains only one file with data read from a memory buffer

     *

     * @param string $memory content of the file

     * @param string $filename public name of the file

     * @param array $stat statistics of the file. Index 7 (size) will be

     *        overwritten to match the size of $memory

     * @param string $mime mime type of the file. Default will determine the

     *        mime type thanks to the extension of $filename

     * @see File_Archive_Reader_Memory

     */

    function readMemory($memory, $filename, $stat=array(), $mime=null)

    {

        require_once "File/Archive/Reader/Memory.php";

        return new File_Archive_Reader_Memory($memory, $filename, $stat, $mime);

    }

    /**

     * Contains several other sources. Take care the sources don't have several

     * files with the same filename. The sources are given as a parameter, or

     * can be added thanks to the reader addSource method

     *

     * @param array $sources Array of strings or readers that will be added to

     *        the multi reader. If the parameter is a string, a reader will be

     *        built thanks to the read function

     * @see   File_Archive_Reader_Multi, File_Archive::read()

     */

    function readMulti($sources = array())

    {

        require_once "File/Archive/Reader/Multi.php";

        $result = new File_Archive_Reader_Multi();

        foreach ($sources as $index => $foo) {

            $s =& File_Archive::_convertToReader($sources[$index]);

            if (PEAR::isError($s)) {

                return $s;

            } else {

                $result->addSource($s);

            }

        }

        return $result;

    }

    /**

     * Make the files of a source appear as one large file whose content is the

     * concatenation of the content of all the files

     *

     * @param File_Archive_Reader $toConvert The source whose files must be

     *        concatened

     * @param string $filename name of the only file of the created reader

     * @param array $stat statistics of the file. Index 7 (size) will be

     *        overwritten to match the total size of the files

     * @param string $mime mime type of the file. Default will determine the

     *        mime type thanks to the extension of $filename

     * @see   File_Archive_Reader_Concat

     */

    function readConcat(&$toConvert, $filename, $stat=array(), $mime=null)

    {

        $source =& File_Archive::_convertToReader($toConvert);

        if (PEAR::isError($source)) {

            return $source;

        }

        require_once "File/Archive/Reader/Concat.php";

        return new File_Archive_Reader_Concat($source, $filename, $stat, $mime);

    }

    /**

     * Changes the name of each file in a reader by applying a custom function

     * The function must return false if the file is to be discarded, or the new

     * name of the file else

     *

     * @param Callable $function Function called to modify the name of the file

     *        $function takes the name of the file as a parameter and returns the

     *        new name, or false if the file must be discarded

     * @param File_Archive_Reader $toConvert The files of this source will be

     *        modified

     * @return File_Archive_Reader a new reader that contains the same files

     *        as $toConvert but with a different name

     */

    function changeName($function, &$toConvert)

    {

        $source =& File_Archive::_convertToReader($toConvert);

        if (PEAR::isError($source)) {

            return $source;

        }

        require_once "File/Archive/Reader/ChangeName.php";

        return new File_Archive_Reader_RemoveDirectory($source);

    }

    /**

     * Removes from a source the files that do not follow a given predicat

     *

     * @param File_Archive_Predicate $predicate Only the files for which

     *        $predicate->isTrue() will be kept

     * @param File_Archive_Reader $source Source that will be filtered

     * @see   File_Archive_Reader_Filter

     */

    function filter($predicate, &$toConvert)

    {

        $source =& File_Archive::_convertToReader($toConvert);

        if (PEAR::isError($source)) {

            return $source;

        }

        require_once "File/Archive/Reader/Filter.php";

        return new File_Archive_Reader_Filter($predicate, $source);

    }

    /**

     * Predicate that always evaluate to true

     *

     * @see File_Archive_Predicate_True

     */

    function predTrue()

    {

        require_once "File/Archive/Predicate/True.php";

        return new File_Archive_Predicate_True();

    }

    /**

     * Predicate that always evaluate to false

     *

     * @see File_Archive_Predicate_False

     */

    function predFalse()

    {

        require_once "File/Archive/Predicate/False.php";

        return new File_Archive_Predicate_False();

    }

    /**

     * Predicate that evaluates to the logical AND of the parameters

     * You can add other predicates thanks to the

     * File_Archive_Predicate_And::addPredicate() function

     *

     * @param File_Archive_Predicate (any number of them)

     * @see File_Archive_Predicate_And

     */

    function predAnd()

    {

        require_once "File/Archive/Predicate/And.php";

        $pred = new File_Archive_Predicate_And();

        $args = func_get_args();

        foreach ($args as $p) {

            $pred->addPredicate($p);

        }

        return $pred;

    }

    /**

     * Predicate that evaluates to the logical OR of the parameters

     * You can add other predicates thanks to the

     * File_Archive_Predicate_Or::addPredicate() function

     *

     * @param File_Archive_Predicate (any number of them)

     * @see File_Archive_Predicate_Or

     */

    function predOr()

    {

        require_once "File/Archive/Predicate/Or.php";

        $pred = new File_Archive_Predicate_Or();

        $args = func_get_args();

        foreach ($args as $p) {

            $pred->addPredicate($p);

        }

        return $pred;

    }

    /**

     * Negate a predicate

     *

     * @param File_Archive_Predicate $pred Predicate to negate

     * @see File_Archive_Predicate_Not

     */

    function predNot($pred)

    {

        require_once "File/Archive/Predicate/Not.php";

        return new File_Archive_Predicate_Not($pred);

    }

    /**

     * Evaluates to true iif the file is larger than a given size

     *

     * @param int $size the minimal size of the files (in Bytes)

     * @see File_Archive_Predicate_MinSize

     */

    function predMinSize($size)

    {

        require_once "File/Archive/Predicate/MinSize.php";

        return new File_Archive_Predicate_MinSize($size);

    }

    /**

     * Evaluates to true iif the file has been modified after a given time

     *

     * @param int $time Unix timestamp of the minimal modification time of the

     *        files

     * @see File_Archive_Predicate_MinTime

     */

    function predMinTime($time)

    {

        require_once "File/Archive/Predicate/MinTime.php";

        return new File_Archive_Predicate_MinTime($time);

    }

    /**

     * Evaluates to true iif the file has less that a given number of

     * directories in its path

     *

     * @param int $depth Maximal number of directories in path of the files

     * @see File_Archive_Predicate_MaxDepth

     */

    function predMaxDepth($depth)

    {

        require_once "File/Archive/Predicate/MaxDepth.php";

        return new File_Archive_Predicate_MaxDepth($depth);

    }

    /**

     * Evaluates to true iif the extension of the file is in a given list

     *

     * @param array or string $list List or comma separated string of possible

     * extension of the files

     * @see File_Archive_Predicate_Extension

     */

    function predExtension($list)

    {

        require_once "File/Archive/Predicate/Extension.php";

        return new File_Archive_Predicate_Extension($list);

    }

    /**

     * Evaluates to true iif the MIME type of the file is in a given list

     *

     * @param array or string $list List or comma separated string of possible

     *        MIME types of the files. You may enter wildcards like "image/*" to

     *        select all the MIME in class image

     * @see   File_Archive_Predicate_MIME, MIME_Type::isWildcard()

     */

    function predMIME($list)

    {

        require_once "File/Archive/Predicate/MIME.php";

        return new File_Archive_Predicate_MIME($list);

    }

    /**

     * Evaluates to true iif the name of the file follow a given regular

     * expression

     *

     * @param string $ereg regular expression that the filename must follow

     * @see File_Archive_Predicate_Ereg, ereg()

     */

    function predEreg($ereg)

    {

        require_once "File/Archive/Predicate/Ereg.php";

        return new File_Archive_Predicate_Ereg($ereg);

    }

    /**

     * Evaluates to true iif the name of the file follow a given regular

     * expression (case insensitive version)

     *

     * @param string $ereg regular expression that the filename must follow

     * @see File_Archive_Predicate_Eregi, eregi

     */

    function predEregi($ereg)

    {

        require_once "File/Archive/Predicate/Eregi.php";

        return new File_Archive_Predicate_Eregi($ereg);

    }

    /**

     * Evaluates to true only after a given number of evaluations

     * This can be used to select files by index since the evaluation is done

     * once per file

     *

     * @param array The indexes for which the returned predicate will return true

     *        are the keys of the array

     *        The predicate will return true if isset($indexes[$pos])

     */

    function predIndex($indexes)

    {

        require_once "File/Archive/Predicate/Index.php";

        return new File_Archive_Predicate_Index($indexes);

    }

    /**

     * Custom predicate built by supplying a string expression

     *

     * Here are different ways to create a predicate that keeps only files

     * with names shorter than 100 chars

     * <sample>

     *  File_Archive::predCustom("return strlen($name)<100;")

     *  File_Archive::predCustom("strlen($name)<100;")

     *  File_Archive::predCustom("strlen($name)<100")

     *  File_Archive::predCustom("strlen($source->getFilename())<100")

     * </sample>

     *

     * @param string $expression String containing an expression that evaluates

     *        to a boolean. If the expression doesn't contain a return

     *        statement, it will be added at the begining of the expression

     *        A ';' will be added at the end of the expression so that you don't

     *        have to write it. You may use the $name variable to refer to the