filelib.h

This interface exports a standardized set of tools for working with files across various platforms. It is implemented for each of the following platforms: Mac OSX, Windows, and Linux. Directory and search paths are allowed to contain separators in any of the supported styles, which often makes it possible to use the same code on different platforms.
Functions
getDirectoryPathSeparator() Returns the standard directory path separator used on this platform.
getSearchPathSeparator() Returns the standard search path separator used on this platform.
getRoot(filename) Returns the root of a filename.ext pair, which consists of everything in filename up to the last dot and the subsequent extension.
getExtension(filename) Returns the extension component of filename, which consists of the separating dot and all subsequent characters.
getHead(pathname) Returns all but the last component of a path name, where the components are names separated by any of the directory path separators (forward or reverse slashes).
getTail(pathname) Returns the last component of a path name, where the components are names separated by any of the directory path separators (forward or reverse slashes).
defaultExtension(filename, ext) Adds an extension to a file name if none already exists.
openOnPath(path, filename, mode) Opens a files by searching directories in a search path for the first matching file.
findOnPath(path, filename) Returns a canonical name of a file found using a search path.
deleteFile(filename) Deletes the specified file.
renameFile(oldname, newname) Renames a file.
fileExists(pathname) Returns true if the specified file exists.
isFile(pathname) Returns true if the specified file is a regular file.
isSymbolicLink(pathname) Returns true if the specified file is a symbolic link.
isDirectory(pathname) Returns true if the specified file is a directory.
createDirectory(pathname) Creates a new directory for the specified pathname.
createDirectoryPath(pathname) Creates a new directory for the specified pathname.
setCurrentDirectory(pathname) Changes the current directory to the specified path.
getCurrentDirectory() Returns an absolute pathname for the current directory.
expandPathname(pathname) Expands a pathname into a canonical name for the platform.
listDirectory(dir) Returns an alphabetical list of all the files in the specified directory, excluding the unix . and .. entries.
newDirectoryIterator(dir) Creates a new directory iterator that will step through the files in the specified directory.
newDirectoryTreeIterator(dir) Creates a new directory iterator that will walk recursively through the files in the specified directory and its subdirectories.
matchFilenamePattern(filename, pattern) Determines whether the filename matches the specified pattern.
getFileType(filename) Gets the file type of a Macintosh file, which is a four-character string.
getFileCreator(filename) Gets the creator code of a Macintosh file, which is a four-character string.

Function detail


string getDirectoryPathSeparator(void);
Returns the standard directory path separator used on this platform.

Usage:

sep = getDirectoryPathSeparator();

string getSearchPathSeparator(void);
Returns the standard search path separator used on this platform.

Usage:

sep = getSearchPathSeparator();

string getRoot(string filename);
Returns the root of a filename.ext pair, which consists of everything in filename up to the last dot and the subsequent extension. If no dot appears, getRoot returns the entire name. the extension

Usage:

root = getRoot(filename);

string getExtension(string filename);
Returns the extension component of filename, which consists of the separating dot and all subsequent characters. If no dot exists in the final component, extension returns the empty string. Note that this interpretation is different than one used by the :e substitution in the shell. The semantics were chosen so that the expression
   concat(getRoot(filename), getExtension(filename))
is equal to the original filename.

Usage:

ext = getExtension(filename);

string getHead(string pathname);
Returns all but the last component of a path name, where the components are names separated by any of the directory path separators (forward or reverse slashes). The special cases are illustrated by the following examples:
   getHead("a/b")  = "a"
   getHead("a")    = ""
   getHead("/a")   = "/"
   getHead("/")    = "/"

Usage:

head = getHead(pathname);

string getTail(string pathname);
Returns the last component of a path name, where the components are names separated by any of the directory path separators (forward or reverse slashes). The special cases are illustrated by the following examples:
   getTail("a/b")   = "b"
   getTail("a")     = "a"
   getTail("/a")    = "a"
   getTail("/")     = ""

Usage:

tail = getTail(pathname);

