ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
Loading...
Searching...
No Matches
ALib Module Files - Programmer's Manual

Table of Contents

1. Introduction

This ALib Module provides mechanics to scan directories and contained files. The scan results are collected in an instance of FTree , which inherits class StringTree . Using classes StringTree::Cursor and StringTree::RecursiveIterator , two very comfortable interfaces to accessing the results are available.

As of today, besides scanning files, no specific further functionality is given and it is up to the user of the module to do with the result lists whatever is intended.

While the reference documentation of the types found in this module is quite verbose and thus should be all that is really needed, this Programmer's Manual just provides some few step by step demo samples.

2. Tutorial

2.1 Scanning a File Tree

A simple application needs to include just headers alib/files/ftree.hpp and alib/files/fscanner.hpp :

#include "alib/files/ftree.hpp"
#include "alib/files/fscanner.hpp"
using namespace alib;
using namespace std;

For scanning a path including its subdirectories, a few objects are needed:

// Beginning of main(). Initialize ALIB once
alib::Bootstrap();
// A monotonic allocator, used by the file tree to allocate storage
MonoAllocator monomem(4096);
// The file tree to collect the results.
FTree fileTree(&monomem);
// The scan parameters. Apart from the start directory, we leave everything on defaults.
ScanParameters scanParameters(ALIB_BASE_DIR A_CHAR("/src/alib/files") );
// A vector to collect the result path(s).
std::vector<ResultsPaths> resultPaths;

Here are the links to the reference documentation of these objects:

Note that the sample code above uses preprocessor symbol ALIB_BASE_DIR, which is defined with the ALib unit test project, that this documentation uses to generate the samples.

That is all we needed to start the scan, which is done using namespace function ScanFiles . Next we use namespace function DbgDump , which as its prefix Dbg indicates, is only available in debug-compilations of the library:

// Scan files
files::ScanFiles( fileTree, scanParameters, resultPaths);
// Dump files to the console
AString dumpBuffer;
DbgDump(dumpBuffer, fileTree);
cout << dumpBuffer << endl;

The resulting output is:

drwxr-xr-x root root 4.0K 2024-02-21 22:14 sta -- /
drwxr-xr-x root root 4.0K 2023-12-23 09:19 sta -- /mnt
drwxr-xr-x a a 4.0K 2023-11-04 07:52 sta -- /mnt/a
drwx------ a a 4.0K 2024-03-11 20:44 sta -- /mnt/a/dev
drwx------ a a 4.0K 2024-03-11 21:08 sta -- /mnt/a/dev/A-Worx
drwxr-xr-x a a 4.0K 2024-03-20 07:37 sta -- /mnt/a/dev/A-Worx/ALib
drwxr-xr-x a a 4.0K 2024-02-28 21:00 sta -- /mnt/a/dev/A-Worx/ALib/src
drwxr-xr-x a a 4.0K 2024-03-20 08:29 sta -- /mnt/a/dev/A-Worx/ALib/src/alib
drwxr-xr-x a a 4.0K 2024-03-18 18:16 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files (0d, 15f, 0ea, 0bl)
-rw-r--r-- a a 29.2K 2024-03-11 12:17 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp
-rw-r--r-- a a 54.2K 2024-03-18 10:01 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp
-rw-r--r-- a a 1.5K 2024-02-29 15:05 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftools.cpp
-rw-r--r-- a a 2.8K 2024-03-11 12:17 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp
-rw-r--r-- a a 12.3K 2024-03-18 18:16 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp
-rw-r--r-- a a 6.0K 2024-02-29 15:05 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp
-rw-r--r-- a a 12.0K 2024-03-18 18:16 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp
-rw-r--r-- a a 14.0K 2024-03-11 12:18 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp
-rw-r--r-- a a 4.0K 2024-02-29 15:05 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.cpp
-rw-r--r-- a a 3.1K 2024-03-17 20:33 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.hpp
-rw-r--r-- a a 2.0K 2024-02-29 15:05 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftools.hpp
-rw-r--r-- a a 11.7K 2024-03-18 09:58 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp
-rw-r--r-- a a 2.9K 2024-03-11 12:17 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ffilter.hpp
-rw-r--r-- a a 3.0K 2024-03-18 09:59 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.cpp
-rw-r--r-- a a 13.9K 2024-03-17 10:02 OK -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp

