A package to manage file access across platforms. Incorporates functions from various standard File:: packages, but more importantly, works around the glorious suckage present in File::Spec, at least in version 0.82 and earlier. Read the “Why oh why?” sections for why this package was necessary.
| NaturalDocs:: | A package to manage file access across platforms. |
| CheckCompatibility | Checks if the standard packages required by this one are up to snuff and dies if they aren’t. |
| Path String Functions | |
| CanonizePath | Takes a path and returns a logically simplified version of it. |
| PathIsAbsolute | Returns whether the passed path is absolute. |
| JoinPath | Creates a path from its elements. |
| JoinPaths | Joins two paths. |
| SplitPath | Takes a path and returns its elements. |
| JoinDirectories | Creates a directory string from an array of directory names. |
| SplitDirectories | Takes a string of directories and returns an array of its elements. |
| MakeRelativePath | Takes two paths and returns a relative path between them. |
| IsSubPathOf | Returns whether the path is a descendant of another path. |
| ConvertToURL | Takes a relative path and converts it from the native format to a relative URL. |
| NoUpwards | Takes an array of directory entries and returns one without all the entries that refer to the parent directory, such as ‘.’ |
| NoFileName | Takes a path and returns a version without the file name. |
| NoExtension | Returns the path without an extension. |
| ExtensionOf | Returns the extension of the passed path, or undef if none. |
| IsCaseSensitive | Returns whether the current platform has case-sensitive paths. |
| Disk Functions | |
| CreatePath | Creates a directory tree corresponding to the passed path, regardless of how many directories do or do not already exist. |
| RemoveEmptyTree | Removes an empty directory tree. |
| Copy | Copies a file from one path to another. |
sub CheckCompatibility
Checks if the standard packages required by this one are up to snuff and dies if they aren’t. This is done because I can’t tell which versions of File::Spec have splitpath just by the version numbers.
sub CanonizePath #( path )
Takes a path and returns a logically simplified version of it.
Because File::Spec->canonpath doesn’t strip quotes on Windows. So if you pass in “a b\c” or “a b”\c, they still end up as different strings even though they’re logically the same.
It also doesn’t remove things like “..”, so “a/b/../c” doesn’t simplify to “a/c” like it should.
sub JoinPath #( volume, dirString, $file )
Creates a path from its elements.
| volume | The volume, such as the drive letter on Windows. Undef if none. |
| dirString | The directory string. Create with JoinDirectories() if necessary. |
| file | The file name, or undef if none. |
The joined path.
sub JoinPaths #( basePath, extraPath, noFileInExtra )
Joins two paths.
| basePath | May be a relative path, an absolute path, or undef. |
| extraPath | May be a relative path, a file, a relative path and file together, or undef. |
| noFileInExtra | Set this to true if extraPath is a relative path only, and doesn’t have a file. |
The joined path.
Because nothing in File::Spec will simply slap two paths together. They have to be split up for catpath/file, and rel2abs requires the base to be absolute.
sub SplitPath #( path, noFile )
Takes a path and returns its elements.
| path | The path to split. |
| noFile | Set to true if the path doesn’t have a file at the end. |
The array ( volume, directoryString, file ). If any don’t apply, they will be undef. Use SplitDirectories() to split the directory string if desired.
Because File::Spec->splitpath may leave a trailing slash/backslash/whatever on the directory string, which makes it a bit hard to match it with results from File::Spec->catdir.
sub SplitDirectories #( directoryString )
Takes a string of directories and returns an array of its elements.
Because File::Spec->splitdir might leave an empty element at the end of the array, which screws up both joining in ConvertToURL and navigation in MakeRelativePath.
sub MakeRelativePath #( basePath, targetPath )
Takes two paths and returns a relative path between them.
| basePath | The starting path. May be relative or absolute, so long as the target path is as well. |
| targetPath | The target path. May be relative or absolute, so long as the base path is as well. |
If both paths are relative, they are assumed to be relative to the same base.
The target path relative to base.
First, there’s nothing that gives a relative path between two relative paths.
Second, if target and base are absolute but on different volumes, File::Spec->abs2rel creates a totally non-functional relative path. It should return the target as is, since there is no relative path.
Third, File::Spec->abs2rel between absolute paths on the same volume, at least on Windows, leaves the drive letter on. So abs2rel(‘a:\b\c\d’, ‘a:\b’) returns ‘a:c\d’ instead of the expected ‘c\d’. That makes no sense whatsoever. It’s not like it was designed to handle only directory names, either; the documentation says ‘path’ and the code seems to explicitly handle it. There’s just an ‘unless’ in there that tacks on the volume, defeating the purpose of a relative path and making the function worthless.
sub NoFileName #( path )
Takes a path and returns a version without the file name. Useful for sending paths to CreatePath().
sub CreatePath #( path )
Creates a directory tree corresponding to the passed path, regardless of how many directories do or do not already exist. Do not include a file name in the path. Use NoFileName() first if you need to.
sub RemoveEmptyTree #( path, limit )
Removes an empty directory tree. The passed directory will be removed if it’s empty, and it will keep removing its parents until it reaches one that’s not empty or a set limit.
| path | The path to start from. It will try to remove this directory and work it’s way down. |
| limit | The path to stop at if it doesn’t find any non-empty directories first. This path will not be removed. |
Checks if the standard packages required by this one are up to snuff and dies if they aren’t.
sub CheckCompatibility
Takes a path and returns a logically simplified version of it.
sub CanonizePath #( path )
Returns whether the passed path is absolute.
sub PathIsAbsolute #( path )
Creates a path from its elements.
sub JoinPath #( volume, dirString, $file )
Joins two paths.
sub JoinPaths #( basePath, extraPath, noFileInExtra )
Takes a path and returns its elements.
sub SplitPath #( path, noFile )
Creates a directory string from an array of directory names.
sub JoinDirectories #( directory, directory, ... )
Takes a string of directories and returns an array of its elements.
sub SplitDirectories #( directoryString )
Takes two paths and returns a relative path between them.
sub MakeRelativePath #( basePath, targetPath )
Returns whether the path is a descendant of another path.
sub IsSubPathOf #( base, path )
Takes a relative path and converts it from the native format to a relative URL.
sub ConvertToURL #( path )
Takes an array of directory entries and returns one without all the entries that refer to the parent directory, such as ‘.’
sub NoUpwards #( array )
Takes a path and returns a version without the file name.
sub NoFileName #( path )
Returns the path without an extension.
sub NoExtension #( path )
Returns the extension of the passed path, or undef if none.
sub ExtensionOf #( path )
Returns whether the current platform has case-sensitive paths.
sub IsCaseSensitive
Creates a directory tree corresponding to the passed path, regardless of how many directories do or do not already exist.
sub CreatePath #( path )
Removes an empty directory tree.
sub RemoveEmptyTree #( path, limit )
Copies a file from one path to another.
sub Copy #( source, destination ) => bool