cvs: php4 /pear/File Find.php

alexmerz Fri Aug 3 00:52:31 2001 EDT Modified files: /php4/pear/File Find.php Log: fix PHPDoc Index: php4/pear/File/Find.php diff -u php4/pear/File/Find.php:1.13 php4/pear/File/Find.php:1.14 --- php4/pear/File/Find.php:1.13 Sun Jul 29 17:40:36 2001 +++ php4/pear/File/Find.php Fri Aug 3 00:52:31 2001 @@ -16,47 +16,66 @@ // | Authors: Sterling Hughes <sterling@php.net> | // +----------------------------------------------------------------------+ // -// $Id: Find.php,v 1.13 2001/07/29 21:40:36 sterling Exp $ -// -// Commonly needed functions searching directory trees +// $Id: Find.php,v 1.14 2001/08/03 04:52:31 alexmerz Exp $ // require_once 'PEAR.php'; +/** +* Commonly needed functions searching directory trees +* +* @access public +* @version $Id: Find.php,v 1.14 2001/08/03 04:52:31 alexmerz Exp $ +* @package File +* @author Sterling Hughes <sterling@php.net> +*/ class File_Find { + /** + * internal dir-list + * @var array + */ var $_dirs = array (); + /** + * founded files + * @var array + */ var $files = array (); + /** + * founded dirs + * @var array + */ var $directories = array (); /** * Search the current directory to find matches for the * the specified pattern. * - * @param $pattern a string containing the pattern to search + * @param string $pattern a string containing the pattern to search * the directory for. - * - * @param $direct_path a string containing the directory path + * + * @param string $direct_path a string containing the directory path * to search. * - * @param $pattern_type a string containing the type of + * @param string $pattern_type a string containing the type of * pattern matching functions to use (can either be 'php' or * 'perl'). * - * @return an array containing all of the files and directories + * @return array containing all of the files and directories * matching the pattern. - * + * * @author Sterling Hughes <sterling@php.net> + * @access public */ function &glob ($pattern, $dirpath, $pattern_type='php') { $dh = @opendir ($dirpath); - + if (!$dh) { $pe = new FileFindException ("Cannot open directory"); return ($pe); } - + $match_function = File_Find::_determineRegex ($pattern, $pattern_type); while ($entry = @readdir ($dh)) @@ -67,7 +86,7 @@ $matches[] = $entry; } } - + @closedir ($dh); return ($matches); } @@ -75,14 +94,15 @@ /** * Map the directory tree given by the directory_path parameter. * - * @param $directory_path contains the directory path that you + * @param string $directory_path contains the directory path that you * want to map. * - * @return a two element array, the first element containing a list + * @return array a two element array, the first element containing a list * of all the directories, the second element containing a list of all the * files. * * @author Sterling Hughes <sterling@php.net> + * @access public */ function &maptree ($directory) { @@ -90,75 +110,79 @@ while (count ($this->_dirs)) { - $dir = array_pop ($this->_dirs); + $dir = array_pop ($this->_dirs); File_Find::_build ($dir); array_push ($this->directories, $dir); } - + return array ($this->directories, $this->files); } - + /** * Search the specified directory tree with the specified pattern. Return an * array containing all matching files (no directories included). * - * @param $pattern the pattern to match every file with. - * - * @param $directory the directory tree to search in. - * - * @param $regex_type the type of regular expression support to use, either + * @param string $pattern the pattern to match every file with. + * + * @param string $directory the directory tree to search in. + * + * @param string $regex_type the type of regular expression support to use, either * 'php' or 'perl'. * - * @return a list of files matching the pattern parameter in the the directory + * @return array a list of files matching the pattern parameter in the the directory * path specified by the directory parameter * * @author Sterling Hughes <sterling@php.net> + * @access public */ function &search ($pattern, $directory, $type='php') { list (,$files) = File_Find::maptree ($directory); $match_function = File_Find::_determineRegex ($pattern, $type); - + reset ($files); while (list (,$entry) = each ($files)) { if ($match_function ($pattern, $entry)) $matches[] = $entry; } - + return ($matches); } - /** * Determine whether or not a variable is a PEAR exception * - * @param $var the variable to test. - * - * @return returns true if the variable is a PEAR error, otherwise + * @param object PEAR_Error $var the variable to test. + * + * @return boolean returns true if the variable is a PEAR error, otherwise * it returns false. + * @access public */ function isError (&$var) { return PEAR::isError($var); } - + /** * Fetch the current File_Find version * - * @return the current File_Find version. + * @return string the current File_Find version. + * @access public */ function File_Find_version() { return (1.1); } - - /* + /** * internal function to build singular directory trees, used by * File_Find::maptree() + * + * @param string $directory name of the directory to read + * @return void */ function _build ($directory) { $dh = @opendir ($directory); - + if (!$dh) { $pe = new FileFindException ("Cannot open directory"); return ($pe); @@ -166,27 +190,31 @@ while ($entry = @readdir ($dh)) { - + if ($entry != '.' && $entry != '..') { - + $entry = "$directory/$entry"; - + if (is_dir ($entry)) array_push ($this->_dirs, $entry); else array_push ($this->files, $entry); - + } - + } - + @closedir ($dh); } - - /* + + /** * internal function to determine the type of regular expression to * use, implemented by File_Find::glob() and File_Find::search() + * + * @param string $type given RegExp type + * @return string kind of function ( "eregi", "ereg" or "preg_match") ; + * */ function _determineRegex ($pattern, $type) { @@ -197,18 +225,38 @@ } else { $match_function = 'ereg'; } - + return ($match_function); } //End Class } - +/** +* Exception Class for Errorhandling of File_Find +* @access public +*/ class FileFindException extends PEAR_Error { + /** + * classname + * @var string + */ var $classname = 'FileFindException'; + /** + * Message in front of the error message + * @var string + */ var $error_message_prepend = 'Error in File_Find'; - + /** + * Creates a PEAR_Error object + * + * @param string $message Error message + * @param int $mode Error mode + * @param int $level Error level + * + * @return object PEAR_Error + * @access public + */ function FileFindException ($message, $mode = PEAR_ERROR_RETURN, $level = E_USER_NOTICE) { $this->PEAR_Error ($message, $mode, $level);