You might wonder about the resultPath vector given as an output parameter into function ScanFiles . Especially the question is: Why is it a vector? Wouldn't it be just the requested start path?

Let's quickly examine the result:

cout << "Number of result paths: " << resultPaths.size() << endl;
cout << " real path[0]: " << resultPaths.front().RealPath << endl;

This writes:

Number of result paths: 1
real path[0]: /mnt/a/dev/A-Worx/ALib/src/alib/files

So, in fact, it is only one result and it is here called "real path" is exactly the path that was requested to be scanned. But this can be quite different, when symbolic links come into place. Details on this topic is given in the with reference documentation of function ScanFiles and instead to repeat this here, we ask the reader for a brief digression to this explanation now.

2.2 Using Filters With Scanning

We left all fields of class ScanParameters with their default values in the previous sample. Now we want to look at fields:

Again, please refer to the reference documentation of the fields linked above, to get a quick understanding, why the scan function offers to set up to three different filter objects.

Class FFilter is a very simple virtual abstract interface class, which only has one single method Includes to implement. Derived filter types, need return true, if a file or directory "passes" the filter, hence in this case is included in the scan results.

It should be very straight forward to implement an own derived a filter class. The problem with such class would be, that it would be more or less "hard-coded" in respect to what is filtered and what not. This might be flexible enough for most applications.
The next chapter introduces a filter which is run-time compiled!

2.3 Class FileExpressions

In case module ALib Expressions is included in the ALib Distribution , this module exposes class FileExpressions . This class implements a CompilerPlugin dedicated to articulate run-time expressions working with FInfo objects.

The class exposes public inner type FileExpressions::Filter which implements the FFilter interface. With construction, the filter accepts a character string containing the filter expression.

The full set of expression operators, functions and constants is documented with class FileExpressions and not to be repeated here. While expressions might return any kind of type, those used with class FileExpression::Filter, have to evaluate to a boolean value. As documented with module ALib Expressions , due to the type-safe implementation of the module, already at "compile time" of an expression (which is run-time of your software), the result type of an expression can be checked.

We just look at some samples:

We have to add header file alib/files/fileexpressions.hpp :

#include "alib/files/fileexpressions.hpp"

Now this code compiles:

// Beginning of main(). Initialize ALIB once
alib::Bootstrap();
// objects needed for scanning files
MonoAllocator monomem(4096);
FTree fileTree(&monomem);
ScanParameters scanParameters(ALIB_BASE_DIR A_CHAR("/src/alib/files") );
std::vector<ResultsPaths> resultPaths;
// create the expression compiler and let it compile a filter
FileExpressions fex;
scanParameters.FileFilter= fex.CreateFilter(A_CHAR("name = \"ftree.hpp\""));
// Scan files
files::ScanFiles( fileTree, scanParameters, resultPaths);

The resulting output is:

drwxr-xr-x root root   4.0K 2024-02-21 22:14 sta -- /  
drwxr-xr-x root root   4.0K 2023-12-23 09:19 sta -- /mnt  
drwxr-xr-x    a    a   4.0K 2023-11-04 07:52 sta -- /mnt/a  
drwx------    a    a   4.0K 2024-03-11 20:44 sta -- /mnt/a/dev  
drwx------    a    a   4.0K 2024-03-11 21:08 sta -- /mnt/a/dev/A-Worx  
drwxr-xr-x    a    a   4.0K 2024-03-20 07:37 sta -- /mnt/a/dev/A-Worx/ALib  
drwxr-xr-x    a    a   4.0K 2024-02-28 21:00 sta -- /mnt/a/dev/A-Worx/ALib/src  
drwxr-xr-x    a    a   4.0K 2024-03-20 08:29 sta -- /mnt/a/dev/A-Worx/ALib/src/alib  
drwxr-xr-x    a    a   4.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files  (0d, 1f, 0ea, 0bl)
-rw-r--r--    a    a  13.9K 2024-03-17 10:02 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp

