The NeL framework provides a wealth of tools for both local and virtual file system manipulation and creation. In this section we'll cover the utility singletons CPath and CFile, reading and writing files on the local filesystem and the how to create and access the two virtual filesystems: BNP (Big Files) and XML Pack.
There are two core tools for managing paths and files: CPath and CFile. The CPath singleton is a designed to abstract file-system operations and searches on a high level, including logical virtual filesystems. The CFile singleton is more low-level and designed for direct, local operating system access.
The CFile utility is tremendously useful when you need lower level direct access to the local file systems. It is, for the most part, an informational class providing various methods to retrieve a filename (separated from the path,) a path (separated from the filename,) file size and permissions. But it also includes some tremendously useful methods for file system operations such as copyFile() and method for file comparison and so on. Realistically checking the CFile API will provide more information than can be provided here but we will cover in a code example a couple simple scenarios.
std::string srcFile = "/home/me/test1/testfile.txt";
std::string othFIle = "/home/me/test1/test2.txt";
std::string tmpStr;
// Produces a string containing "testfile.txt"
tmpStr = CFile::getFilename(srcFile);
// Produces a string containing "/home/me/"
tmpStr = CFile::getPath(srcFile);
// Produces a string containing "txt"
tmpStr = CFile::getFileExtension(srcFile);
// This check only works for files on the local system, not files in BNP or XML Packs.
if(!CFile::isDirectory(srcFile) && CFile::fileExists(srcFile))
{
// Note: getFileSize and getFileCreationDate use CPath and will work on BNP and XML Packs.
nlinfo("this file is %d bytes and was created on %d (seconds from epoch,) last modified on %d (seconds from epoch).",
CFile::getFileSize(srcFile),
CFile::getFileCreationDate(srcFile),
CFIle::getFileModificationDate(srcFile));
// Also has the ability to manipulate local directories and files.
// Make sure we can write to this file.
CFile::setRWAccess(srcFile);
// Create a new directory. Also createDirectoryTree creates several branches deep.
CFile::createDirectory("/home/me/test2");
// Copy our srcFile to the new directory.
CFile::copyFile("/home/me/test2", srcFile);
// Delete the old srcFile
CFile::deleteFile(srcFile);
srcFile="/home/me/test2/testfile.txt";
// Move our other file.
CFile::moveFile("/home/me/test2", othFile);
// Finally delete the old directory.
CFile::deleteDirectory("/home/me/test1");
}
The above example really covers the vast majority of uses of this utility. There are a couple advanced items that are important to note: temporary file creation and file callbacks.
The CFile utility provides a method called getTemporaryOutputFilename(src,dest). You provide the method with a source file name and it will update the argument dest with a unique filename: e.g. testfile.txt becomes testfile.txt.tmp. Subsequently calls to the method will then begin to produce testfile.txt.tmp.1 and testfile.txt.tmp.2 and so on.
The file callbacks are a useful way to monitor whether a file has changed. To harness this you need to create a function that accepts a string argument and then use the addFileChangeCallback method. Here is a quick example.
void fileChanged(const std::string &filename)
{
nlinfo("The following file has changed: %s", filename.c_str());
}
int main (int argc, char **argv)
{
createDebug();
CFile::addFileChangeCallback("testfile.txt");
// .. do some logic, maybe change the file...
// finally cleanup at exit:
CFile::removeFileChangeCallback("testfile.txt");
}
This utility is the most commonly used utility in the NeL file toolbox. It creates a logical layer above the physical file system and any virtual file systems such as Big Files and XML Packs. The goal is to provide developers with as simple an interface as possible and still maintain a high level of transparency and usability. In the course of typical usage you will first add search paths, possibly add some file or file extension remappings, perform lookups and finally you may have a need to reset the whole CPath object.
There are several methods at your disposal for adding search paths. You'll typically add a search path so that the system can find common datafiles, configuration files and so on. So it is important to add search paths early in the program execution. An important concept for search paths is the alternative directories options. These are directories that are added to the search order but pre-cached. This means that they will only be searched during lookups once all primary search paths have been exhausted.
dd
dd
dd
ddd