Documentation: File Manipulation

Documentation: File Manipulation [Remove Frame]

Almost all applications will eventually be faced with the need to manipulate file, and directories, and access the underlying operating system's file system. In FOX, a large collection of useful filename and directory name manipulation functions is provided with which you can perform these tasks easily.
Moreover, the FOX file manipulations are aware of platform specific idiosyncracies, such as UNC under MS-Windows and escaping sequences under UNIX.

Finding Special Directories

Certain directories in the file system are special, like the applications current working directory, the users home directory, and so on. FOX supplies the following functions for this purpose:

FXString getEnvironment(const FXString& name)

This function obtains the environment variable name from the environment. It returns the empty string if not found.

FXString getHomeDirectory()

Returns the current user's home directory.

FXString getUserDirectory(const FXString& user)

Returns the home directory of the named user, or the current user's home directory if the parameter user is empty.

FXString setCurrentDirectory(const FXString& path)

Change the application's current working directory to path

FXString getCurrentDirectory()

Returns the current working directory of the application.

FXString setCurrentDrive(const FXString& prefix)

Change the application's current drive letter to prefix, where prefix is the drive letter, like "a:", "b:", and so on. This function of course has no effect on UNIX systems.

FXString getCurrentDrive()

Returns the current drive letter of the application. This function of course has no effect on UNIX systems.

FXString getExecPath()

Returns the path along which the systems shell usually locates executable programs, or "$PATH". The returned path string is a sequence of directories separated by PATHLISTSEP.

Filename Manipulation

Manipulating filenames is done with the following functions:

FXString directory(const FXString& file)

Return the directory part of file. Note that directory("/bla/bla/") yields "/bla/bla" and NOT "/bla". However, directory("/bla/bla") yields "/bla" as we expect!

FXString name(const FXString& file)

Return name and extension part of file. Note that name("/bla/bla/") yields "" and NOT "bla". However, name("/bla/bla") yields "bla" as we expect.

FXString title(const FXString& file)

Return title part of file. This is the name of the document with the directory part and the extension part removed.

FXString extension(const FXString& file)

Return extension part of file.

FXString stripExtension(const FXString& file)

Strip the extension part of file.

FXString drive(const FXString& file)

Return the drive letter part of file. Of course, on UNIX systems this will return the empty string.

FXString expand(const FXString& file)

Expand meta-characters in file. On UNIX systems, "~" is expanded into the current user's home directory, "~user" into the given user's home directory, via getUserDirectory(). Also, "$VARIABLE", "${VARIABLE}", or "$(VARIABLE)" will be expanded into the environment variable VARIABLE, via getEnvironment(). On MS-Windows, environment variables of the form "%VARIABLE%" are expanded similarly.

FXString simplify(const FXString& file)

Return the simplest pathname representation of file. The path will remain relative if it was relative, or absolute if it was absolute. Also, a trailing "/" will be preserved as this is important in other functions. For example, simplify("..//aaa/./bbb//../c/") yields "../aaa/c/".

FXString absolute(const FXString& file)

Return the absolute path to the file, given the current working directory and drive letter.

FXString absolute(const FXString& base,const FXString& file)

Build the absolute path to the file, from the given base directory and file.

FXString relative(const FXString& file)

Return the path to file, relative to the current working directory.

FXString relative(const FXString& base,const FXString& file)

Return the path to file, relative to the directory base.

FXString enquote(const FXString& file,FXbool forcequotes=FALSE)

Enquote file to make safe for shell. Normally, quotes are only generated when necessary, but if forcequotes is TRUE quotes are always generated regarless of necessity.
Files with special characters need to be quoted before they may be passed to bash, ksh, csh (UNIX) or cmd (MS-Windows).

FXString dequote(const FXString& file)

Dequote file to yield the original again.

FXString unique(const FXString& file)

Generate unique filename of the form "pathnameXXX.ext", where pathname.ext is the original input file, and XXX is a number, possibly empty, that makes the file unique.

FXString search(const FXString& pathlist,const FXString& file)

Search pathlist for this file, return full path name for first occurrence. The pathlist is a PATHLISTSEP separated list of directories, such as returned by getExecPath.

FXString upLevel(const FXString& file)

Return path to directory above input directory file.

Obtaining information about files

A number of functions are also available to obtain various kinds of information about files or directories:

FXbool isAbsolute(const FXString& file)

Return true if file is an absolute pathname.

FXbool isTopDirectory(const FXString& file)

Return true if input file is a top-level directory.

FXbool isFile(const FXString& file)

Return true if input file is a file name.

FXbool isLink(const FXString& file)

