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. Read the “Why oh why?” sections for why this package was necessary.

Usage and Dependencies

The package doesn’t depend on any other Natural Docs packages and is ready to use immediately.
All functions except CanonizePath() assume that all parameters are canonized.

Summary

NaturalDocs:: File	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.
Disk Functions
CreatePath	Creates a directory tree corresponding to the passed path, regardless of how many directories do or do not already exist.
Copy	Copies a file from one path to another.

CheckCompatibility

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.

Path String Functions

CanonizePath

sub CanonizePath #(path)

Takes a path and returns a logically simplified version of it.

Why oh why?

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.

PathIsAbsolute

sub PathIsAbsolute #(path)

Returns whether the passed path is absolute.

JoinPath

sub JoinPath #	(	volume,
		dirString,
		$file	)

Creates a path from its elements.

Parameters

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.

Returns

The joined path.

JoinPaths

sub JoinPaths #	(	basePath,
		extraPath,
		noFileInExtra	)

Joins two paths.

Parameters

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.

Returns

The 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.

SplitPath

sub SplitPath #	(	path,
		noFile	)

Takes a path and returns its elements.

Parameters

path	The path to split.
noFile	Set to true if the path doesn’t have a file at the end.

Returns

The array ( volume, directoryString, file ). If any don’t apply, they will be undef. Use SplitDirectories() to split the directory string if desired.

Why oh Why?

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.

JoinDirectories

sub JoinDirectories #	(	directory,
		directory,
		...	)

Creates a directory string from an array of directory names.

Parameters

SplitDirectories

sub SplitDirectories #(directoryString)

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.

MakeRelativePath

sub MakeRelativePath #	(	basePath,
		targetPath	)

Takes two paths and returns a relative path between them.

Parameters

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.

Returns

The 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.

IsSubPathOf

sub IsSubPathOf #	(	base,
		path	)

Returns whether the path is a descendant of another path.

Parameters

base	The base path to test against.
path	The possible subpath to test.

Returns

Whether path is a descendant of base.

ConvertToURL

sub ConvertToURL #(path)

Takes a relative path and converts it from the native format to a relative URL. Note that it doesn’t convert special characters to amp chars.

NoUpwards

sub NoUpwards #(array)

Takes an array of directory entries and returns one without all the entries that refer to the parent directory, such as ‘.’ and ‘..’.

NoFileName

sub NoFileName #(path)

Takes a path and returns a version without the file name. Useful for sending paths to CreatePath().

Disk Functions

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.

Copy

sub Copy #	(	source,
		destination	)

Copies a file from one path to another. If the destination file exists, it is overwritten.

Parameters

source	The file to copy.
destination	The destination to copy to.

sub CheckCompatibility

Checks if the standard packages required by this one are up to snuff and dies if they aren’t.

sub CanonizePath #(path)

Takes a path and returns a logically simplified version of it.

sub PathIsAbsolute #(path)

Returns whether the passed path is absolute.

sub JoinPath #	(	volume,
		dirString,
		$file	)

Creates a path from its elements.

sub JoinPaths #	(	basePath,
		extraPath,
		noFileInExtra	)

Joins two paths.

sub SplitPath #	(	path,
		noFile	)

Takes a path and returns its elements.

sub JoinDirectories #	(	directory,
		directory,
		...	)

Creates a directory string from an array of directory names.

sub SplitDirectories #(directoryString)

Takes a string of directories and returns an array of its elements.

sub MakeRelativePath #	(	basePath,
		targetPath	)

Takes two paths and returns a relative path between them.

sub IsSubPathOf #	(	base,
		path	)

Returns whether the path is a descendant of another path.

sub ConvertToURL #(path)

Takes a relative path and converts it from the native format to a relative URL.

sub NoUpwards #(array)

Takes an array of directory entries and returns one without all the entries that refer to the parent directory, such as ‘.’

sub NoFileName #(path)

Takes a path and returns a version without the file name.

sub CreatePath #(path)

Creates a directory tree corresponding to the passed path, regardless of how many directories do or do not already exist.

sub Copy #	(	source,
		destination	)

Copies a file from one path to another.