D
Language
Phobos
Comparisons
object
std
std.base64
std.bitarray
std.boxer
std.compiler
std.conv
std.ctype
std.date
std.demangle
std.file
std.format
std.gc
std.intrinsic
std.math
std.md5
std.mmfile
std.openrj
std.outbuffer
std.path
std.process
std.random
std.recls
std.regexp
std.socket
std.socketstream
std.stdint
std.stdio
std.cstream
std.stream
std.string
std.system
std.thread
std.uni
std.uri
std.utf
std.zip
std.zlib
std.windows
std.linux
std.c
std.c.stdio
std.c.windows
std.c.linux
|
std.recls
recls - standing for recursive ls - is a platform-independent
recursive search library, designed and implemented by Matthew Wilson, as the first
exemplar project for his column Positive Integration in
C/C++ Users Journal.
recls currently supports recursive searching of file systems (UNIX and Windows), and
FTP sites (currently Windows-only). Future enhancements may include recursive-searching of the
Windows registry, source-code control systems, and, of course, FTP-searching for UNIX platforms.
recls is implemented in C++, using the
STLSoft
libraries (which are also bundled with Digital Mars; see
stlsoft.digitalmars.com),
and presents a C-API. recls is also mapped to a host of other languages and
technologies, including C++, COM, C#/.NET, Java, Ruby
and STL among an ever-expanding list. Given its non-trivial size, the recls D
mapping is a good place to learn about interfacing C libraries to D.
The recls homepage is www.recls.org,
from which updates to the library, and all the other language mappings, may be obtained. Support
for recls has evolved to piggy-back on the
STLSoft newsgroup, although
questions about using recls in D should be directed through the main
D newsgroup, and bugs in
recls (in D) should be reported to the
D bugs newsgroup.
The Windows version of the D mapping of recls uses a crude-but-adequate delay-loading
mechanism such that linking to WinInet.lib is not required. This strategy was necessitated by
D's linkage model, and was elected to avoid encumbering executables with something that they
may not use. There is are negative effects if the program explicitly uses WinInet.lib for
other aspects.
The recls object model is comprised of the following classes:
the enum RECLS_FLAG:
and the following functions:
The basic usage is as follows:
-
Create a search instance, either FileSearch or
FtpSearch, e.g.
// Enumerate all the zip and exe files on the Digital Mars FTP server
Search s = new FtpSearch("ftp.digitalmars.com", "anonymous", "", "/",
"*.zip;*.exe", RECLS_FLAG.RECURSIVE | RECLS_FLAG.PASSIVE_FTP);
or
// Enumerate all the three-letter first-level sub-directories beginning
// with s of H:\SynSoft\D\phobos\
FileSearch s = new FileSearch("H:\SynSoft\D\phobos\", "s??",
RECLS_FLAG.DIRECTORIES);
-
Enumerate the search instance, using foreach.
foreach(Entry e; s)
{
if(e.size < 2000)
{
writef(e.path); // e.g. "/Digital_Mars_C++/STL"
writef(e.directory); // e.g. "/Digital_Mars_C++/STL"
writef(e.file); // e.g. "stlport.zip"
writef(e.fileName); // e.g. "stlport"
writef(e.fileExt); // e.g. "zip"
...
}
}
The many properties of the Entry class are used to provide
access to all attributes of file/directory entries.
std.recls.Entry
The Entry class has the following properties:
- char[] getPath()
- char[] path()
- The full path of the entry
- char drive() - (Windows only)
- The drive component of the entry's path
- char[] directory()
- The directory component of the entry's path
- char[] directoryPath()
- The full location component of the entry's path.
- char[][] directoryParts()
- An array of strings representing the parts of the Directory property
- char[] file()
- The file component of the entry's path
- char[] shortFile()
- The short equivalent of the entry's File property
- char[] fileName()
- The file name component of the entry's path
- char[] fileExt()
- The file extension component of the entry's path
- d_time creationTime()
- The time the entry was created
- d_time modificationTime()
- The time the entry was last modified
- d_time lastAccessTime()
- The time the entry was last accessed
- d_time lastStatusChangeTime()
- The time the entry's last status changed
- recls_filesize_t fileSize()
- The size of the entry
- int isReadOnly()
- Indicates whether the entry is read-only
- int isDirectory()
- Indicates whether the entry is a directory
- int isLink()
- Indicates whether the entry is a link
std.recls.FileSearch
The FileSearch class derives from the
Search class, and has the following
methods:
- this(in char[] searchRoot, in char[] pattern, in uint flags)
- Create a search object with the given searchRoot, pattern and flags
- searchRoot The root directory of the search. If null, or the empty string, the current directory is assumed
- pattern The search pattern. If null all entries are returned (equivalent to specifying
wildcardsAll().) If the empty string, the search returns an empty result set.
- flags A combination of RECLS_FLAG flags which moderate the search
- Note: pattern can be a composite pattern, e.g. "*.exe;*.zip;*.c??", but the separator must
be the correct one for the local operating system (see getPathSeparator()).
std.recls.FtpSearch
The FtpSearch class derives from the
Search class, and has the following
methods:
- this(in char[] host, in char[] username, in char[] password, in char[] searchRoot, in char[] pattern, in uint flags)
- Create a search object with the given searchRoot, pattern and flags
- host The name of the host providing the FTP service
- username The username of the acount to use to log on to the FTP server
- password The password of the acount to use to log on to the FTP server
- searchRoot The root directory of the search. If null, or the empty string, the current directory is assumed
- pattern The search pattern. If null all entries are returned (equivalent to specifying
wildcardsAll().) If the empty string, the search returns an empty result set.
- flags A combination of RECLS_FLAG flags which moderate the search
- Note: pattern can be a composite pattern, e.g. "*.exe;*.zip;*.c??", but the separator must
be the correct one for the local operating system (see getPathSeparator()).
std.recls.ReclsException
Exception class used by the recls module.
std.recls.Search
Base class of the FileSearch and
FtpSearch classes. Supports foreach.
std.recls.RECLS_FLAG
Enumeration, whose values control the search behaviour provided by the
FileSearch and
FtpSearch classes.
- FILES - Include files in search. Included by default if none specified
- DIRECTORIES - Include directories in search. Not currently supported
- LINKS - Include links in search. Ignored in Win32
- DEVICES - Include devices in search. Not currently supported
- RECURSIVE - Searches given directory and all sub-directories
- NO_FOLLOW_LINKS - Does not expand links
- DIRECTORY_PARTS - Fills out the directory parts. Supported from version 1.1.1 onwards
- DETAILS_LATER - Does not fill out anything other than the path. Not currently supported
- PASSIVE_FTP - Passive mode in FTP
std.recls functions
Free functions provided by the recls module.
- char[][] getRoots();
- Returns an array of all file-system roots on the local system.
-
On Unix, this always returns an array with a single entry which is "/". On Windows,
it will return an array of strings representing the drives, e.g. "C:", "D:", "H:", "Y:"
.
- char[] getPathNameSeparator();
- Returns the symbol used to separate distinct path names in path name lists.
-
On UNIX this is "/"; on Win32 it is "\".
.
- char[] getPathNameSeparator();
- Returns the symbol used to separate the directory parts within paths.
-
On UNIX this is ":"; on Win32 it is ";".
.
- char[] wildcardsAll();
- Returns the wildcard symbol used to represent the "all files" for the current operating system.
-
On UNIX this is "*"; on Win32 it is "*.*".
.
- int isDirectoryEmpty(char[] dir);
- int isDirectoryEmpty(Entry dir);
-
Determines whether the given directory is empty.
.
- recls_filesize_t calcDirectorySize(char[] dir, int bRecurse);
- recls_filesize_t calcDirectorySize(Entry dir, int bRecurse);
-
Determines the size of the given directory. If bRecurse is non-0, it calculates the size of all
sub-directories, otherwise it counts only the sizes of the files in the given directory.
.
Copyright (c) 2003-2004 by Matthew Wilson, Synesis Software Pty Ltd, All Rights Reserved
|