Class: I2CE FileSearch: Difference between revisions
No edit summary |
No edit summary |
||
Line 3: | Line 3: | ||
** [[Class: I2CE_FileSearch_Caching | I2CE_FileSearch_Caching]] | ** [[Class: I2CE_FileSearch_Caching | I2CE_FileSearch_Caching]] | ||
*Location: Part of the module [[I2CE Module List#I2CE|I2CE]] in the package [https://launchpad.net/i2ce I2CE] | *Location: Part of the module [[I2CE Module List#I2CE|I2CE]] in the package [https://launchpad.net/i2ce I2CE] | ||
*Source: Defined in the file [http://bazaar.launchpad.net/~intrahealth+informatics/i2ce/4.0. | *Source: Defined in the file [http://bazaar.launchpad.net/~intrahealth+informatics/i2ce/4.0.1-release/annotate/head:/lib/I2CE_FileSearch.php lib/I2CE_FileSearch.php] | ||
Class to handle file searching. | Class to handle file searching. | ||
==Variables== | ==Variables== | ||
===$relative_path=== | |||
If not null, it is the file system path that all paths are attempted to resolve to. If null, all resolved paths are absolute @protected static string $relative_path | |||
*Type: static protected $relative_path | |||
===$relative_root=== | |||
The root drive of the relative path e.g. "C:" on windows or '/' on unix. on windows unix it may or may not contains the trailing "\" due to the following maddness: *realpath(C:) is C:\ *realpath(C:\) is C:\ *realpath(C:\\) is C:\ *realpath(C:\some) is C:\some *realpath(C:\some\) is C:\some @protected static string $relative_root | |||
*Type: static protected $relative_root | |||
===$relative_parts=== | |||
The parts of the relative path. On windows, it does '''not''' include the drive letter. @protected static array of string $relative_parts | |||
*Type: static protected $relative_parts | |||
===$found_locales=== | ===$found_locales=== | ||
The found locale(s) . One of: FALSE, a string, or an array. The former two in the case of a single serach, the later in case of a $find_all search | The found locale(s) . One of: FALSE, a string, or an array. The former two in the case of a single serach, the later in case of a $find_all search | ||
Line 77: | Line 89: | ||
** [http://www.php.net/manual/en/language.types.boolean.php boolean ] $absolut <br/>whether or not to try to make a relative path absolut. It will overide (but not change) the global behaviour of this instance. | ** [http://www.php.net/manual/en/language.types.boolean.php boolean ] $absolut <br/>whether or not to try to make a relative path absolut. It will overide (but not change) the global behaviour of this instance. | ||
***Default Value: null | ***Default Value: null | ||
** [http://www.php.net/manual/en/language.types.string.php string ] $path_prefix <br/>Defaults to null. Any prefix to add to a | ** [http://www.php.net/manual/en/language.types.string.php string ] $path_prefix <br/>Defaults to null. Any prefix to add to a local class path (if we do make absolute) | ||
***Default Value: null | ***Default Value: null | ||
** [http://www.php.net/manual/en/language.pseudo-types.php mixed ] $locales <br/>null(default) , string or array of string. Used to override the default locale settings when not the defaults of null. It is the list of localized sub-directories to search for, if the given glob is a subdirectory. | ** [http://www.php.net/manual/en/language.pseudo-types.php mixed ] $locales <br/>null(default) , string or array of string. Used to override the default locale settings when not the defaults of null. It is the list of localized sub-directories to search for, if the given glob is a subdirectory. | ||
Line 128: | Line 140: | ||
*Signature: public function getLocaleOfLastSearch() | *Signature: public function getLocaleOfLastSearch() | ||
*Returns: mixed.<br/>If the last search has $find_all = false then either false if no file was found or a string, the locale in which the the results was found. If the $find_all was true, then it is an array of string, the locales of the files found. | *Returns: mixed.<br/>If the last search has $find_all = false then either false if no file was found or a string, the locale in which the the results was found. If the $find_all was true, then it is an array of string, the locales of the files found. | ||
===getParts()=== | |||
Returns the parts of a path split up according to the directory spearator. Does _not_ check to see if the given $path is valid | |||
*Signature: static public function getParts($path,$dir_sep,$esc_char,$ignore_empty) | |||
*Parameters: | |||
** [http://www.php.net/manual/en/language.types.string.php string ] $path @param mixed string $dir_sep. chracter or array of charaterds. Defautls to DIRECTORY_SEPARATOR. A single character used as the directory sepearator | |||
**$dir_sep | |||
***Default Value: DIRECTORY_SEPARATOR | |||
** [http://www.php.net/manual/en/language.types.string.php string ] $esc_char <br/>Defautls to '\' if $dir_sep is '/' and detaults to none if the $dir_sep is '\'. Set it to false if you don't want any escape characters | |||
***Default Value: null | |||
** [http://www.php.net/manual/en/language.types.boolean.php boolean ] $ignore_empty <br/>If true (default), we dont add "empty" parts e.g. C:\some\\path returns array('c:','some','path'). Exmaple: \toolkit\path returns array('toolkit','path') | |||
***Default Value: true | |||
*Returns: $array | |||
===getRelativePath()=== | |||
Returns the path which all files are attempted to resolve relative to | |||
*Signature: static public function getRelativePath() | |||
*Returns: [http://www.php.net/manual/en/language.pseudo-types.php mixed ]<br/>string, the path, or null if there is no relative path | |||
===getRootPath()=== | |||
Attempts to get the base directory of the given path. On unix (or non-windows) this is always '/' On windows it is the drive with colon and no trailing slash, e.g. 'E:' | |||
*Signature: static public function getRootPath($path) | |||
*Parameters: | |||
** [http://www.php.net/manual/en/language.types.string.php string ] $path <br/>An absolute path | |||
*Returns: mixed.<br/>A string on success, null on failure | |||
===getSearchPath()=== | ===getSearchPath()=== | ||
Gets the search path for the specified catgegory | Gets the search path for the specified catgegory | ||
Line 150: | Line 184: | ||
***Default Value: "" | ***Default Value: "" | ||
*Returns: [http://www.php.net/manual/en/language.types.array.php array ]<br/>List of directories | *Returns: [http://www.php.net/manual/en/language.types.array.php array ]<br/>List of directories | ||
===realPath()=== | |||
Gets the real path, realpath(), of a given path on unix. On windows, if the relative path is not set, then this is just realpath(), otherwise it tries to resolve it as a path relative to the [[#$relative_root | $relative_root]] return mixed. String or false on failure | |||
*Signature: static public function realPath($path) | |||
*Parameters: | |||
**$path | |||
===relativePath()=== | |||
Gets the relative real path of a given path on a windows box. If the relative path is not set, then this is just realpath(), otherwise it tries to resolve it as a path relative to the [[#$relative_root | $relative_root]] See windows path conventions. | |||
*Signature: static public function relativePath($path) | |||
*Parameters: | |||
** [http://www.php.net/manual/en/language.types.string.php string ] $path return mixed. String or false on failure | |||
===removePath()=== | ===removePath()=== | ||
Remove a path in a category | Remove a path in a category | ||
Line 219: | Line 263: | ||
** [http://www.php.net/manual/en/language.types.boolean.php boolean ] $validate <br/>Defaults to true. | ** [http://www.php.net/manual/en/language.types.boolean.php boolean ] $validate <br/>Defaults to true. | ||
***Default Value: true | ***Default Value: true | ||
===setRelativePath()=== | |||
Attempts to set the path for which all files are referenced relative to. not implemented for unix. This is mainly used for the usb-toolkit on windows: | |||
*Signature: static public function setRelativePath($path) | |||
*Parameters: | |||
** [http://www.php.net/manual/en/language.types.string.php string ] $path | |||
[[Category:Class Documentation]] | [[Category:Class Documentation]] |
Revision as of 16:14, 29 October 2009
This article describes the class I2CE_FileSearch.
- Child Classes:
- Location: Part of the module I2CE in the package I2CE
- Source: Defined in the file lib/I2CE_FileSearch.php
Class to handle file searching.
Variables
$relative_path
If not null, it is the file system path that all paths are attempted to resolve to. If null, all resolved paths are absolute @protected static string $relative_path
- Type: static protected $relative_path
$relative_root
The root drive of the relative path e.g. "C:" on windows or '/' on unix. on windows unix it may or may not contains the trailing "\" due to the following maddness: *realpath(C:) is C:\ *realpath(C:\) is C:\ *realpath(C:\\) is C:\ *realpath(C:\some) is C:\some *realpath(C:\some\) is C:\some @protected static string $relative_root
- Type: static protected $relative_root
$relative_parts
The parts of the relative path. On windows, it does not include the drive letter. @protected static array of string $relative_parts
- Type: static protected $relative_parts
$found_locales
The found locale(s) . One of: FALSE, a string, or an array. The former two in the case of a single serach, the later in case of a $find_all search
- Type: protected mixed $found_locales
$preferred_locales
. Keys are categories. Values are arrrays of string, the preferred locales.
- Type: protected array $preferred_locales
$ordered_paths
- Type: protected $ordered_paths
$absolut
protected $var boolean $absolut -- wheter or not to make relative paths absolut based on the directory of the calling file
- Type: protected $absolut
protected $var boolean $search_hidden. Whether or not to search hidden sub-directories
- Type: protected $search_hidden
$search_cwd
protected @var boolean $search_cwd. Whether or not to seach the current working directory
- Type: protected $search_cwd
$last_order
protected @var array $last_order values are the order of the last thing added to the category keys are the classes.
- Type: protected $last_order
$checked_directories
protected @var array $checked_directories array with keys directories and values boolean It is true if the directory has already been checked. Used to avoid recursion,
- Type: protected $checked_directories
Methods
__construct()
Constructor for the FileSearch class
- Signature: public function __construct($hidden,$current_working,$make_absolut)
- Parameters:
- boolean $hidden
Defaults to false. Whether or not to search hidden sub-directories. At the moment it does not have meaning on non unix like platforms.- Default Value: false
- boolean $current_working
Defaults to false. Whether or not to search the current working directory for the file. If so, it checks there first, before the other paths.- Default Value: false
- boolean $make_absolut
Defaults to false. Whether or not to make a relative path absolute when adding it.- Default Value: false
- boolean $hidden
_resolve()
Function to search through a list of paths to find a specified file.
- Signature: protected function _resolve($regExps,$paths,$find_all,$dir_prefix,$reset_found_locales)
- Parameters:
- array $regExps
If desired_file is null then, then $regExp is a list of regular expression to match file names on. - array $paths
of string. The keys are the paths we want to search, the values are the locale they are in - boolean $find_all
If true we find all files, otherwise we return on the first match - string $dir_prefix
any directory we want to prepend onto the file name.- Default Value:
- boolean $reset_found_locales
Defualts to false- Default Value: false
- array $regExps
absolut()
Makes a relative file path or file url absolute relative to the directory that the function was called in.
- Signature: static public function absolut($path,$indx)
- Parameters:
- Returns: string
the absolute path or URL
addPath()
A path to search for a category of files.
- Signature: public function addPath($category,$path,$order,$absolut,$path_prefix,$locales)
- Parameters:
- string $category
the category of files. - string $path
the parh (or glob pattern for a path) to add. There a a few modifications to the globbing... A trailing '**' means that the paths should be added recursivley Paths are automatically checked for localized version by the presence of a 'en_US' subdirectory. specifically, if a path is added such as /my/path and there is a subdir called /my/path/en_US then all subdirectories which are in the preffered locales (or $locales below) are added. Examples: /usr/share/fonts/ adds in this directory to the search paths /usr/share/fonts/* adds in all subdirectories /usr/share/fonts/** recusively adds in all subdirecties /usr/share/fonts/truetype/ttf* adds in all directories begining with ttf - mixed $order
If it is a number, then it indicates the order in which this path is searched. The lower the number, the higher the priority. If multiple paths share the same order, the order in which they are searched is not specfied The are also special string values of $order (all are relative to the category specified):- 'LAST' -- add at the last added order
- 'LOWEST' -- add so it has the lowest order thus far
- 'HIGHEST' -- add so it has the highest order thus far
- 'EVEN_LOWER' -- add so it has lower order than anything thus far. This is the default behavior
- 'EVEN_HIGHER' -- add so it has higher order than anything thus far
- Default Value: 'EVEN_LOWER'
- boolean $absolut
whether or not to try to make a relative path absolut. It will overide (but not change) the global behaviour of this instance.- Default Value: null
- string $path_prefix
Defaults to null. Any prefix to add to a local class path (if we do make absolute)- Default Value: null
- mixed $locales
null(default) , string or array of string. Used to override the default locale settings when not the defaults of null. It is the list of localized sub-directories to search for, if the given glob is a subdirectory.- Default Value: null
- string $category
changeRelativeToAbsolut()
Set whether or not to make relative paths absolute
- Signature: public function changeRelativeToAbsolut($absolut)
- Parameters:
- boolean $absolut
convertUnixToWin()
Convert a relative windows path with / to one with \
- Signature: static public function convertUnixToWin($path)
- Parameters:
- string $path returns $string
findByRegularExpression()
Finds all files with a given extension in the category
- Signature: public function findByRegularExpression($category,$regExps,$find_all,$dir_prefix)
- Parameters:
- string $category
- mixed $regExps
It may be a string, in which case it is a regular expression to match file names on. It may be an array of strings, them we attempt a match against each of the regular expressions specified by the strings. - boolean $find_all
If true we find all files, otherwise we return on the first match - string $dir_prefix
any directory we want to prepend onto the file name.- Default Value:
- Returns: array
of string
findWinShortFileName()
On windows, convert a given file in a given directory to a 8.3 filename
- Signature: static protected function findWinShortFileName($file,$dir)
- Parameters:
- string $file
- $dir
- Returns: string
findWinShortPathName()
Attempt to convert a windows long path name to its 8.3 version
- Signature: static public function findWinShortPathName($file)
- Parameters:
- string $file
The absoluate path to a file/directory
- string $file
- Returns: @string Example: C:\Program Files\my_long_dir becomes c:\program~1\my_lon~1
getCategories()
Get the categories specified
- Signature: public function getCategories()
- Returns: array
of string
getLastOrder()
Get the last order set for the specified category.
getLocaleOfLastSearch()
Get the locale(s) of the results of the last search.
- Signature: public function getLocaleOfLastSearch()
- Returns: mixed.
If the last search has $find_all = false then either false if no file was found or a string, the locale in which the the results was found. If the $find_all was true, then it is an array of string, the locales of the files found.
getParts()
Returns the parts of a path split up according to the directory spearator. Does _not_ check to see if the given $path is valid
- Signature: static public function getParts($path,$dir_sep,$esc_char,$ignore_empty)
- Parameters:
- string $path @param mixed string $dir_sep. chracter or array of charaterds. Defautls to DIRECTORY_SEPARATOR. A single character used as the directory sepearator
- $dir_sep
- Default Value: DIRECTORY_SEPARATOR
- string $esc_char
Defautls to '\' if $dir_sep is '/' and detaults to none if the $dir_sep is '\'. Set it to false if you don't want any escape characters- Default Value: null
- boolean $ignore_empty
If true (default), we dont add "empty" parts e.g. C:\some\\path returns array('c:','some','path'). Exmaple: \toolkit\path returns array('toolkit','path')- Default Value: true
- Returns: $array
getRelativePath()
Returns the path which all files are attempted to resolve relative to
- Signature: static public function getRelativePath()
- Returns: mixed
string, the path, or null if there is no relative path
getRootPath()
Attempts to get the base directory of the given path. On unix (or non-windows) this is always '/' On windows it is the drive with colon and no trailing slash, e.g. 'E:'
- Signature: static public function getRootPath($path)
- Parameters:
- string $path
An absolute path
- string $path
- Returns: mixed.
A string on success, null on failure
getSearchPath()
Gets the search path for the specified catgegory
- Signature: public function getSearchPath($category,$localized)
- Parameters:
- Returns: array.
If not localized with keys integers, the orders, and values an array of strings, the paths for that order, if $localized is TRUE, and keys are paths values are locales.
isAbsolut()
Checks to see if a path is absolute. All files identified by a URI/L are considered to be absolute
- Signature: static public function isAbsolut($path)
- Parameters:
- $path
- Returns: boolean
limitToSubdir()
Remove sub-directories from a category
- Signature: public function limitToSubdir($category,$limit)
- Parameters:
- Returns: array
List of directories
realPath()
Gets the real path, realpath(), of a given path on unix. On windows, if the relative path is not set, then this is just realpath(), otherwise it tries to resolve it as a path relative to the $relative_root return mixed. String or false on failure
- Signature: static public function realPath($path)
- Parameters:
- $path
relativePath()
Gets the relative real path of a given path on a windows box. If the relative path is not set, then this is just realpath(), otherwise it tries to resolve it as a path relative to the $relative_root See windows path conventions.
- Signature: static public function relativePath($path)
- Parameters:
- string $path return mixed. String or false on failure
removePath()
Remove a path in a category
- Signature: public function removePath($category,$path,$absolut,$path_prefix)
- Parameters:
- string $category
- string $path
- boolean $absolut
whether or not to try to make a relative path absolut. It will overide (but not change) the global behaviour of this instance.- Default Value: FALSE
- string $path_prefix
Defaults to null. Any prefix to add to a relative class path (if we do make absolute)- Default Value: NULL
removePaths()
Remove a list of paths from the category path list.
- Signature: public function removePaths($category,$path_list)
- Parameters:
- Returns: array
List of directories
reset()
- Signature: public function reset()
resetFoundLocales()
Reset the found locales
- Signature: protected function resetFoundLocales($multiple)
- Parameters:
- boolean $multiple
If true setup so we are returning multiple resutls. otherwise we return a single result
- boolean $multiple
resolve()
Function to search through a list of paths to find a specified file.
- Signature: public function resolve($regExps,$paths,$find_all,$dir_prefix,$reset_found_locales)
- Parameters:
- array $regExps
If desired_file is null then, then $regExp is a list of regular expression to match file names on. - array $paths
of string. The keys are the paths we want to search, the values are the locale they are in - boolean $find_all
If true we find all files, otherwise we return on the first match - string $dir_prefix
any directory we want to prepend onto the file name.- Default Value:
- boolean $reset_found_locales
Defualts to false- Default Value: false
- array $regExps
search()
Find a file (or directory) of a certain category
- Signature: public function search($category,$filename,$find_all)
- Parameters:
- Returns: mixed.
Returns either a string which is the path and file name of the file we found, or null if we did not find the file, or an array of file names if $find_all was set to true
searchCurrentWorkingDirectory()
- Signature: public function searchCurrentWorkingDirectory($search)
- Parameters:
- $search
searchHiddenSubdirectories()
- Signature: public function searchHiddenSubdirectories($search)
- Parameters:
- $search
searchPaths()
Search paths for matches to the regular expression
- Signature: public function searchPaths($find_all,$regExps,$paths,$prefix)
- Parameters:
- Returns: array
List of directories
setPreferredLocales()
Set the preferred locale(s) for a category. If not set, defaults the locales default to I2CE::DEFAULT_LOCALE
- Signature: public function setPreferredLocales($category,$locales,$validate)
- Parameters:
setRelativePath()
Attempts to set the path for which all files are referenced relative to. not implemented for unix. This is mainly used for the usb-toolkit on windows:
- Signature: static public function setRelativePath($path)
- Parameters:
- string $path