ALib Module FileTree - Programmer's Manual

Table of Contents

• 1. Introduction
• 2. Tutorial
  • 2.1 Scanning a File Tree
  • 2.3 Real-Paths
    • 2.3.1 The Symbolic Link Challenge
    • 2.3.2 Reestablishing Symbolic Paths
  • 2.3 Using Filters With Scanning
  • 2.4 Class FileExpressions
• 3. Monitoring Changes in an FTree
• 4. Attaching Custom Data to Files
• 5. Iterating File-Trees
• 6. 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 Cursor and StringTreeIterator, 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 header ALib.FileTree.H.

#include "ALib.FileTree.H"
 
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/filetree") );
 
// A vector to collect the result path(s).
filetree::CanonicalPathList    resultPaths;

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

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

Note that the sample code above uses configuration macro 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 the 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. For this a full lock is needed.
{ALIB_LOCK_WITH(fileTree)
    filetree::ScanFiles(*fileTree, scanParameters, &resultPaths);
}
    
// Dump files to the console. Lock in shared mode (read only)
AString dumpBuffer;
{ALIB_LOCK_SHARED_WITH(fileTree)
    filetree::DbgDump(dumpBuffer, *fileTree);
}
cout << dumpBuffer << endl;

The resulting output is:

drwxr-xr-x  1          a          a       378B 24. Apr 2026 11:15 NON M- (  0 D   0 F  0 EA  0BL) /hub   
drwxr-xr-x  1          a          a       512B 13. May 2026 15:08 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects   
drwxr-xr-x  1          a          a       166B 13. May 2026 15:16 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib   
drwxr-xr-x  1          a          a     3.0KiB 13. May 2026 11:18 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src   
drwxr-xr-x  1          a          a       432B 12. May 2026 20:28 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib   
drwxr-xr-x  1          a          a       576B 12. May 2026 20:28 REC M- (  1 D  25 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree   
drwxr-xr-x  1          a          a       206B 13. May 2026 10:04 REC -- (  0 D   5 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions   
-rw-r--r--  1          a          a    11.9KiB 12. Mar 2026 16:23 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.cpp   
-rw-r--r--  1          a          a    12.0KiB 13. May 2026 10:04 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.hpp   
-rw-r--r--  1          a          a     2.6KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.ixx   
-rw-r--r--  1          a          a     1.2KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.mod.cpp   
-rw-r--r--  1          a          a     1.3KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.uni.cpp   
-rw-r--r--  1          a          a     2.8KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ffilter.hpp   
-rw-r--r--  1          a          a     2.7KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetree.ixx   
-rw-r--r--  1          a          a       785B 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetree.prepro.hpp   
-rw-r--r--  1          a          a     1.2KiB 12. May 2026 20:21 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetree.uni.cpp   
-rw-r--r--  1          a          a     4.0KiB 26. Mar 2026 10:03 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.alibrc   
-rw-r--r--  1          a          a     4.6KiB 26. Mar 2026 10:03 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.cpp   
-rw-r--r--  1          a          a     1.9KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.hpp   
-rw-r--r--  1          a          a     1.1KiB 12. May 2026 16:21 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.mod.cpp   
-rw-r--r--  1          a          a    76.1KiB 10. May 2026 17:14 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/fscanner.cpp   
-rw-r--r--  1          a          a    21.1KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/fscanner.hpp   
-rw-r--r--  1          a          a     1.9KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/fscanner.mod.cpp   
-rw-r--r--  1          a          a     1.8KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/fscanner.uni.cpp   
-rw-r--r--  1          a          a    18.4KiB 23. Apr 2026 06:50 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftfile.cpp   
-rw-r--r--  1          a          a     1.1KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftfile.mod.cpp   
-rw-r--r--  1          a          a    10.9KiB 12. Mar 2026 16:23 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftree.cpp   
-rw-r--r--  1          a          a    61.6KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftree.hpp   
-rw-r--r--  1          a          a     1.2KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftree.mod.cpp   
-rw-r--r--  1          a          a     1.6KiB 26. Mar 2026 07:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftvalue.cpp   
-rw-r--r--  1          a          a    15.5KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftvalue.hpp   
-rw-r--r--  1          a          a     1.1KiB 11. May 2026 11:19 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftvalue.mod.cpp   
 

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;
    Path realPath;
    Path symbolicPath;
    {ALIB_LOCK_SHARED_WITH(fileTree)
        resultPaths.front().AssembleRealPath(    realPath    , lang::Inclusion::Include);
        resultPaths.front().AssembleSymbolicPath(symbolicPath, lang::Inclusion::Include);
    }
    cout << "           real path[0]: " << realPath     << endl;
    cout << "       symbolic path[0]: " << symbolicPath << endl;

This writes:

Number of result paths: 1
           real path[0]: /hub/projects/ALib/src/alib/filetree
       symbolic path[0]: /hub/projects/ALib/src/alib/filetree

So, in this test, we get indeed only one result. Nevertheless, we have can ask the FTFile instance in the vector for two different representations: "symbolic" and "real" path. The "symbolic path" is exactly the path we requested to be scanned. The real path, however, is different. How this relates and how multiple result paths may be returned is explained in the next section.

2.3 Real-Paths

2.3.1 The Symbolic Link Challenge

The invention of symbolic links in the Unix world allowed very flexible ways to organize directories and files. The drawback is, that software might be confused by such links, and many applications and tools exist do not handle symbolic links correctly. If done wrongly, circular references can easily occur and let a software, for example one that scans a file tree, run into an endless loop.

This library avoids this problem in the only possible efficient way: It always uses the real path of a file or directory. If a "real" directory is it twice, the recursion stops.

For this, the function ScanFiles defines a "data contract". Instead of repeating its definition here, we ask the reader to read about this here right now.

With this information in mind, we can now answer the question of why the result when scanning just one single path is a vector of paths! Here is a sample:

Suppose we have the following directory structure:
    /a/a 
    /b/b 
    /b/link -> /a/a

Scanning the directory /b leads to the following result paths:
    /a/a 
    /b/b 

So, one simple link into a sibling path of the start-path leads to two results already.

2.3.2 Reestablishing Symbolic Paths

The approach taken by the library to handle symbolic links leads to 100% correct scan results, detects circular references, and is extremely efficient in respect to common approaches of other software. Also, software that uses the result trees will not be confused by symbolic links and will never need to care about them.

However, at the moment software displays the scanned file's paths back to the user or to other software, presenting real-paths can be a problem. For example, if a tool processes source code files and lists some results to be "clickable" an an IDE's output tool window, most IDEs (including CLion) do not detect that the presented file is the as registered with the IDE using a symbolic path. With that, the IDE opesn the same source-file twice, once with the symbolic path (the one it knew before) and once with the real path! The IDE would maybe even ask: "Do you want to edit files outside your project?"

To avoid this, class FTFile offers a special parent node, accessible with
FTFile::GetSymbolicParent. As its name suggests, this method returns the symbolic link that
the scanner followed to hit that file or directory. Custom scanners (or other code that manipulates a FTree) can use the method FTFile::SetSymbolicParent to provide similar information. In the case that no symbolic link was followed, the method returns the same object that the code

    FTFile ( myFile.AsCursor().Parent() )

would receive.

Consequently, class FTFile offers two methods:

• FTFile::AssembleSymbolicPath, and
• FTFile::AssembleRealPath.

Note

It is also possible to directly use the StringTree's functionality provided with the method TCursor::AssemblePath. This can be accessed with:

  myFile.AsCursor().AssemblePath(...);

Here, of course, it is always the real path that is returned. If you can answer to yourself why this is, you have understood ALib's architecture in
respect to the classes StringTree / Cursor and FTree / FTFile very well!

As a final remark: The function ScanFiles sets the symbolic parent only when the file or directory was not scanned already - either through the real path or a different symbolic link. This means that the symbolic parent is set only once and its setting depends on the order of the scanned files, and, in case of multiple scans, the order of their start paths.

Attention

Symbolic parent information stores backlinks to other nodes in the tree. Therefore, if symbolic paths are needed, nodes that participate in those links must stay alive. In other words: avoid deleting nodes after scanning, and avoid scan filters/options that delete nodes while scanning (for example, post-recursion filtering or empty-directory removal), because this can invalidate symbolic path reconstruction.
The library does not check for this, and it is the responsibility of the user to ensure that symbolic parent information is not invalidated by deleting nodes or using filters that delete nodes during scanning. The reason that this is not implemented is that symbolic parent information is not needed in many cases, and in the case it is needed, usually no node deletion is needed.

But stay warned: mixing both, symbolic path retrieval and arbitrary node deletion, can lead to hard crashes (undefined behavior) of your software!

2.3 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 runtime compiled!

2.4 Class FileExpressions

In case module ALib Expressions is included in the ALib Build, this module ALib FileTree exposes the FileExpressions class, which implements a CompilerPlugin that allows articulate runtime expressions working with FTValue objects.

The class exposes the public inner type 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 runtime of your software), the result type of an expression can be checked.

We just look at some samples:

We have to add the header-file ALib.FileTree.Expressions.H:

#include "ALib.FileTree.Expressions.H"

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
fileTree.DbgCriticalSections(lang::Switch::Off); // we access this tree only from one thread
ScanParameters              scanParameters(ALIB_BASE_DIR  A_PATH("/src/alib/filetree") );
CanonicalPathList           resultPaths;
 
// create the expression compiler and let it compile a filter
FileExpressions fex;
scanParameters.FileFilter= fex.CreateFilter(A_CHAR("name = \"files.mpp\""));
 
// Scan files
filetree::ScanFiles( *fileTree, scanParameters, &resultPaths);

The resulting output is:

drwxr-xr-x  1          a          a       378B 24. Apr 2026 11:15 NON M- (  0 D   0 F  0 EA  0BL) /hub   
drwxr-xr-x  1          a          a       512B 13. May 2026 15:08 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects   
drwxr-xr-x  1          a          a       166B 13. May 2026 15:16 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib   
drwxr-xr-x  1          a          a     3.0KiB 13. May 2026 11:18 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src   
drwxr-xr-x  1          a          a       432B 12. May 2026 20:28 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib   
drwxr-xr-x  1          a          a       576B 12. May 2026 20:28 REC M- (  1 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree   
drwxr-xr-x  1          a          a       206B 13. May 2026 10:04 REC -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions   

Here are some more samples:

scanParameters.FileFilter= fex.CreateFilter(A_CHAR("size > kilobytes(10)"));

drwxr-xr-x  1          a          a       378B 24. Apr 2026 11:15 NON M- (  0 D   0 F  0 EA  0BL) /hub   
drwxr-xr-x  1          a          a       512B 13. May 2026 15:08 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects   
drwxr-xr-x  1          a          a       166B 13. May 2026 15:16 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib   
drwxr-xr-x  1          a          a     3.0KiB 13. May 2026 11:18 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src   
drwxr-xr-x  1          a          a       432B 12. May 2026 20:28 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib   
drwxr-xr-x  1          a          a       576B 12. May 2026 20:28 REC M- (  1 D   8 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree   
drwxr-xr-x  1          a          a       206B 13. May 2026 10:04 REC -- (  0 D   2 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions   
-rw-r--r--  1          a          a    11.9KiB 12. Mar 2026 16:23 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.cpp   
-rw-r--r--  1          a          a    12.0KiB 13. May 2026 10:04 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.hpp   
-rw-r--r--  1          a          a    76.1KiB 10. May 2026 17:14 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/fscanner.cpp   
-rw-r--r--  1          a          a    21.1KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/fscanner.hpp   
-rw-r--r--  1          a          a    18.4KiB 23. Apr 2026 06:50 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftfile.cpp   
-rw-r--r--  1          a          a    10.9KiB 12. Mar 2026 16:23 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftree.cpp   
-rw-r--r--  1          a          a    61.6KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftree.hpp   
-rw-r--r--  1          a          a    15.5KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftvalue.hpp   

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

drwxr-xr-x  1          a          a       378B 24. Apr 2026 11:15 NON M- (  0 D   0 F  0 EA  0BL) /hub   
drwxr-xr-x  1          a          a       512B 13. May 2026 15:08 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects   
drwxr-xr-x  1          a          a       166B 13. May 2026 15:16 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib   
drwxr-xr-x  1          a          a     3.0KiB 13. May 2026 11:18 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src   
drwxr-xr-x  1          a          a       432B 12. May 2026 20:28 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib   
drwxr-xr-x  1          a          a       576B 12. May 2026 20:28 REC M- (  1 D   8 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree   
drwxr-xr-x  1          a          a       206B 13. May 2026 10:04 REC -- (  0 D   2 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions   
-rw-r--r--  1          a          a    11.9KiB 12. Mar 2026 16:23 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.cpp   
-rw-r--r--  1          a          a    12.0KiB 13. May 2026 10:04 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions/fileexpressions.hpp   
-rw-r--r--  1          a          a     1.2KiB 12. May 2026 20:21 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetree.uni.cpp   
-rw-r--r--  1          a          a     4.0KiB 26. Mar 2026 10:03 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.alibrc   
-rw-r--r--  1          a          a     4.6KiB 26. Mar 2026 10:03 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.cpp   
-rw-r--r--  1          a          a     1.1KiB 12. May 2026 16:21 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.mod.cpp   
-rw-r--r--  1          a          a    18.4KiB 23. Apr 2026 06:50 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftfile.cpp   
-rw-r--r--  1          a          a    10.9KiB 12. Mar 2026 16:23 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/ftree.cpp   

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

drwxr-xr-x  1          a          a       378B 24. Apr 2026 11:15 NON M- (  0 D   0 F  0 EA  0BL) /hub   
drwxr-xr-x  1          a          a       512B 13. May 2026 15:08 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects   
drwxr-xr-x  1          a          a       166B 13. May 2026 15:16 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib   
drwxr-xr-x  1          a          a     3.0KiB 13. May 2026 11:18 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src   
drwxr-xr-x  1          a          a       432B 12. May 2026 20:28 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib   
drwxr-xr-x  1          a          a       576B 12. May 2026 20:28 REC M- (  1 D   4 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree   
drwxr-xr-x  1          a          a       206B 13. May 2026 10:04 REC -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions   
-rw-r--r--  1          a          a     4.0KiB 26. Mar 2026 10:03 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.alibrc   
-rw-r--r--  1          a          a     4.6KiB 26. Mar 2026 10:03 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.cpp   
-rw-r--r--  1          a          a     1.9KiB 11. May 2026 11:22 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.hpp   
-rw-r--r--  1          a          a     1.1KiB 12. May 2026 16:21 STA -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/filetreecamp.mod.cpp   

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

drwxr-xr-x  1          a          a       378B 24. Apr 2026 11:15 NON M- (  0 D   0 F  0 EA  0BL) /hub   
drwxr-xr-x  1          a          a       512B 13. May 2026 15:08 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects   
drwxr-xr-x  1          a          a       166B 13. May 2026 15:16 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib   
drwxr-xr-x  1          a          a     3.0KiB 13. May 2026 11:18 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src   
drwxr-xr-x  1          a          a       432B 12. May 2026 20:28 NON M- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib   
drwxr-xr-x  1          a          a       576B 12. May 2026 20:28 REC M- (  1 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree   
drwxr-xr-x  1          a          a       206B 13. May 2026 10:04 REC -- (  0 D   0 F  0 EA  0BL) /hub/projects/ALib/src/alib/filetree/expressions   

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:

• void MonitorDistinctFile(lang::ContainerOp, FTreeListener*, FTreeListener::Event, const FTFile&) ,
• void MonitorFilesByName(lang::ContainerOp, FTreeListener*, FTreeListener::Event, const PathString&) ,
• void MonitorPath(lang::ContainerOp, FTreeListener*, FTreeListener::Event, const FTree::Cursor&) ,
• void MonitorPathPrefix(lang::ContainerOp, FTreeListener*, FTreeListener::Event, const PathString&) ,
• void MonitorPathSubstring(lang::ContainerOp, FTreeListener*, FTreeListener::Event, const PathString&) , and
• int MonitorStop(FTreeListener*) .

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 calling the method

• void Notify(FTreeListener::Event, FTFile, const PathString&) 

with the according event type set.

Built-in scan functions duly perform such notifications. One warning has to be mentioned: If filter SPFileFilter 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 of gaining 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 FTFile:

• TCustom & AttachCustomData(TArgs&& ...) ,
• bool HasCustomData() const,
• TCustom & GetCustomData() , and
• void DeleteCustomData() .

A convenience method is furthermore provided with:

• void DeleteAllCustomData() .

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

5. Iterating File-Trees

For iterating scanned FTrees, class StringTreeIterator, provided with the module ALib Containers, is very convenient.

Here is quick sample code taken from the debug-function DbgDump:

// create and configure iteratator
StringTreeIterator<FTree> stit;
stit.SetPathGeneration(lang::Switch::Off);
stit.SetMaxDepth( depth );
stit.Initialize ( startNode, startNode.IsRoot() ? lang::Inclusion::Exclude
                                                : lang::Inclusion::Include );
// loop over all nodes and dump
while( stit.IsValid()) {
    if( includedTypes.Test(stit.Node()->Type()))
        fmt.Format( target, DBG_DUMP_FORMAT, FTFile(stit.Node())  );
    stit.Next();
}

As you can see from this sample, to access the file information during iteration, the StringTree::Cursor received with the method Node has to be wrapped in an instance of class FTFile. (For the optimizing compiler, this is a no-op.)

Further options are available, for example, to sort the files and directories with custom sorters which could be implemented using runtime expressions.

For all information consult the reference documentation of class StringTreeIterator.

6. Outlook

This should be enough for the time being. Module ALib FileTree is quite new and was introduced only with ALib C++ Framework 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.