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.
A simple application needs to include just headers alib/files/ftree.hpp and alib/files/fscanner.hpp :
For scanning a path including its subdirectories, a few objects are needed:
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:
The resulting output is:
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:
This writes:
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.
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!
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 :
Now this code compiles:
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:
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
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
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
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
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.