ALib Module Files - Programmer's Manual

Table of Contents

• 1. Introduction
• 2. Tutorial
  • 2.1 Scanning a File Tree
  • 2.2 Using Filters With Scanning
  • 2.3 Class FileExpressions
• 3. Monitoring Changes in an FTree
• 4. Attaching Custom Data to Files
• 5. Outlook

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();
 
// The file tree to collect the results (using the shared, self-contained version).
SharedFTree                 fileTree(10);
 
// The scan parameters. Apart from the start directory, we leave everything on defaults.
ScanParameters              scanParameters(ALIB_BASE_DIR  A_PATH("/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:

• FTree,
• ScanParameters,
• ResultsPaths and
• TMonoAllocator located in module ALib Monomem.

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 (If multithreaded, this uses the SharedLock from the SharedFTree
{
    files::ScanFiles( fileTree, scanParameters, resultPaths);
}
    
// Dump files to the console. Lock in shared mode (read only)
AString dumpBuffer;
{ALIB_LOCK_SHARED_WITH(fileTree)
    DbgDump(dumpBuffer, *fileTree);
}
cout << dumpBuffer << endl;

The resulting output is:

drwxr-xr-x 18       root       root     4.0KiB 26. Nov 2024 15:13 STA -- (  0 D   0 F  0 EA  0BL) / 
drwxr-xr-x 16       root       root     4.0KiB 01. Apr 2024 09:22 STA -- (  0 D   0 F  0 EA  0BL) /mnt 
drwxr-xr-x 15          a          a     4.0KiB 29. Mar 2024 11:31 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a 
drwx------ 18          a          a     4.0KiB 03. Dec 2024 20:17 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev 
drwx------ 13          a          a     4.0KiB 15. Dec 2024 07:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx 
drwxr-xr-x  8          a          a     4.0KiB 15. Dec 2024 10:23 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib 
drwxr-xr-x  5          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src 
drwxr-xr-x 20          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib 
drwxr-xr-x  2          a          a     4.0KiB 14. Dec 2024 20:24 REC -- (  0 D  13 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files 
-rw-r--r--  1          a          a    36.5KiB 14. Dec 2024 19:45 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp 
-rw-r--r--  1          a          a    68.2KiB 14. Dec 2024 14:37 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp 
-rw-r--r--  1          a          a     2.8KiB 17. Nov 2024 12:58 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp 
-rw-r--r--  1          a          a    12.6KiB 21. Nov 2024 19:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp 
-rw-r--r--  1          a          a    10.2KiB 14. Dec 2024 19:48 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp 
-rw-r--r--  1          a          a    17.4KiB 10. Dec 2024 11:28 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/file.cpp 
-rw-r--r--  1          a          a    11.8KiB 21. Nov 2024 13:20 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp 
-rw-r--r--  1          a          a    16.5KiB 10. Dec 2024 13:47 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp 
-rw-r--r--  1          a          a     3.1KiB 14. Dec 2024 19:46 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.cpp 
-rw-r--r--  1          a          a     4.7KiB 09. Dec 2024 08:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.hpp 
-rw-r--r--  1          a          a    11.1KiB 10. Dec 2024 18:32 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp 
-rw-r--r--  1          a          a     2.9KiB 23. Nov 2024 13:50 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ffilter.hpp 
-rw-r--r--  1          a          a    58.8KiB 10. Dec 2024 20:20 STA -- (  0 D   0 F  0 EA  0BL) /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:

• DirectoryFilterPreRecursion
• DirectoryFilterPostRecursion
• FileFilter

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 (using an automatic shared value)
SharedFTree                 fileTree(10); // 10 kb initial monotonic memory
ScanParameters              scanParameters(ALIB_BASE_DIR  A_PATH("/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 18       root       root     4.0KiB 26. Nov 2024 15:13 STA -- (  0 D   0 F  0 EA  0BL) / 
drwxr-xr-x 16       root       root     4.0KiB 01. Apr 2024 09:22 STA -- (  0 D   0 F  0 EA  0BL) /mnt 
drwxr-xr-x 15          a          a     4.0KiB 29. Mar 2024 11:31 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a 
drwx------ 18          a          a     4.0KiB 03. Dec 2024 20:17 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev 
drwx------ 13          a          a     4.0KiB 15. Dec 2024 07:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx 
drwxr-xr-x  8          a          a     4.0KiB 15. Dec 2024 10:23 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib 
drwxr-xr-x  5          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src 
drwxr-xr-x 20          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib 
drwxr-xr-x  2          a          a     4.0KiB 14. Dec 2024 20:24 REC -- (  0 D   1 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files 
-rw-r--r--  1          a          a    58.8KiB 10. Dec 2024 20:20 STA -- (  0 D   0 F  0 EA  0BL) /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 18       root       root     4.0KiB 26. Nov 2024 15:13 STA -- (  0 D   0 F  0 EA  0BL) / 
drwxr-xr-x 16       root       root     4.0KiB 01. Apr 2024 09:22 STA -- (  0 D   0 F  0 EA  0BL) /mnt 
drwxr-xr-x 15          a          a     4.0KiB 29. Mar 2024 11:31 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a 
drwx------ 18          a          a     4.0KiB 03. Dec 2024 20:17 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev 
drwx------ 13          a          a     4.0KiB 15. Dec 2024 07:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx 
drwxr-xr-x  8          a          a     4.0KiB 15. Dec 2024 10:23 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib 
drwxr-xr-x  5          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src 
drwxr-xr-x 20          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib 
drwxr-xr-x  2          a          a     4.0KiB 14. Dec 2024 20:24 REC -- (  0 D   9 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files 
-rw-r--r--  1          a          a    36.5KiB 14. Dec 2024 19:45 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp 
-rw-r--r--  1          a          a    68.2KiB 14. Dec 2024 14:37 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp 
-rw-r--r--  1          a          a    12.6KiB 21. Nov 2024 19:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp 
-rw-r--r--  1          a          a    10.2KiB 14. Dec 2024 19:48 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp 
-rw-r--r--  1          a          a    17.4KiB 10. Dec 2024 11:28 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/file.cpp 
-rw-r--r--  1          a          a    11.8KiB 21. Nov 2024 13:20 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp 
-rw-r--r--  1          a          a    16.5KiB 10. Dec 2024 13:47 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp 
-rw-r--r--  1          a          a    11.1KiB 10. Dec 2024 18:32 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp 
-rw-r--r--  1          a          a    58.8KiB 10. Dec 2024 20:20 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp 

scanParameters.FileFilter= fex.CreateFilter(A_CHAR("GetHour(date) % 2 == 0"));

drwxr-xr-x 18       root       root     4.0KiB 26. Nov 2024 15:13 STA -- (  0 D   0 F  0 EA  0BL) / 
drwxr-xr-x 16       root       root     4.0KiB 01. Apr 2024 09:22 STA -- (  0 D   0 F  0 EA  0BL) /mnt 
drwxr-xr-x 15          a          a     4.0KiB 29. Mar 2024 11:31 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a 
drwx------ 18          a          a     4.0KiB 03. Dec 2024 20:17 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev 
drwx------ 13          a          a     4.0KiB 15. Dec 2024 07:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx 
drwxr-xr-x  8          a          a     4.0KiB 15. Dec 2024 10:23 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib 
drwxr-xr-x  5          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src 
drwxr-xr-x 20          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib 
drwxr-xr-x  2          a          a     4.0KiB 14. Dec 2024 20:24 REC -- (  0 D   5 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files 
-rw-r--r--  1          a          a    68.2KiB 14. Dec 2024 14:37 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp 
-rw-r--r--  1          a          a     2.8KiB 17. Nov 2024 12:58 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp 
-rw-r--r--  1          a          a     4.7KiB 09. Dec 2024 08:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.hpp 
-rw-r--r--  1          a          a    11.1KiB 10. Dec 2024 18:32 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp 
-rw-r--r--  1          a          a    58.8KiB 10. Dec 2024 20:20 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.hpp 

scanParameters.FileFilter= fex.CreateFilter(A_CHAR("IndexOf(name,\"camp\")>0"));

drwxr-xr-x 18       root       root     4.0KiB 26. Nov 2024 15:13 STA -- (  0 D   0 F  0 EA  0BL) / 
drwxr-xr-x 16       root       root     4.0KiB 01. Apr 2024 09:22 STA -- (  0 D   0 F  0 EA  0BL) /mnt 
drwxr-xr-x 15          a          a     4.0KiB 29. Mar 2024 11:31 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a 
drwx------ 18          a          a     4.0KiB 03. Dec 2024 20:17 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev 
drwx------ 13          a          a     4.0KiB 15. Dec 2024 07:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx 
drwxr-xr-x  8          a          a     4.0KiB 15. Dec 2024 10:23 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib 
drwxr-xr-x  5          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src 
drwxr-xr-x 20          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib 
drwxr-xr-x  2          a          a     4.0KiB 14. Dec 2024 20:24 REC -- (  0 D   2 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files 
-rw-r--r--  1          a          a     2.8KiB 17. Nov 2024 12:58 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp 
-rw-r--r--  1          a          a    10.2KiB 14. Dec 2024 19:48 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp 

scanParameters.FileFilter= fex.CreateFilter(A_CHAR("EndsWith(Path,\"files\")"));

drwxr-xr-x 18       root       root     4.0KiB 26. Nov 2024 15:13 STA -- (  0 D   0 F  0 EA  0BL) / 
drwxr-xr-x 16       root       root     4.0KiB 01. Apr 2024 09:22 STA -- (  0 D   0 F  0 EA  0BL) /mnt 
drwxr-xr-x 15          a          a     4.0KiB 29. Mar 2024 11:31 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a 
drwx------ 18          a          a     4.0KiB 03. Dec 2024 20:17 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev 
drwx------ 13          a          a     4.0KiB 15. Dec 2024 07:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx 
drwxr-xr-x  8          a          a     4.0KiB 15. Dec 2024 10:23 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib 
drwxr-xr-x  5          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src 
drwxr-xr-x 20          a          a     4.0KiB 14. Dec 2024 20:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib 
drwxr-xr-x  2          a          a     4.0KiB 14. Dec 2024 20:24 REC -- (  0 D  13 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files 
-rw-r--r--  1          a          a    36.5KiB 14. Dec 2024 19:45 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.hpp 
-rw-r--r--  1          a          a    68.2KiB 14. Dec 2024 14:37 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.cpp 
-rw-r--r--  1          a          a     2.8KiB 17. Nov 2024 12:58 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.hpp 
-rw-r--r--  1          a          a    12.6KiB 21. Nov 2024 19:24 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.cpp 
-rw-r--r--  1          a          a    10.2KiB 14. Dec 2024 19:48 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/filescamp.cpp 
-rw-r--r--  1          a          a    17.4KiB 10. Dec 2024 11:28 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/file.cpp 
-rw-r--r--  1          a          a    11.8KiB 21. Nov 2024 13:20 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fileexpressions.hpp 
-rw-r--r--  1          a          a    16.5KiB 10. Dec 2024 13:47 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/fscanner.hpp 
-rw-r--r--  1          a          a     3.1KiB 14. Dec 2024 19:46 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/finfo.cpp 
-rw-r--r--  1          a          a     4.7KiB 09. Dec 2024 08:19 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/textfile.hpp 
-rw-r--r--  1          a          a    11.1KiB 10. Dec 2024 18:32 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ftree.cpp 
-rw-r--r--  1          a          a     2.9KiB 23. Nov 2024 13:50 STA -- (  0 D   0 F  0 EA  0BL) /mnt/a/dev/A-Worx/ALib/src/alib/files/ffilter.hpp 
-rw-r--r--  1          a          a    58.8KiB 10. Dec 2024 20:20 STA -- (  0 D   0 F  0 EA  0BL) /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. Monitoring Changes in an FTree

Class FTree provides several interface methods that allow instances of abstract type FTreeListener to be registered for monitoring changes.

Those are:

• FTree::MonitorDistinctFile,
• FTree::MonitorFilesByName,
• FTree::MonitorPath,
• FTree::MonitorPathPrefix,
• FTree::MonitorPathSubstring, and
• FTree::MonitorStop.

For various reasons it is not - with reasonable effort and efficiency - possible to
trigger the notification events from inside class FTree automatically. Besides this class being just a rather thin layer on top of class StringTree, the class itself can never be sure when, for example, a new file entry is really finally created with all available information set.

For this reason, the notification events have to be triggered by the code entities that manipulate the tree. Notification is performed by callng method

• FTree::Notify

with the according event type set.

Built-in scan functions duly perform such notifications. One warning has to be mentioned: If filter ScanParameters::DirectoryFilterPostRecursion is set, then notification about the creation of files, which later are removed by this filter will occur. On removal, only the node that is removed will be notified, but not the child nodes, which previously had been notified to having been created.
This is a design decision in favor to efficiency.

4. Attaching Custom Data to Files

Class FTree allows attaching a custom object to each node. The memory of this custom object is allocated (and thus recycled with deletion of nodes) using the internal pool allocator.

It is up to the using software to keep track about which data type is assigned to which node of the tree. In the most common cases, where either all nodes receive the same data, or leaf-nodes (files) receive a different type than directories, this is no burden.
With debug-compilations, type information is stored with every node and it is asserted that the same type is received or deleted that was previously set.

The interface provided to manage custom data is comprised by the following methods:

Once this is done, methods of class File:

• File::AttachCustomData,
  
• File::HasCustomData,
  
• File::GetCustomData, and
  
• File::DeleteCustomData.

A convenience method is furthermore provided with:

• FTree::DeleteAllCustomData.

However, this method is only applicable if all nodes have custom data of the same type set.

5. 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 and was extended and overhauled with Version 2412. The future will show how this module expands.

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