Natural Docs Version 0.9 |
NaturalDocs:: FileA 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. Read the “Why oh why?” sections for why this package was necessary. Usage and Dependencies
Summary
JoinPath
Joins two paths. Parameters
ReturnsThe joined path. Why oh why?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. MakeRelativePath
Takes two paths and returns a relative path between them. Parameters
If both paths are relative, they are assumed to be relative to the same base. ReturnsThe target path relative to base. Why oh why?Wow, where to begin? First of all, there’s nothing that gives a relative path between two relative paths. Second of all, 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 of all, 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 fucking 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. Morons. Update: This last one appears to be fixed in File::Spec 0.83, but that version isn’t even listed on CPAN. Lovely. Apparently it just comes with ActivePerl. Somehow I don’t think most Linux users are using that. NoFileName
Takes a path and returns a version without the file name. Useful for sending paths to CreatePath(). CreatePath
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. SplitDirectories
Takes a string of directories and returns an array of its elements. Why oh why?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. Morons. |