/* * File: filelib.h * --------------- * This file exports a standardized set of tools for working with * files. The library offers at least some portability across the * file systems used in the three supported platforms: Mac OSX, * Windows, and Linux. Directory and search paths are allowed to * contain separators in any of the supported styles, which usually * makes it possible to use the same code on different platforms. */ #ifndef _filelib_h #define _filelib_h #include #include #include #include #include "vector.h" /* * Function: openFile * Usage: if (openFile(stream, filename)) ... * ------------------------------------------ * Opens the filestream stream using the specified * filename. This function is similar to the open * method of the stream classes, but uses a C++ string * object instead of the older C-style string. If the operation * succeeds, openFile returns true; * if it fails, openFile sets the failure flag in the * stream and returns false. */ bool openFile(std::ifstream & stream, std::string filename); bool openFile(std::ofstream & stream, std::string filename); /* * Function: promptUserForFile * Usage: string filename = promptUserForFile(stream, prompt); * ----------------------------------------------------------- * Asks the user for the name of a file. The file is opened using * the reference parameter stream, and the function * returns the name of the file. If the requested file cannot be * opened, the user is given additional chances to enter a valid file. * The optional prompt argument provides an input prompt * for the user. */ std::string promptUserForFile(std::ifstream & stream, std::string prompt = ""); std::string promptUserForFile(std::ofstream & stream, std::string prompt = ""); /* * Function: openFileDialog * Usage: string filename = openFileDialog(stream); * string filename = openFileDialog(stream, title); * string filename = openFileDialog(stream, title, path); * ------------------------------------------------------------- * Opens a dialog that allows the user to choose the file. The * title parameter is displayed in the dialog title. * The path parameter is used to set the working directory; * if path does not appear, openFileDialog * uses the current directory. */ std::string openFileDialog(std::ifstream & stream); std::string openFileDialog(std::ifstream & stream, std::string title); std::string openFileDialog(std::ifstream & stream, std::string title, std::string path); std::string openFileDialog(std::ofstream & stream); std::string openFileDialog(std::ofstream & stream, std::string title); std::string openFileDialog(std::ofstream & stream, std::string title, std::string path); /* * Function: readEntireFile * Usage: readEntireFile(is, lines); * --------------------------------- * Reads the entire contents of the specified input stream into the * string vector lines. The client is responsible for * opening and closing the stream. The vector can be either an STL * vector or a Vector as defined in the * Stanford C++ libraries. */ void readEntireFile(std::istream & is, Vector & lines); void readEntireFile(std::istream & is, std::vector & lines); /* * Function: getRoot * Usage: string root = getRoot(filename); * --------------------------------------- * Returns the root of filename. The root consists * of everything in filename up to the last dot and * the subsequent extension. If no dot appears in the final component * of the filename, getRoot returns the entire name. */ std::string getRoot(std::string filename); /* * Function: getExtension * Usage: ext = getExtension(filename); * ------------------------------------ * Returns the extension of filename. The extension * consists of the separating dot and all subsequent characters. * If no dot exists in the final component, getExtension * returns the empty string. These semantics ensure that concatenating * the root and the extension always returns the original filename. */ std::string getExtension(std::string filename); /* * Function: getHead * Usage: head = getHead(filename); * -------------------------------- * Returns all but the last component of a path name. The components * of the path name can be 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"     getTail("a/b")   = "b"
 *    getHead("a")    = ""      getTail("a")     = "a"
 *    getHead("/a")   = "/"     getTail("/a")    = "a"
 *    getHead("/")    = "/"     getTail("/")     = ""
 *
