www.digitalmars.com Home | Search | D | Comments
Last update Mon Aug 22 2005
D
Language
Phobos
Comparisons


object

std
 std.base64
 std.boxer
 std.compiler
 std.conv
 std.ctype
 std.date
 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.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:

  1. 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);
      
  2. 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

Feedback and Comments

Add feedback and comments regarding this page.
Copyright © 1999-2005 by Digital Mars, All Rights Reserved