string defaultExtension(string filename, string ext);
Adds an extension to a file name if none already exists. If the extension argument begins with a leading *, any existing extension in filename is replaced by ext.

Usage:

newname = defaultExtension(filename, ext);

FILE *openOnPath(string path, string filename, string mode);
Opens a files by searching directories in a search path for the first matching file. The openOnPath routine has the same structure as fopen in the standard library and the filename and mode arguments are the same as in that call. The path argument consists of a list of directories which are prepended to the filename, unless the filename begins with an absolute directory marker, such as / or ~. The directories in the search path may be separated either by colons (Unix style) or semicolons (Windows style). The openOnPath function returns an open stream to the indicated file, or NULL, if no existing file is found.

Usage:

FILE *file = openOnPath(path, filename, mode);

string findOnPath(string path, string filename);
Returns a canonical name of a file found using a search path. The findOnPath function is similar to openOnPath, except that it returns the name of the file instead of trying to open in. If no matching file is found, findOnPath returns NULL.

Usage:

pathname = findOnPath(path, filename);

void deleteFile(string filename);
Deletes the specified file. Errors are reported by calling error in the implementation.

Usage:

deleteFile(filename);

void renameFile(string oldname, string newname);
Renames a file. Errors are reported by calling error in the implementation.

Usage:

renameFile(oldname, newname);

bool fileExists(string pathname);
Returns true if the specified file exists.

Usage:

if (fileExists(pathname)) . . .

bool isFile(string pathname);
Returns true if the specified file is a regular file.

Usage:

if (isFile(pathname)) . . .

bool isSymbolicLink(string pathname);
Returns true if the specified file is a symbolic link.

Usage:

if (isSymbolicLink(pathname)) . . .

bool isDirectory(string pathname);
Returns true if the specified file is a directory.

Usage:

if (isDirectory(pathname)) . . .

void createDirectory(string pathname);
Creates a new directory for the specified pathname. The createDirectory function does not report an error if the directory already exists. Unlike createDirectoryPath, createDirectory does not create missing directories along the path. If some component of pathname does not exist, this function signals an error.

Usage:

createDirectory(pathname);

void createDirectoryPath(string pathname);
Creates a new directory for the specified pathname. If intermediate components of the pathname do not exist, this function creates them as needed.

Usage:

createDirectoryPath(pathname);

void setCurrentDirectory(string path);
Changes the current directory to the specified path.

Usage:

setCurrentDirectory(pathname);

string getCurrentDirectory(void);
Returns an absolute pathname for the current directory.

Usage:

pathname = getCurrentDirectory();

string expandPathname(string filename);
Expands a pathname into a canonical name for the platform.

Usage:

fullname = expandPathname(pathname);

string *listDirectory(string dir);
Returns an alphabetical list of all the files in the specified directory, excluding the unix . and .. entries. The array is terminated with a NULL entry.

Usage:

string array[] = listDirectory(dir);

Iterator newDirectoryIterator(string dir);
Creates a new directory iterator that will step through the files in the specified directory.

Usage:

foreach (name in newDirectoryIterator(dir)) . . .

Iterator newDirectoryTreeIterator(string dir);
Creates a new directory iterator that will walk recursively through the files in the specified directory and its subdirectories.

Usage:

foreach (name in newDirectoryTreeIterator(dir)) . . .

bool matchFilenamePattern(string filename, string pattern);
Determines whether the filename matches the specified pattern. The pattern string is interpreted in much the same way that a Unix shell expands filenames and supports the following wildcard options:

? Matches any single character
* Matches any sequence of characters
[...] Matches any of the specified characters
[^...] Matches any character except the specified ones

The last two options allow a range of characters to be specified in the form a-z.

Usage:

if (matchFilenamePattern(filename, pattern)) . . .

string getFileType(string filename);
Gets the file type of a Macintosh file, which is a four-character string. This function returns the string "????" on other platforms.

Usage:

type = getFileType(filename);

string getFileCreator(string filename);
Gets the creator code of a Macintosh file, which is a four-character string. This function returns the string "????" on other platforms.

Usage:

type = getFileCreator(filename);