A file's name and handle for invoking many file system functions. More...
#include <file.h>
Classes | |
struct | Accum |
An Accum object is a template class object whose role is to provide a generic interface for any standard sequence container to the accumulate_lines virtual interface. More... | |
struct | accumulate_lines |
A class of functor objects whose purpose is to provide a generic interface between the read_* functions, below, and some container used to hold lines read. More... | |
struct | FileNameSorter |
struct | is_separator |
A functor that tells you if a specifed character is a path sepator. It is meant to be used as a parameter to StrTool::parse_words -- or any function needing a predicate indicating that a character is the path separator. More... | |
class | Tree |
A tree of file names, representing a directory hierarcy. More... | |
Public Types | |
typedef rep_t::const_iterator | const_iterator |
const Iterator to characters in the filename | |
typedef rep_t::iterator | iterator |
mutable iterator to characters in the file name | |
typedef FileStatus::file_size_t | off_t |
The data type of the file's size. | |
typedef std::string | rep_t |
actual representation of the file's name | |
typedef std::set< FileName, FileNameSorter > | sorted_names_t |
Alphabetically sorted set of FileNames. | |
Public Member Functions | |
rep_t | basename (bool remove_extension=false) const |
Get the filename part of the pathname. | |
iterator | begin () |
Get a pointer to the first char in the name. | |
const_iterator | begin () const |
Get a pointer to the first char in the name. | |
char const * | c_str () const |
Get a old fashion C string from the filename. | |
bool | chmod (FileMode) const |
Set the mode (ie permissions, or attributes) on the file named by this to the mode specified. | |
void | convert_to_absolute_path () |
Adds the name of the current directory to a file name if it has no directory part specified. | |
void | convertToDirectorySearchPattern (char const *pattern="*") |
void | convertToDirectorySearchPattern (std::string const &pattern) |
Assume that this FileName is a directory name and add specified pattern to it to make it into a directory search pattern (or a simple filename if the pattern contains no wildcard characters). | |
bool | copy (FileName const &destination) const |
Copy the file whose name is specified '*this' into a new file whose name is specified in destination. | |
char const * | data () const |
Get a pointer to the non-nul terminated filename. | |
rep_t | dirname () const |
Get only the directory part of the pathname. | |
bool | empty () const |
return true if the filename is an emtpy string | |
iterator | end () |
Get a ptr to first char after name. | |
const_iterator | end () const |
Get a ptr to first char after name. | |
void | erase (size_t o) |
Erase the character at offset o. | |
void | erase (size_t o, size_t l) |
Erase l characters at offset o. | |
void | erase (iterator a, iterator b) |
Erase a range of characters. | |
void | erase (iterator a) |
Erase the character at location. | |
bool | exists () const |
FileName | expand_tildes () const |
rep_t | extension () const |
Get the file name extension part of the pathname. | |
FileMode | file_mode () const |
off_t | file_size () const |
bool | file_stat (FileStatus *s, bool l=false) const |
Get status of named file, return true if error. If the optional second parameter is 'true' then read the status of the link corresponding to the file name. The default is to read through the link to get the status of the file or directory to which the link points. | |
bool | file_time (FileTime *t) const |
Inquire the file time. | |
FileName (FileName const &r) | |
copy construct | |
FileName (std::string const &r) | |
construct from a string | |
FileName (char const *r) | |
construct form a char const* | |
FileName () | |
FileName() default constructor. | |
void | insert (size_t o, rep_t const &s) |
Insert a string at an offset. | |
void | insert (size_t o, char const *s) |
Insert a string at an offset. | |
void | insert (iterator a, char c) |
Insert a character at a location. | |
bool | is_absolute_path () const |
bool | is_createable () const |
bool | is_dir () const |
bool | is_executable () const |
bool | is_readable () const |
bool | is_root_dir () const |
bool | is_syntactically_valid () const |
bool | is_writeable () const |
bool | matches (rep_t pattern) const |
bool | matches (char const *pattern) const |
Does the filename match a given naming patttern (shell style). | |
bool | mkdir (FileMode m=FileMode(" drwxrwxrwx")) const |
Make a directory whose name is given by this filename. Return true if an error occurred. The 'directory' bit of the FileMode is assumed -- and thus ignored. | |
operator std::string & () | |
Convert to string &. | |
operator std::string const & () const | |
Convert to const string &. | |
FileName | operator+ (std::string const &r) const |
concatenate the filename with a std::string to make a new filename | |
FileName | operator+ (char const *r) const |
concatenate the filename with a c style string to make a new filename | |
FileName | operator+ (FileName const &r) const |
append a file name to this file name | |
FileName & | operator+= (std::string const &r) |
append a string to this file name | |
FileName & | operator+= (char c) |
append a character to this file name | |
FileName & | operator+= (char const *p) |
append a string to this file name | |
bool | operator< (std::string const &rhs) const |
Compare this filename's string component against. | |
template<class T > | |
FileName & | operator= (T const &rhs) |
Assign this FileName from some other string source. | |
bool | operator== (char const *rhs) const |
compare a filename to a c style string | |
bool | operator== (std::string const rhs) const |
compare a filename to a string | |
bool | operator== (FileName const rhs) const |
Compare two filenames. | |
char & | operator[] (size_t i) |
Get a ref to the character at a specified offset from the start of the string. | |
char | operator[] (size_t i) const |
Get the character at a specified offset from the start of the string. | |
template<class Container > | |
std::string | read_file (Container &container, size_t *line_count_ptr=0) |
Read a whole file into a container of std::string's. Return any error text as a std::string as well. If the return string is empty then no errors have occurred. | |
std::string | read_lines (accumulate_lines &accum, size_t *line_count_ptr=0, bool removeCR=false) |
This function lets you read lines from the file whose name contained in this filename very quickly. You probably want to use the FileName::read_file function below instead of calling this function. It simplifies the interface significantly. | |
FileName | readlink (int *returnedMode=0) const |
Assume that this filename refers to a symbolic link file and attempt to read through the link to get the name of the thing it points to. If the optional mode pointer is passed in also read the symbolic link's file mode and return it in *returnMode; Note that normally the FileMode of a symbolic link is a mix of the attributes of the link itself and the thing it points to. The mix works like this: | |
bool | remove () const |
Remove the file named by this FileName. | |
bool | rename (FileName const &destination) const |
Rename the file whose name is specified '*this' into a new file whose name is specified in destination. | |
bool | rmdir () const |
Remove the directory named by this filename. | |
std::string | shorten (int max_chars) const |
Produce a string which is a shortened version of the filename by deleting excess characters and inserting an elipses in the middle to signify missing characters. The name will not refer to a real file (unless by accident). | |
size_t | size () const |
Get length of string. | |
size_t | slurp (std::list< std::string > *lines) const |
Read the whole file (binary read) into a list of strings return the number of lines read. This is the fastest way to read a file into a bunch of strings. | |
void | slurp (FileContents *f) const |
Read whole file (binary read) into a FileContents object and set its error method correctly. | |
rep_t | substr (size_t s, size_t l) const |
Get a substring given a start ofset a number of characters. | |
std::auto_ptr< Tree > | tree (bool only_dirs=false) const |
Get the subdirectory tree starting with this filename. If this filename refers to a normal file, then tree will have only one node. If this does not refer to a valid file, one node will be returned but the 'status' will indicate that it is not a good file. If this FileName is a directory, then the sub-directory tree will be returned. If any node's status is not avaialable, its status will indicate that. | |
bool | write (char const *begin, char const *end, bool binary_mode=true) |
Open the file whose name is contained in this FileName object and write the data found between begin and end to the file in either ascii or binary mode depending on the binary_mode flag. On unix, this flag is ignored. The file will be created with default umask permission. | |
bool | write (std::string const &file_contents, bool binary_mode=true) |
Write a string to a newly create file whose name is the contained in this filename. If the file previously existed, it will be deleted then recreated. | |
Static Public Member Functions | |
static int | compareIgnoringPathSeparatorDifferences (std::string const &l, std::string const &r) |
static int | compareIgnoringPathSeparatorDifferences (char const *l, char const *r, size_t lsize, size_t rsize) |
static FileName | find_executable (std::string progname, std::string path="") |
Search the specified path, or the current PATH environment variable for the named program. | |
static FileName | find_file_in_path (std::string filename, std::string path="") |
Search a path for a given file -- executable or not. See find_executable for the general idea. This function, finds any file, not just executables. | |
static int | find_matching (rep_t pattern, sorted_names_t *l, int options=0) |
static int | find_matching (char const *pattern, sorted_names_t *matches, int options=0) |
A static method that finds a list of FileName's matching a specified pattern by reading the file system directory and comparing the file names to the requested pattern. | |
static FileName | getcwd () |
static function to get the current working directory as a filename | |
static FileName | mktemp (FileName dir="./") |
static function that will return a FileName with the name of a temporary file in the specified directory. | |
Static Public Attributes | |
static char | PATH_separator = ':' |
Either : or ; depending on the os This variable defines what character separates components of the PATH environment variable. | |
Private Member Functions | |
std::auto_ptr< Tree > | tree_helper (std::string const &path, bool only_dirs=false, int depth=0) const |
used by tree() to recurse through directory hierarchies | |
Private Attributes | |
rep_t | impl_ |
The string that is the file name. | |
Friends | |
std::string | operator+ (char const *lhs, FileName const &rhs) |
global free function to concatenate c style strings and filenames producing std::strings' | |
std::string | operator+ (std::string const &lhs, FileName const &rhs) |
global free function to concatenate strings and filenames, producing std::strings | |
bool | operator== (char const *lhs, FileName const &rhs) |
global free function to compare a c style string to a filename | |
bool | operator== (std::string const &lhs, FileName const &rhs) |
global free function to compare a std::string to a filename |
A file's name and handle for invoking many file system functions.
FileName is a generalized utility class for performing file operations. A FileName has much in common with std::string but adds many additional member functions that are associated with operating systems calls involving files:
Basically this class has everything in it but the kitchen sink.
A FileName is not a string, but it can be converted to a string &, or string const & with high speed.
Definition at line 490 of file file.h.
typedef rep_t::const_iterator const_iterator |
typedef rep_t::iterator iterator |
typedef FileStatus::file_size_t off_t |
typedef std::string rep_t |
typedef std::set<FileName, FileNameSorter> sorted_names_t |
FileName | ( | ) |
FileName() default constructor.
rep_t basename | ( | bool | remove_extension = false |
) | const |
iterator begin | ( | ) |
const_iterator begin | ( | ) | const |
char const* c_str | ( | ) | const |
bool chmod | ( | FileMode | mode | ) | const |
static int compareIgnoringPathSeparatorDifferences | ( | std::string const & | l, | |
std::string const & | r | |||
) | [static] |
static int compareIgnoringPathSeparatorDifferences | ( | char const * | l, | |
char const * | r, | |||
size_t | lsize, | |||
size_t | rsize | |||
) | [static] |
void convert_to_absolute_path | ( | ) |
void convertToDirectorySearchPattern | ( | char const * | pattern = "*" |
) |
Assume that this FileName is a directory name and add specified pattern to it to make it into a directory search pattern (or a simple filename if the pattern contains no wildcard characters). If this is a directory, or it ends in / or \, add * to the end as needed to make this a directory search pattern.
pattern | is the "*.c", or other pattern you are trying to construct from this directory. |
Definition at line 2449 of file file.cxx.
void convertToDirectorySearchPattern | ( | std::string const & | pattern | ) |
Assume that this FileName is a directory name and add specified pattern to it to make it into a directory search pattern (or a simple filename if the pattern contains no wildcard characters).
If this is a directory, or it ends in / or \, add * to the end as needed to make this a directory search pattern.
pattern | is the "*.c", or other pattern you are trying to construct from this directory. |
Definition at line 774 of file file.h.
bool copy | ( | FileName const & | destination | ) | const |
Copy the file whose name is specified '*this' into a new file whose name is specified in destination.
Directories cannot be copied using this function -- and error will result.
destination | The name of the file where the copy goes. |
Definition at line 1686 of file file.cxx.
char const* data | ( | ) | const |
rep_t dirname | ( | ) | const |
bool empty | ( | ) | const |
const_iterator end | ( | ) | const |
void erase | ( | size_t | o, | |
size_t | l | |||
) |
void erase | ( | iterator | a | ) |
bool exists | ( | ) | const |
FileName expand_tildes | ( | ) | const |
~/.bashrc becomes /home/user/.bashrc
and
~lboggs/.bashrc
becomes
/home/lboggs/.bashrc
Note that the prefix, /home/, is just an example. The real results will depend on the home directory of the specified user -- as determined by passwd() method.
Definition at line 2369 of file file.cxx.
string extension | ( | ) | const |
FileMode file_mode | ( | ) | const |
FileName::off_t file_size | ( | ) | const |
bool file_stat | ( | FileStatus * | s, | |
bool | l = false | |||
) | const |
Get status of named file, return true if error. If the optional second parameter is 'true' then read the status of the link corresponding to the file name. The default is to read through the link to get the status of the file or directory to which the link points.
[in] | s | The place to store the status of the file whose name is contained in *this. |
[in] | l | A default flag indicating that if the filename referes to a link the then data for the link should be read instead of for the link itself. Normally, this is not set, the default is the most desireable form. Only directory display programs need read the link itself. |
Definition at line 804 of file file.cxx.
bool file_time | ( | FileTime * | t | ) | const |
FileName find_executable | ( | std::string | progname, | |
std::string | path = "" | |||
) | [static] |
Search the specified path, or the current PATH environment variable for the named program.
progname | is the name of an executable to search for | |
path | is a platform specific directory path (unix: colon separated, windows: semicolon separated) |
How this works varies a bit from os to os. If no path is specified, or the path is an empty string, the current PATH environment variable will be used for the search. On Windows, the PATH variable is separated by spaces and semicolons but on unix it is separated by only colons. Further, on Windows, the program name may not include the file name extension which is one of .bat, .com, .exe, .cmd. On these systems, this will be automatically appended during the search.
Definition at line 1416 of file file.cxx.
FileName find_file_in_path | ( | std::string | filename, | |
std::string | path = "" | |||
) | [static] |
Search a path for a given file -- executable or not. See find_executable for the general idea. This function, finds any file, not just executables.
filename | is the name of the file to search for | |
path | is a directory search path dependend in form on the os you are on. |
Definition at line 1517 of file file.cxx.
static int find_matching | ( | rep_t | pattern, | |
sorted_names_t * | l, | |||
int | options = 0 | |||
) | [static] |
A static method that finds a list of FileName's matching a specified pattern by reading the file system directory and comparing the file names to the requested pattern.
pattern | is the search pattern: "*.exe", "/home/dir/files*.*", etc. | |
matches | is a set of strings into which to place the matching filenames. | |
options | is selector for the kinds of files you want to include -- see below. |
The 'options' parameter specifies flags to be interpreted with respect to the returned list of matching filenames. The value passed to options are a bit mask with the following intepretation:
0x00 -- all files are included in the output data but the results do not contain the pathnames specified in the pattern, only the basename's of the matches. 0x01 -- all files are included in the output data and the results _do_ contain the pathname specified in the pattern. 0x02 -- only directories are included but no paths are included. 0x03 -- only directories, and the paths are included. 0x04 -- NO directories are included and no paths are included 0x05 -- NO directories are included but the paths are.
int find_matching | ( | char const * | pattern, | |
sorted_names_t * | matches, | |||
int | options = 0 | |||
) | [static] |
A static method that finds a list of FileName's matching a specified pattern by reading the file system directory and comparing the file names to the requested pattern.
pattern | is the search pattern: "*.exe", "/home/dir/files*.*", etc. | |
matches | is a set of strings into which to place the matching filenames. | |
options | is selector for the kinds of files you want to include -- see below. |
The 'options' parameter specifies flags to be interpreted with respect to the returned list of matching filenames. The value passed to options are a bit mask with the following intepretation:
0x00 -- all files are included in the output data but the results do not contain the pathnames specified in the pattern, only the basename's of the matches. 0x01 -- all files are included in the output data and the results _do_ contain the pathname specified in the pattern. 0x02 -- only directories are included but no paths are included. 0x03 -- only directories, and the paths are included. 0x04 -- NO directories are included and no paths are included 0x05 -- NO directories are included but the paths are.
Definition at line 1080 of file file.cxx.
FileName getcwd | ( | ) | [static] |
void insert | ( | size_t | o, | |
rep_t const & | s | |||
) |
void insert | ( | size_t | o, | |
char const * | s | |||
) |
void insert | ( | iterator | a, | |
char | c | |||
) |
bool is_absolute_path | ( | ) | const |
bool is_createable | ( | ) | const |
bool is_dir | ( | ) | const |
bool is_executable | ( | ) | const |
bool is_readable | ( | ) | const |
bool is_root_dir | ( | ) | const |
bool is_syntactically_valid | ( | ) | const |
bool is_writeable | ( | ) | const |
bool matches | ( | rep_t | pattern | ) | const |
bool matches | ( | char const * | pattern | ) | const |
Does the filename match a given naming patttern (shell style).
pattern | is a file name search pattern: "*.c", etc. |
Definition at line 1027 of file file.cxx.
Make a directory whose name is given by this filename. Return true if an error occurred. The 'directory' bit of the FileMode is assumed -- and thus ignored.
Definition at line 1641 of file file.cxx.
static function that will return a FileName with the name of a temporary file in the specified directory.
dir | is the name of a directory where the temporary file will go. |
That is, this function produces the name of a file in the specified directory that does not yet exist -- for use in creating temporary files. The directory parameter is optional -- the default being the current directory.
When specifying a directory name, you must supply the trailing slash and you may also include a prefix for the file. Here are some valid examples:
FileName::mktemp(); FileName::mktemp("/tmp/"); FileName::mktemp("../../junk_");
Definition at line 1371 of file file.cxx.
operator std::string const & | ( | ) | const |
FileName operator+ | ( | std::string const & | r | ) | const |
FileName operator+ | ( | char const * | r | ) | const |
FileName& operator+= | ( | std::string const & | r | ) |
FileName& operator+= | ( | char | c | ) |
FileName& operator+= | ( | char const * | p | ) |
bool operator< | ( | std::string const & | rhs | ) | const |
FileName& operator= | ( | T const & | rhs | ) |
bool operator== | ( | char const * | rhs | ) | const |
bool operator== | ( | std::string const | rhs | ) | const |
bool operator== | ( | FileName const | rhs | ) | const |
char& operator[] | ( | size_t | i | ) |
char operator[] | ( | size_t | i | ) | const |
std::string read_file | ( | Container & | container, | |
size_t * | line_count_ptr = 0 | |||
) |
Read a whole file into a container of std::string's. Return any error text as a std::string as well. If the return string is empty then no errors have occurred.
container | can be any sequence container that should holds lines of text from the input file (as std::string) | |
line_count_ptr | is a pointer to the location where the count of read lines will be stored. |
This function differs from the FileName::slurp() method in that slurp reads the entire file into a single giant array of characters. This function reads it into a any container of std::strings which you define. Note that on large files, vector<std::string> gives you O(N) inserts whereast list<std::string> gives you O(1) inserts. A skiprope<std::string> would give you O(ln(N)) inserts as well as O(ln(N)) array indexing -- unlike the list which has none what so ever.
string read_lines | ( | FileName::accumulate_lines & | accum, | |
size_t * | line_count_ptr = 0 , |
|||
bool | removeCR = false | |||
) |
This function lets you read lines from the file whose name contained in this filename very quickly. You probably want to use the FileName::read_file function below instead of calling this function. It simplifies the interface significantly.
accum | is an container-wrapper that will hold the input data. | |
line_count_ptr | is an optional pointer to a size_t holding the count of read lines. | |
removeCR | is an optional boolean that tells the function to remove a trailing \r character, i |
You must create a FilenName::accumulate_lines object to serve as an interface to the container into which you are storing the read lines. The lines will be read in binary mode. The line separator, \n, will not be included in the strings returned -- nor will any single trailing \r (On unix you must set the removeCR flag to get the trailing \r removed. On windows, this is neither necessary nor helpful.)
This function returns a std::string contain any error message that might have occurred. If the return value is empty, then no error occurred.
Do not attempt to use the push_back method to do anything but accumulate lines. The read_lines algorithm handles very long lines, but it has a fixed size internal buffer. As the data is read from the file it is stored in this internal buffer. When a line exceeds the length of this buffer, partial lines will be pushed into the the container. The back() function will subsequently be called to get access to the most recently pushed partial line so that the partial line can be completed using the std::string::append method.
See the body of FileName::read() below for an example of using read_lines().
Definition at line 1991 of file file.cxx.
FileName readlink | ( | int * | returnedMode = 0 |
) | const |
Assume that this filename refers to a symbolic link file and attempt to read through the link to get the name of the thing it points to. If the optional mode pointer is passed in also read the symbolic link's file mode and return it in *returnMode; Note that normally the FileMode of a symbolic link is a mix of the attributes of the link itself and the thing it points to. The mix works like this:
If the does not exist or is not a symbolic link, then the returned value is empty string. If the file is a symbolic link then an absolute path will be returned.
Definition at line 2471 of file file.cxx.
bool remove | ( | ) | const |
bool rename | ( | FileName const & | destination | ) | const |
Rename the file whose name is specified '*this' into a new file whose name is specified in destination.
destination | A FileName containing the new name for the file. |
Definition at line 1753 of file file.cxx.
bool rmdir | ( | ) | const |
string shorten | ( | int | max_chars | ) | const |
Produce a string which is a shortened version of the filename by deleting excess characters and inserting an elipses in the middle to signify missing characters. The name will not refer to a real file (unless by accident).
Shorten a filename for display purposes only.
Definition at line 1948 of file file.cxx.
size_t size | ( | ) | const |
size_t slurp | ( | std::list< std::string > * | lines | ) | const |
void slurp | ( | FileContents * | f | ) | const |
Read whole file (binary read) into a FileContents object and set its error method correctly.
Definition at line 1327 of file file.cxx.
rep_t substr | ( | size_t | s, | |
size_t | l | |||
) | const |
std::auto_ptr< FileName::Tree > tree | ( | bool | only_dirs = false |
) | const |
Get the subdirectory tree starting with this filename. If this filename refers to a normal file, then tree will have only one node. If this does not refer to a valid file, one node will be returned but the 'status' will indicate that it is not a good file. If this FileName is a directory, then the sub-directory tree will be returned. If any node's status is not avaialable, its status will indicate that.
Definition at line 2230 of file file.cxx.
std::auto_ptr< FileName::Tree > tree_helper | ( | std::string const & | path, | |
bool | only_dirs = false , |
|||
int | depth = 0 | |||
) | const [private] |
bool write | ( | char const * | begin, | |
char const * | end, | |||
bool | binary_mode = true | |||
) |
Open the file whose name is contained in this FileName object and write the data found between begin and end to the file in either ascii or binary mode depending on the binary_mode flag. On unix, this flag is ignored. The file will be created with default umask permission.
begin | is the pointer to the beginning of the data to be written. | |
end | is the end of the buffer to be written | |
binary_mode | (windows only) controls the io mode. |
Definition at line 2129 of file file.cxx.
bool write | ( | std::string const & | file_contents, | |
bool | binary_mode = true | |||
) |
Write a string to a newly create file whose name is the contained in this filename. If the file previously existed, it will be deleted then recreated.
file_contents | is the content of the newly created file | |
binary_mode | is a flag indicating that binary mode will be used to write the file (Windows only). |
The file will be created using default umask protections and will be written be written as either ascii or binary base on the binary_mode flag. On unix this flag is ignored.
Definition at line 2119 of file file.cxx.
std::string operator+ | ( | char const * | lhs, | |
FileName const & | rhs | |||
) | [friend] |
std::string operator+ | ( | std::string const & | lhs, | |
FileName const & | rhs | |||
) | [friend] |
bool operator== | ( | char const * | lhs, | |
FileName const & | rhs | |||
) | [friend] |
bool operator== | ( | std::string const & | lhs, | |
FileName const & | rhs | |||
) | [friend] |
char PATH_separator = ':' [static] |