Here are some more samples:

scanParameters.FileFilter= fex.CreateFilter(A_CHAR("size > kilobytes(10)"));
drwxr-xr-x root root   4.0K 2024-02-21 22:14 sta -- /  
drwxr-xr-x root root   4.0K 2023-12-23 09:19 sta -- /mnt  
drwxr-xr-x    a    a   4.0K 2023-11-04 07:52 sta -- /mnt/a  
drwx------    a    a   4.0K 2024-03-11 20:44 sta -- /mnt/a/dev  
drwx------    a    a   4.0K 2024-03-11 21:08 sta -- /mnt/a/dev/A-Worx  
drwxr-xr-x    a    a   4.0K 2024-03-20 07:37 sta -- /mnt/a/dev/A-Worx/ALib  
drwxr-xr-x    a    a   4.0K 2024-02-28 21:00 sta -- /mnt/a/dev/A-Worx/ALib/src  
drwxr-xr-x    a    a   4.0K 2024-03-20 08:29 sta -- /mnt/a/dev/A-Worx/ALib/src/alib  
drwxr-xr-x    a    a   4.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files  (0d, 7f, 0ea, 0bl)
-rw-r--r--    a    a  29.2K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp  
-rw-r--r--    a    a  54.2K 2024-03-18 10:01 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp  
-rw-r--r--    a    a  12.3K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp  
-rw-r--r--    a    a  12.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp  
-rw-r--r--    a    a  14.0K 2024-03-11 12:18 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp  
-rw-r--r--    a    a  11.7K 2024-03-18 09:58 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp  
-rw-r--r--    a    a  13.9K 2024-03-17 10:02 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp
scanParameters.FileFilter= fex.CreateFilter(A_CHAR("GetHour(time) % 2 == 0"));
drwxr-xr-x root root   4.0K 2024-02-21 22:14 sta -- /  
drwxr-xr-x root root   4.0K 2023-12-23 09:19 sta -- /mnt  
drwxr-xr-x    a    a   4.0K 2023-11-04 07:52 sta -- /mnt/a  
drwx------    a    a   4.0K 2024-03-11 20:44 sta -- /mnt/a/dev  
drwx------    a    a   4.0K 2024-03-11 21:08 sta -- /mnt/a/dev/A-Worx  
drwxr-xr-x    a    a   4.0K 2024-03-20 07:37 sta -- /mnt/a/dev/A-Worx/ALib  
drwxr-xr-x    a    a   4.0K 2024-02-28 21:00 sta -- /mnt/a/dev/A-Worx/ALib/src  
drwxr-xr-x    a    a   4.0K 2024-03-20 08:29 sta -- /mnt/a/dev/A-Worx/ALib/src/alib  
drwxr-xr-x    a    a   4.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files  (0d, 9f, 0ea, 0bl)
-rw-r--r--    a    a  29.2K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp  
-rw-r--r--    a    a  54.2K 2024-03-18 10:01 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp  
-rw-r--r--    a    a   2.8K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp  
-rw-r--r--    a    a  12.3K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp  
-rw-r--r--    a    a  12.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp  
-rw-r--r--    a    a  14.0K 2024-03-11 12:18 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp  
-rw-r--r--    a    a   3.1K 2024-03-17 20:33 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.hpp  
-rw-r--r--    a    a   2.9K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ffilter.hpp  
-rw-r--r--    a    a  13.9K 2024-03-17 10:02 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp
scanParameters.FileFilter= fex.CreateFilter(A_CHAR("IndexOf(name,\"camp\")>0"));
drwxr-xr-x root root   4.0K 2024-02-21 22:14 sta -- /  
drwxr-xr-x root root   4.0K 2023-12-23 09:19 sta -- /mnt  
drwxr-xr-x    a    a   4.0K 2023-11-04 07:52 sta -- /mnt/a  
drwx------    a    a   4.0K 2024-03-11 20:44 sta -- /mnt/a/dev  
drwx------    a    a   4.0K 2024-03-11 21:08 sta -- /mnt/a/dev/A-Worx  
drwxr-xr-x    a    a   4.0K 2024-03-20 07:37 sta -- /mnt/a/dev/A-Worx/ALib  
drwxr-xr-x    a    a   4.0K 2024-02-28 21:00 sta -- /mnt/a/dev/A-Worx/ALib/src  
drwxr-xr-x    a    a   4.0K 2024-03-20 08:29 sta -- /mnt/a/dev/A-Worx/ALib/src/alib  
drwxr-xr-x    a    a   4.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files  (0d, 2f, 0ea, 0bl)
-rw-r--r--    a    a   2.8K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp  
-rw-r--r--    a    a   6.0K 2024-02-29 15:05 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp
scanParameters.FileFilter= fex.CreateFilter(A_CHAR("EndsWith(Path,\"files\")"));
drwxr-xr-x root root   4.0K 2024-02-21 22:14 sta -- /  
drwxr-xr-x root root   4.0K 2023-12-23 09:19 sta -- /mnt  
drwxr-xr-x    a    a   4.0K 2023-11-04 07:52 sta -- /mnt/a  
drwx------    a    a   4.0K 2024-03-11 20:44 sta -- /mnt/a/dev  
drwx------    a    a   4.0K 2024-03-11 21:08 sta -- /mnt/a/dev/A-Worx  
drwxr-xr-x    a    a   4.0K 2024-03-20 07:37 sta -- /mnt/a/dev/A-Worx/ALib  
drwxr-xr-x    a    a   4.0K 2024-02-28 21:00 sta -- /mnt/a/dev/A-Worx/ALib/src  
drwxr-xr-x    a    a   4.0K 2024-03-20 08:29 sta -- /mnt/a/dev/A-Worx/ALib/src/alib  
drwxr-xr-x    a    a   4.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files  (0d, 15f, 0ea, 0bl)
-rw-r--r--    a    a  29.2K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp  
-rw-r--r--    a    a  54.2K 2024-03-18 10:01 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp  
-rw-r--r--    a    a   1.5K 2024-02-29 15:05 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftools.cpp  
-rw-r--r--    a    a   2.8K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp  
-rw-r--r--    a    a  12.3K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp  
-rw-r--r--    a    a   6.0K 2024-02-29 15:05 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp  
-rw-r--r--    a    a  12.0K 2024-03-18 18:16 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp  
-rw-r--r--    a    a  14.0K 2024-03-11 12:18 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp  
-rw-r--r--    a    a   4.0K 2024-02-29 15:05 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.cpp  
-rw-r--r--    a    a   3.1K 2024-03-17 20:33 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.hpp  
-rw-r--r--    a    a   2.0K 2024-02-29 15:05 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftools.hpp  
-rw-r--r--    a    a  11.7K 2024-03-18 09:58 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp  
-rw-r--r--    a    a   2.9K 2024-03-11 12:17 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ffilter.hpp  
-rw-r--r--    a    a   3.0K 2024-03-18 09:59 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.cpp  
-rw-r--r--    a    a  13.9K 2024-03-17 10:02 OK  -- /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp
Note
Of-course the expression compiler implemented with class FileExpressions may be used not only with filtering files. The compiler has public access and it can be used to compile and evaluate any other sort of expressions, including such that do not return a boolean value, can be compiled and evaluated.

3. Outlook

This should be enough for the time being. Module ALib Files is quite new and was introduced only with ALib C++ Library release Version 2402. The future will show how this module expands.

Again, consult the extensive Reference Documentation for all details about the currently existing functionality.