Description:

This is the reference documentation of module ALib FileTree of the ALib C++ Framework.

See also: A user manual with tutorial-style sample code is found in the Programmer's Manual of this module.

Nested Namespaces:
namespace	detail
	This namespace implements internals of namespace alib::filetree.
namespace	std

Type Index:
struct	CanonicalPathList
struct	CanonicalResult
	Result information from MakeCanonical. More...
struct	FFilter
class	FileExpressions
class	FilesCamp
class	FTFile
class	FTree
struct	FTreeListener
class	FTValue
class	OwnerAndGroupResolver
struct	ScanParameters
	Input parameters to function ScanFiles. More...
struct	TSharedFTree

Type Definition Index:
using	SPFileFilter = std::shared_ptr<FFilter>
	A shared pointer to a filter.

Enumeration Index:
enum class	PathRootKind { Errorneous , Relative , AbsoluteRoot , DriveLetter , UNC , URL , Device }
	Classification of path root formats that cannot be directly scanned. More...

Function Index:
AString &	DbgDump (AString &target, FTree &tree, EnumBitSet< FileStatus::Types > includedTypes=EnumBitSet< FileStatus::Types >(true), FTree::Cursor startNode=FTree::Cursor(), unsigned depth=(std::numeric_limits< unsigned int >::max)())
void	FFormat_File (const Box &box, const String &formatSpec, NumberFormat &nf, AString &target)
CanonicalResult	MakeCanonical (Path &sourcePath, FTree::Cursor &node, Path &pathToNode, CanonicalPathList *resultPaths=nullptr)
FTValue::ScanStates	ScanFiles (FTree &tree, ScanParameters &parameters, CanonicalPathList resultPaths=nullptr, Path remainingStart=nullptr)

Variable Index:
String	DBG_DUMP_FORMAT
String	DBG_FILETREE_SCAN_VERBOSE_LOG_FORMAT

Type Definition Details:

◆ SPFileFilter

using alib::filetree::SPFileFilter = std::shared_ptr<FFilter>

A shared pointer to a filter.

Definition at line 43 of file ffilter.hpp.

Enumeration Details:

◆ PathRootKind

enum class alib::filetree::PathRootKind

strong

Classification of path root formats that cannot be directly scanned.