Return true if input file is a link.

FXbool isDirectory(const FXString& file)

Return true if input file is a directory.

FXbool isReadable(const FXString& file)

Return true if input file is readable.

FXbool isWritable(const FXString& file)

Return true if input file is writable.

FXbool isExecutable(const FXString& file)

Return true if input file is executable.

FXbool isOwnerReadWriteExecute(const FXString& file)

Return true if owner has read-write-execute permissions.

FXbool isOwnerReadable(const FXString& file)

Return true if owner has read permissions.

FXbool isOwnerWritable(const FXString& file)

Return true if owner has write permissions.

FXbool isOwnerExecutable(const FXString& file)

Return true if owner has execute permissions.

FXbool isGroupReadWriteExecute(const FXString& file)

Return true if group has read-write-execute permissions.

FXbool isGroupReadable(const FXString& file)

Return true if group has read permissions.

FXbool isGroupWritable(const FXString& file)

Return true if group has write permissions.

FXbool isGroupExecutable(const FXString& file)

Return true if group has execute permissions.

FXbool isOtherReadWriteExecute(const FXString& file)

Return true if others have read-write-execute permissions.

FXbool isOtherReadable(const FXString& file)

Return true if others have read permissions.

FXbool isOtherWritable(const FXString& file)

Return true if others have write permissions.

FXbool isOtherExecutable(const FXString& file)

Return true if others have execute permissions.

FXbool isSetUid(const FXString& file)

Return true if the file sets the user id on execution.

FXbool isSetGid(const FXString& file)

Return true if the file sets the group id on execution.

FXbool isSetSticky(const FXString& file)

Return true if the file has the sticky bit set.

FXString owner(const FXString& file)

Return owner name of file, if available; otherwise "user".

FXString group(const FXString& file)

Return group name of file, if available; otherwise "group".

unsigned long size(const FXString& file)

Return size of file in bytes

FXTime modified(const FXString& file)

Return last modified time of file.

FXTime accessed(const FXString& file)

Return last accessed time of file.

FXTime created(const FXString& file)

Return create-time of file.

FXTime touched(const FXString& file)

Return touched time of file.

Copying, Moving, Linking Files

The following operations are available on files:

FXbool createDirectory(const FXString& path,FXuint mode)

Create new directory path, with permissions set to mode.

FXbool createFile(const FXString& file,FXuint mode)

Create new empty file, with permissions set to mode.

FXbool concatenate(const FXString& srcfile1,const FXString& srcfile2,const FXString& dstfile,FXbool overwrite=FALSE)

Concatenate srcfile1 and srcfile2 to a dstfile. If overwrite is true, then the operation fails if dstfile already exists. srcfile1 and srcfile2 should not be the same as dstfile.

FXbool remove(const FXString& file)

Remove file or directory, recursively.

FXbool copy(const FXString& srcfile,const FXString& dstfile,FXbool overwrite=FALSE)

Copy srcfile to a dstfile, recursively if srcfile is a directory. If overwrite is true, then the operation fails if dstfile or a file inside dstfile already exists.

FXbool move(const FXString& srcfile,const FXString& dstfile,FXbool overwrite=FALSE)

Move srcfile to a dstfile, recursively if srcfile is a directory. If overwrite is true, then the operation fails if dstfile or a file inside dstfile already exists. If srcfile and dstfile are on the same file system, the files are moved; if srcfile and dstfile are on different file systems, the files are copied and the original srcfile is removed only after all files have been copied successfully.

FXbool link(const FXString& srcfile,const FXString& dstfile,FXbool overwrite=FALSE)

Link dstfile to srcfile. If overwrite is true, then the operation fails if dstfilealready exists. If srcfile and dstfile are on different filesystems, the operation will fail.

FXbool symlink(const FXString& srcfile,const FXString& dstfile,FXbool overwrite=FALSE)

Make a symbolic link from dstfile to srcfile. If overwrite is true, then the operation fails if dstfilealready exists.

FXString symlink(const FXString& file)

Return the destination of the symlink file.

Other File Operations

Finally, some operations which don't fit in any easy categories:

FXbool match(const FXString& pattern,const FXString& file,FXuint flags=(FILEMATCH_NOESCAPE|FILEMATCH_FILE_NAME))

Perform wildcard match of file against the pattern. The pattern may contain special wild-card characters:

? Matches single character.

* Matches zero or more characters.

[abc] Matches a single character, which must be a, b, or c.

[^abc] Matches a single character, which must be anything other than a, b, or c.

[!abc] Ditto.

[a-zA-Z] Matches single character, which must be one of a-z or A-Z.

