alib::files Namespace Reference

Description:

This is the reference documentation of module ALib Files 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::files.
namespace	std

Type Index:
struct	CanonicalPathList
struct	FFilter
class	File
class	FileExpressions
class	FilesCamp
class	FInfo
	The entry type which is embedded in each tree node. More...
class	FTree
struct	FTreeListener
class	OwnerAndGroupResolver
struct	ScanParameters
	Input parameters to function ScanFiles. More...
struct	TextFileLineReader
struct	TSharedFTree
class	TTextFile

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

Function Index:
AString &	DbgDump (AString &target, FTree &tree, EnumBitSet< FInfo::Types > includedTypes=EnumBitSet< FInfo::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)
FInfo::ScanStates	MakeCanonical (Path &sourcePath, FTree::Cursor &node, Path &pathToNode, CanonicalPathList *resultPaths=nullptr)
FInfo::ScanStates	ScanFiles (FTree &tree, ScanParameters &parameters, CanonicalPathList *resultPaths=nullptr, Path *remainingStart=nullptr)
	TextFileLineReader (const CString &) -> TextFileLineReader< 1024 >
	Deduction guide fixing emtplate parameter #TLocalBufferSize to its default 1024.
	TextFileLineReader (files::File) -> TextFileLineReader< 1024 >
	Deduction guide fixing emtplate parameter #TLocalBufferSize to its default 1024.

Variable Index:
String	DBG_DUMP_FORMAT
String	DBG_FILES_SCAN_VERBOSE_LOG_FORMAT

Type Definition Details:

SPFileFilter

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

A shared pointer to a filter.

Definition at line 44 of file ffilter.inl.

Function Details:

DbgDump()

AString & alib::files::DbgDump	(	AString &	target,
		FTree &	tree,
		EnumBitSet< FInfo::Types >	includedTypes = EnumBitSet< FInfo::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::files::FFormat_File	(	const Box &	box,
		const String &	formatSpec,
		NumberFormat &	nf,
		AString &	target )

This implementation of boxing function FFormat for objects of type File, 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 FILES 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 455 of file file.cpp.

MakeCanonical()

FInfo::ScanStates alib::files::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 targeted node, can re-establish the file-path as originally specified. This is done with the method AssembleSymbolicPath.

Note

This function is mainly used by the function ScanFiles and a direct use is seldom needed.

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 when the method returns. 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 is an absolute path, this node is changed to the root folder of the FTree. 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 points to the then moved node. When the method exits this contains the path to the modified node not scanned, yet.
[in,out]	resultPaths	Todo

Returns

The scan state of the target node. This should usually be STATS or RESOLVED. In case of failure, NOT_EXISTENT or other scan state values that indicate failure are returned.

ScanFiles()

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

General Information

Scans the filesystem according to the given ScanParameters and adds FInfo 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
• 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:

1. A posix version for posix compatible OSes,
2. 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::files::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_FILES_SCAN_VERBOSE_LOG_FORMAT

String alib::files::DBG_FILES_SCAN_VERBOSE_LOG_FORMAT

extern

The format string used with verbose logging to domain /ALIB/FILES/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}"