Enumerator
Errorneous	Errorneous path format.
Relative	Relative path (no special root).
AbsoluteRoot	Unix-style absolute path starting with /.
DriveLetter	Windows drive letter (C:, D:, etc).
UNC	Universal Naming Convention (\\server\share).
URL	URL scheme (http://, ftp://, file://, etc).
Device	Windows device path (\\.\...).

Definition at line 241 of file fscanner.hpp.

Function Details:

◆ DbgDump()

AString & alib::filetree::DbgDump	(	AString &	target,
		FTree &	tree,
		EnumBitSet< FileStatus::Types >	includedTypes = EnumBitSet< FileStatus::Types >(true),
		FTree::Cursor	startNode = FTree::Cursor(),
		unsigned	depth = (std::numeric_limits< unsigned int >::max)() )

Dumps the given branch of this object's tree.
This function is only available with debug-compilations.

Parameters

target	The target string buffer.
tree	The tree to dump.
includedTypes	Optional filter for types. Defaults to 'all'.
startNode	The start node. If this is not valid, the root node is chosen. Defaults to an invalid cursor.
depth	The maximum depth of recursion. Defaults to unlimited depth.

Returns: The given target to allow concatenated operations.

◆ FFormat_File()

void alib::filetree::FFormat_File	(	const Box &	box,
		const String &	formatSpec,
		NumberFormat &	nf,
		AString &	target )

This implementation of boxing function FFormat for objects of type FTFile, simply invokes the method AString & Format(Substring, AString&, lang::CurrentData, NumberFormat*) const and thus, using the format specification is given with that method.

Note that the NumberFormat instance used for formatting file sizes and similar, does not use the instance given with parameter nf. Instead, the instance retrieved with NumberFormat & GetNumberFormat() is used. This feature enables to determine the number format separately for file data output, independent of the settings the formater uses.

If the parameter formatSpec is empty, the string "ta h on gn s dm nal" is used, which is resourced in camp FILETREE under the key "FFMT".

Parameters

box	The box containing the file object.
formatSpec	The format string.
nf	The number format specification to use.
target	The target string to write to.

Definition at line 417 of file ftfile.cpp.

Here is the call graph for this function:

◆ MakeCanonical()

CanonicalResult alib::filetree::MakeCanonical	(	Path &	sourcePath,
		FTree::Cursor &	node,
		Path &	pathToNode,
		CanonicalPathList *	resultPaths = nullptr )

Analyses the given sourcePath and converts it to its canonical version. This is similar to what the POSIX function realpath() and C++ std::filesystem::canonical do.
This version, in addition, creates corresponding nodes in the FTree (passed indirectly with the parameter node). Besides removing "." and ".." entries, symbolic links are not only resolved, but the nodes they are targeting receive information about the link that targeted them. This information is set with the method SetSymbolicParent. With that, the path of directories or files that are children of such a targeted node, can re-establish the file-path as originally specified. This is done with the method AssembleSymbolicPath.

Path Root Detection and Tree Representation

The method detects and handles various path root formats, creating appropriate tree nodes:

Relative paths (Relative):
No special root. The path is resolved relative to the provided node.
Example: "foo/bar"
Absolute paths (AbsoluteRoot):
Unix-style absolute paths starting with '/'.
Tree node: positioned at tree root with path '/'.
Example: "/usr/local/bin" → root node
URL schemes (URL):
Format: scheme:// where scheme is alphanumeric with +, -, or ..
Tree node: child of root named with the scheme (e.g., http, ftp).
The node is marked as type SOCKET with state NOT_EXISTENT (unscannable virtual node).
Examples: http://example.com → node http, file://path → node file
Windows drive letters (DriveLetter):
Format: C:, C:\, or C:/.
Tree node: child of root named with the drive letter (e.g., C:).
Examples: C:\Windows → node "C:", "D:/data" → node "D:"
(Windows only.)
UNC paths (UNC):
Universal Naming Convention for network shares: \\ or //.
Tree node: positioned at the root with path //.
Examples: \\server\share or //server/share → root node with //.
(Windows only.)
Windows device paths (Device):
Format: \\.\... or //./....
Tree node: child of root with synthesized name starting with DEV.
The remaining path is encoded with colons replacing separators.
The node is marked as type SOCKET with state NOT_EXISTENT (unscannable virtual node).
Examples: \\.\C: → node DEV:C:, \\.\UNC\server → treated as UNC after normalization.
(Windows only.)

Note: The detected PathRootKind is returned in the result and should be preserved by callers if they need to distinguish between root types later, as the node name alone is not always sufficient to unambiguously identify the root kind (e.g., a drive letter C: vs. a scheme c: from URL c://...).; This function is used by the function ScanFiles to resolve the start path and symbolic link targets.

Parameters

[in,out]	sourcePath	The path to scan. This might contain `"."` and `".."` directories, as well as symbolic links. When the method exits successfully, this path is empty. Otherwise, this path-string contains the remaining path, starting with the name of the file or directory that could not be found, accessed, or otherwise be resolved.
[in,out]	node	The starting node. In case the parameter sourcePath contains a root specification (absolute path, URL, etc.), this node is moved to the appropriate position in the tree (often the root). When the method exits successfully, this cursor targets the file that the source path resolved to. In case of failure, this cursor becomes invalid.
[in,out]	pathToNode	This path has to point to the given node when the method is called. When the method returns, it contains the canonical path to the then repositioned node.
[in,out]	resultPaths	Optional pointer to a CanonicalPathList that receives nodes for newly created paths during resolution.

Returns

A CanonicalResult containing:

RootKind: The detected path root format
ScanState: The scan state indicating success or failure:
NONE (new node created), DUPLICATE (already existed), STATS or RESOLVED (successfully scanned), NOT_EXISTENT (path not found), or other error states.

◆ ScanFiles()

FTValue::ScanStates alib::filetree::ScanFiles	(	FTree &	tree,
		ScanParameters &	parameters,
		CanonicalPathList *	resultPaths = nullptr,
		Path *	remainingStart = nullptr )

General Information

Scans the filesystem according to the given ScanParameters and adds FTValue entries to the given FTree.

ALib FTree Data Contract

This function has a contract with the class FTree that is used to store the scan results. This contract states that any file or directory found during a scan is always stored using the "Real Path" of the entry. This means that any symbolic link is resolved. The consequences are:

Files and directories which represent a symbolic link are always "leaf nodes". (They never contain child nodes.). However, their symlink target path is attached twice to the entry:
1. The original link information given, which often uses relative path addressing.
2. The absolute, "Real Path" of the target, which has a corresponding result entry in the given FTree.
If a using software wants to use symbolic paths, for example, to present them to the end user, such paths have to be assembled by the user's code in own responsibility. All information for doing this is provided in the resulting tree object
If symbolic path reconstruction is needed, nodes that participate in symbolic backlinks must stay alive. Therefore, deleting nodes after scanning (or enabling scan options that delete nodes during scanning) is not compatible with this feature.
Doubly linked target files and directories are never a problem for this scanner. Each file is scanned only once. This especially prevents all sorts of problems that would otherwise occur with cyclic symbolic links.
Due to this, even the given start path of a search might not be found as a result in the given FTree, because also start paths are converted to a Real Path.
The scan result may contain more than one resulting path. This happens if a symbolic link targets a file or directory not recursively included in the start path. The resulting "Real Path" of the given start path is, however, always the first result added.

The latter is reflected with (optional) parameter resultPaths of this function, which is of type CanonicalPathList.

Note: Because the class FTree is based on class StringTree, using code is enabled to break this contract by adding entries below symbolic links. Other entities of this ALib Module will not break this contract.

Rescanning of Entries

Existing entries in the given tree are not overwritten. They might be scanned with "higher" ScanStates values, depending on given parameters and how they had been scanned before. If the same "level" of scanning is provided, existing entries will not be scanned again. If a rescan of a certain path is wanted, then the target entry of that path has to be deleted before invoking this function. Due to the implementation of class FTree, repeated delete and scan operations will not cause any heap-memory allocations or deallocations.

platform-dependent Code Selection

File scanning is a platform-dependent task and hence ALib uses one of two different implementations:

A POSIX version for compatible OSes,
A version that relies on C++ std::filesystem.

The fallback version using std::filesystem has the following restrictions:

The only time attribute available is the modification time of an entry. The fields BDate, CDate, and ADate are always set to the same as the modification time, even on filesystems that support the other values.
The file time of symbolic links is always that of the target file. The C++ standard has no possibility to access the link's time itself.
The file time of broken symbolic links is set to the current time (time of scanning).
The size that directories occupy on a disk cannot be determined. Directory entries always report size 0.
The target of a symbolic link which points to a non-accessible directory, cannot be resolved to a "real" (aka canonical) path, even if all other path components before were accessible. (This is true for the implementation of the standard library under GNU/Linux and Clang compiler at the time of writing this, 2024/02.)
The flag bool CrossFileSystems is ignored. Crossing Filesystems cannot be detected using purely the standard library.
A files' owner and owning group is not determined. Instead, static constexpr TOwnerAndGroupID UnknownID is set for both.
The scanning process is half as fast as in the Posix version. The reason for this is probably the internal allocation and deallocation of many quite volatile string objects in the C++ standard library. Well, but it is still fast though!

Note: As for today, using this module under WindowsOS, will fall back to the C++ std::filesystem version. It may be that a future version will provide a native implementation of this target system. Volunteers from the community are welcome to contribute.

Parameters

	tree	The tree to fill.
	parameters	The input parameters to determine the scan process.
[out]	resultPaths	An optional container to store the result paths of a scan. If `nullptr` is given, the result paths are not collected. See the types documentation for further information.
[out]	remainingStart	An optional path string. If given, on failure, it will receive the remainder of the path given with ScanParameters::StartPath starting with the first directory or file that could not be resolved or accessed.

Returns: The scan state code of the tree node of the first resulting path, hence of the node referred to by the given ScanParameters::StartPath.
On error, i.e. if the start path was invalid, not accessible, a broken link, a circular link, or other failures, NOT_EXISTENT is returned.

Variable Details:

◆ DBG_DUMP_FORMAT

String alib::filetree::DBG_DUMP_FORMAT

extern

The format string used with namespace function DbgDump.
Defaults to "{:ta h{2,r} on{10,r} gn{10,r} s(IEC){10,r} dm qqq FxFa (rd{3r}' D' rf{3r}' F' re{2r}' EA' rb{2r}'BL) 'nf l}\n"
This global variable is only available with debug-compilations.

◆ DBG_FILETREE_SCAN_VERBOSE_LOG_FORMAT

String alib::filetree::DBG_FILETREE_SCAN_VERBOSE_LOG_FORMAT

extern

The format string used with verbose logging to domain /ALIB/FILETREE/SCAN by the namespace function ScanFiles.
Defaults to " {:ta h{2,r} on{10,r} gn{10,r} s(IEC){10,r} dm qqq nf l}"

Description:

Nested Namespaces:

Type Index:

Type Definition Index:

Enumeration Index:

Function Index:

Variable Index:

Type Definition Details:

◆ SPFileFilter

Enumeration Details:

◆ PathRootKind

Function Details:

◆ DbgDump()

◆ FFormat_File()

◆ MakeCanonical()

Path Root Detection and Tree Representation

◆ ScanFiles()

General Information

ALib FTree Data Contract

Rescanning of Entries

platform-dependent Code Selection

Variable Details:

◆ DBG_DUMP_FORMAT

◆ DBG_FILETREE_SCAN_VERBOSE_LOG_FORMAT