[^a-zA-Z] Matches single character, which must be anything other than a-z or A-Z.

[!a-zA-Z] Ditto.

pat1|pat2 Matches either pat1 or pat2.

pat1,pat2 Ditto.

(pat1|pat2) Matches either pat1 or pat2; patterns may be nested.

(pat1,pat2) Ditto.

Matching can be influenced using the flags as follows:

FILEMATCH_FILE_NAME No wildcard can ever match "/" (or "\","/" under Windows).

FILEMATCH_NOESCAPE Backslashes don't quote special chars ("\" is treated as "\").

FILEMATCH_PERIOD Leading "." is matched only explicitly (Useful to match hidden files on Unix).

FILEMATCH_LEADING_DIR Ignore "/..." after a match.

FILEMATCH_CASEFOLD Compare without regard to case.

For example,

*.cpp|*.cc|*.cxx|*.C Matches some common extensions for C++ source files.

image.(bmp,gif,jpg) Matches a file called image given as either bmp, gif, or jpg.

*.[^o] Matches any file except object files.

FXint listFiles(FXString*& list,const FXString& path,const FXString& pattern="*",FXuint flags=LIST_MATCHING_FILES|LIST_MATCHING_DIRS)

List files matching pattern in the directory given by path. Returns the number of files in the string-array list which matched the pattern or satisfied the flag conditions. The flags parameter can be a combination of the following:

LIST_MATCHING_FILES Match files (default).

LIST_MATCHING_DIRS Match directories (default).

LIST_NO_FILES Do not match any files.

LIST_NO_DIRS Do not match any directories.

LIST_ALL_FILES Match all files.

LIST_ALL_DIRS Match all directories.

LIST_HIDDEN_FILES Match hidden files also.

LIST_HIDDEN_DIRS Match hidden directories also.

LIST_NO_PARENT Do not match "..".

LIST_CASEFOLD Perform case insensitive matching.

FXTime now()

Return current time.

FXString time(FXTime filetime)

Convert filetime to date-string.

FXString time(const FXchar *format,FXTime filetime)

Convert file time to date-string as per strftime(3). Format characters supported by most systems are:

%a %A %b %B %c %d %H %I %j %m %M %p %S %U %w %W %x %X %y %Y %Z %%

Some systems support additional conversions.

FXbool info(const FXString& file,struct stat& info)

Return info of file as reported by system stat(2) function.

FXbool exists(const FXString& file)

Return true if file exists.

FXbool identical(const FXString& file1,const FXString& file2)

Return true if file1 and file2 are identical, i.e. refer to the same inode.

FXuint mode(const FXString& file)

Return the permissions of file.

FXbool mode(const FXString& file,FXuint mode)

Change the permission of file to mode.

?	Matches single character.
*	Matches zero or more characters.
[abc]	Matches a single character, which must be a, b, or c.
[^abc]	Matches a single character, which must be anything other than a, b, or c.
[!abc]	Ditto.
[a-zA-Z]	Matches single character, which must be one of a-z or A-Z.
[^a-zA-Z]	Matches single character, which must be anything other than a-z or A-Z.
[!a-zA-Z]	Ditto.
pat1\|pat2	Matches either pat1 or pat2.
pat1,pat2	Ditto.
(pat1\|pat2)	Matches either pat1 or pat2; patterns may be nested.
(pat1,pat2)	Ditto.

FILEMATCH_FILE_NAME	No wildcard can ever match "/" (or "\","/" under Windows).
FILEMATCH_NOESCAPE	Backslashes don't quote special chars ("\" is treated as "\").
FILEMATCH_PERIOD	Leading "." is matched only explicitly (Useful to match hidden files on Unix).
FILEMATCH_LEADING_DIR	Ignore "/..." after a match.
FILEMATCH_CASEFOLD	Compare without regard to case.

.cpp\|.cc\|.cxx\|.C	Matches some common extensions for C++ source files.
image.(bmp,gif,jpg)	Matches a file called image given as either bmp, gif, or jpg.
*.[^o]	Matches any file except object files.

LIST_MATCHING_FILES	Match files (default).
LIST_MATCHING_DIRS	Match directories (default).
LIST_NO_FILES	Do not match any files.
LIST_NO_DIRS	Do not match any directories.
LIST_ALL_FILES	Match all files.
LIST_ALL_DIRS	Match all directories.
LIST_HIDDEN_FILES	Match hidden files also.
LIST_HIDDEN_DIRS	Match hidden directories also.
LIST_NO_PARENT	Do not match "..".
LIST_CASEFOLD	Perform case insensitive matching.