*/ std::string getHead(std::string filename); /* * Function: getTail * Usage: tail = getTail(filename); * -------------------------------- * Returns the last component of a path name. The components of the * path name can be separated by any of the directory path separators * (forward or reverse slashes). For details on the interpretation of * special cases, see the comments for the getHead function. */ std::string getTail(std::string filename); /* * Function: defaultExtension * Usage: string newname = defaultExtension(filename, 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. */ std::string defaultExtension(std::string filename, std::string ext); /* * Function: openOnPath * Usage: string pathname = openOnPath(stream, path, filename); * ------------------------------------------------------------ * Opens a file using a search path. If openOnPath * is successful, it returns the first path name on the search path * for which stream.open succeeds. The path * argument consists of a list of directories that are prepended to the * filename, unless filename begins with an absolute * directory marker, such as / or ~. * The directories in the search path may be separated either * by colons (Unix or Mac OS) or semicolons (Windows). If the file * cannot be opened, the failure bit is set in the stream * parameter, and the openOnPath function returns the * empty string. */ std::string openOnPath(std::ifstream & stream, std::string path, std::string filename); std::string openOnPath(std::ofstream & stream, std::string path, std::string filename); /* * Function: findOnPath * Usage: string pathname = findOnPath(path, filename); * ---------------------------------------------------- * Returns the canonical name of a file found using a search path. * The findOnPath function is similar to * openOnPath, except that it doesn't actually * return an open stream. If no matching file is found, * findOnPath returns the empty string. */ std::string findOnPath(std::string path, std::string filename); /* * Function: deleteFile * Usage: deleteFile(filename); * ---------------------------- * Deletes the specified file. Errors are reported by calling * error. */ void deleteFile(std::string filename); /* * Function: renameFile * Usage: renameFile(oldname, newname); * ------------------------------------ * Renames a file. Errors are reported by calling * error in the implementation. */ void renameFile(std::string oldname, std::string newname); /* * Function: fileExists * Usage: if (fileExists(filename)) ... * ------------------------------------ * Returns true if the specified file exists. */ bool fileExists(std::string filename); /* * Function: isFile * Usage: if (isFile(filename)) ... * -------------------------------- * Returns true if the specified file is a regular file. */ bool isFile(std::string filename); /* * Function: isSymbolicLink * Usage: if (isSymbolicLink(filename)) ... * ---------------------------------------- * Returns true if the specified file is a symbolic link. */ bool isSymbolicLink(std::string filename); /* * Function: isDirectory * Usage: if (isDirectory(filename)) ... * ------------------------------------- * Returns true if the specified file is a directory. */ bool isDirectory(std::string filename); /* * Function: setCurrentDirectory * Usage: setCurrentDirectory(filename); * ------------------------------------- * Changes the current directory to the specified path. */ void setCurrentDirectory(std::string path); /* * Function: getCurrentDirectory * Usage: string filename = getCurrentDirectory(); * ----------------------------------------------- * Returns an absolute filename for the current directory. */ std::string getCurrentDirectory(); /* * Function: createDirectory * Usage: createDirectory(path); * ----------------------------- * Creates a new directory for the specified path. 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 path does * not exist, this function signals an error. */ void createDirectory(std::string path); /* * Function: createDirectoryPath * Usage: createDirectoryPath(path); * --------------------------------- * Creates a new directory for the specified path. If intermediate * components of path do not exist, this function creates * them as needed. */ void createDirectoryPath(std::string path); /* * Function: expandPathname * Usage: string pathname = expandPathname(filename); * -------------------------------------------------- * Expands a filename into a canonical name for the platform. */ std::string expandPathname(std::string filename); /* * Function: listDirectory * Usage: listDirectory(path, list); * --------------------------------- * Adds an alphabetized list of the files in the specified directory * to the string vector list. This list excludes the * names . and .. entries. */ void listDirectory(std::string path, Vector & list); void listDirectory(std::string path, std::vector & list); /* * Function: matchFilenamePattern * Usage: if (matchFilenamePattern(filename, 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. */ bool matchFilenamePattern(std::string filename, std::string pattern); /* * Function: getDirectoryPathSeparator * Usage: string sep = getDirectoryPathSeparator(); * ------------------------------------------------ * Returns the standard directory path separator used on this platform. */ std::string getDirectoryPathSeparator(); /* * Function: getSearchPathSeparator * Usage: string sep = getSearchPathSeparator(); * --------------------------------------------- * Returns the standard search path separator used on this platform. */ std::string getSearchPathSeparator(); #include "private/main.h" #endif