Main Page Modules Alphabetical List Compound List File List Compound Members File Members Related Pages

recls - Libraries Documentation

Version 1.1.1

Introduction

This is the documentation for version 1.1.1 of the recls library. (Click here for release history.)

recls (http://recls.org/) is a C library (implemented in C & C++) that provides recursive file-system ¹ searching. It is described in my "Positive Integration" column, in C/C++ User's Journal (CUJ).

The purpose of the library is twofold. As well as providing an educational experience for the readers (and the author!) of the CUJ column, it is also intended to be a production-quality library, and it is my hope that it will find use throughout the development community. The license is very open, and allows use in any commercial or non-commercial organisation, without requiring provision of source, or runtime acknowledgements.

Language Mappings

In addition to the recls C API, the recls library includes the following language mappings:

recls.c++ C++: A set of simple classes that provide a user-friendly interface over the recls C API
recls.stl STL: A mapping of the recls C API to C++, providing STL-like sequences representing matching file ranges, and directory sub-components.
recls-C# C#: A .NET mapping written in C#.

Several other mappings will be provided, as the library evolves through the column:

COM: Mappings to COM IEnumXxxx enumerators, and to OLE (VB-compatible) collections
D: A mapping to D, based on the new foreach keyword.
Java: A mapping to Java, demonstrating JNI (Java Native Interface).
Managed C++: A .NET mapping written in Managed C++
Perl: A mapping to Perl, demonstrating integration as mod_recls.
Python: A mapping to Python
Ruby: A mapping to Ruby.

Installation

At the moment, the libraries are provided in source (+ project) form only; there are no binaries. This means that you are required to build the libraries yourself. Since the project is primarily educational, this shouldn't present an issue (I hope).

Building the libraries requires that you have version 1.6.5 or later of the STLSoft libraries, and that you've defined the enviroment variable STLSOFT_INCLUDE to refer to the STLSoft directory.

Once other language mappings, that rely on dynamic libraries (such as the .NET ones), then it is possible that binary versions will be made available.

Compilers

At the current time, the supported compilers are:

Borland C/C++ (versions 5.5 & 5.6)
Comeau C++, (version 4.3.0.1 & 4.3.3)
Digital Mars C/C++ (versions 8.35 and above)
GNU C/C++ (versions 3.2 and above)
Intel C/C++ (versions 6.0, 7.0 & 7.1)
Metrowerks Code Warrior (versions 7.0 & 8.0)
Microsoft Visual C/C++ (versions 5.0, 6.0, 7.0 & 7.1)

Note that for version 1.0.1, makefiles are provided for Borland C++, CodeWarrior, Digital Mars, GCC and Visual C++ only.

Acknowledgements

Many thanks are due to Joe Casad & Chuck Allison, the editorial heads of C/C++ User's Journal, without whose faith in my ability to steward the "Positive Integration" column, the recls project wouldn't exist.

Thanks are also due to the following, who've lent support in one way or another:

David Hackson of Intel
Greg Peet (gregpeet.com)
Jeff Tieszen of Metrowerks
Walter Bright of Digital Mars
Microsoft
Borland

Best regards, and good coding

Matthew Wilson

   Director, Synesis Software    (http://www.synesis.com.au)

   STLSoft moderator and C++ monomaniac    (http://www.stlsoft.org/)

   Contributing editor, C/C++ Users Journal    (http://www.synesis.com.au/articles.html#columns)

   recls implementor    matthew hat recls dot org

1. Future versions are planned that will operate on FTP sites.

	Director, Synesis Software		(http://www.synesis.com.au)
	STLSoft moderator and C++ monomaniac		(http://www.stlsoft.org/)
	Contributing editor, C/C++ Users Journal		(http://www.synesis.com.au/articles.html#columns)
	recls implementor		matthew hat recls dot org