This class represents nodes in FTree instances. While class FTree is just a rather small wrapper around its base class StringTree, this class File is a wrapper around class Cursor. With that, instances of this class are very lightweight and contain only two pointers: One pointing to the FTree that an instance originates from, the second pointing to the node in the tree.
It is important to understand that this class has three interfaces.
- The direct interface as exposed with this class.
- Using
operator-> the attached data instance of type FInfo is accessed.
- The method AsCursor casts an instance to the (otherwise protected) type Cursor of the underlying string tree.
To get a thorough understanding of why this split exists and what purpose which of the three interfaces serve, a basic understanding of container type class StringTree is very helpful. A similar design principle is implemented with class Variable of module ALib Variables. A technical explanation to why base class FTree::Cursor is protected there in the same fashion is given here.
- See also
- For a quick tutorial about using ALib files, consult the tutorial-style Programmer's Manual of camp ALib Files.
- For this class, a pretty printer for the GNU debugger is provided.
- Instances of this type are appendable to class AString. If done, the full path and file name is written to the target string.
Definition at line 640 of file ftree.inl.
Writes formatted information on this file to the given string buffer target. Within the pattern string format, different symbols are interpreted as tokens. Spaces between tokens are written as given. Strings within the format text that should not be interpreted as tokens may be given in single quotes. Two consecutive single quotes will be replaced to one single quote.
Tokens are defined in lower case letters. If given with upper case letters, the generated string is converted to upper case letters.
This method supports the following tokens:
| Token | Description |
| a | Invokes FormatAccessRights. |
| b | In case this node has a symbolic parent, prints " <- symbolicparent". The symbolic parent is always an absolute path. |
| dm{DATEFORMAT} | The modification date of this file. This token is optionally followed by a "DATEFORMAT" string given in curly braces. For specification information, see AString & Format(Substring, AString&, lang::CurrentData) const. |
| db{DATEFORMAT} | Same as 'dm', but uses the creation date of this file. |
| dc{DATEFORMAT} | Same as 'dm', but uses the change date of this file. |
| da{DATEFORMAT} | Same as 'dm', but uses the date of last access to this file. |
| fx | Prints 'm' if IsCrossingFS returns true, '-' otherwise. |
| fa | Prints 'a' if IsArtificialFS returns true, '-' otherwise. |
| gi[{width[,alignment]}] | The ID of the user group of the file. |
| gn[{width[,alignment]}] | The name of the user group of the file. |
| h | The number of hard links pointing to this file. |
| l | In case of Symbolic links, prints " -> linktarget". If the linktarget is a relative path, then the absolute path is appended in round brackets. |
| na | The name of the file. |
| ns | The stem of the file. |
| ne | The extension of the file. |
| np | The symbolic path to the file, excluding the file name and a trailing separation character. |
| nf | The symbolic path to the file, including the file name and excluding a trailing separation character. |
| nr | The real path to the file, excluding the file name and a trailing separation character. |
| nx | The real path to the file, including the file name and excluding a trailing separation character. |
| oi[{width[,alignment]}] | The ID of the owner of the file. |
| on[{width[,alignment]}] | The name of the owner of the file. |
| q | The scan state printed as resourced with enum ScanStates. |
| rd | Recursively counted subfolders. |
| rf | Recursively counted files. |
| re | Recursively counted access errors. |
| rb | Recursively counted broken links. |
| qqq | The scan ScanStates, encoded in three characters. The conversion is resourced with enum ScanStates3Letters. |
| s[{unit}] | The size of the file. See the explanation below. |
| t | The type, encoded in a single character. The conversion is resourced with enum TypeNames1Letter. |
| tt | The type, encoded in two characters. The conversion is resourced with enum TypeNames2Letters. |
| ttt | The type, encoded in three characters. The conversion is resourced with enum TypeNames3Letters. |
| tttt | The type, as a full word. The conversion is resourced with enum Types. |
- Fields and Alignment
- Any of the tokens above may be followed by {width[,Alignment]}. In words: a pair of curly braces that contains an integral value specifying a field width and, optionally and separated by a comma, an alignment specifier. (The optional alignment specifier is parsed using enum records.) If so, a corresponding field, using spaces as padding character, is printed.
- Printing sizes:
- Token
"s[(unit)]" is used to print file sizes. The optional unit string in curly braces may have one the following values:
IEC: Chooses IEC standard with automatic detection of an appropriate magnitude. The unit of the magnitude found ("B", "KiB", "MiB", "GiB",...) is added to the output. This is the default if the optional unit-partis omitted.SI: Chooses SI standard with automatic detection of an appropriate magnitude. The unit of the magnitude found ("B", "kB", "MB", "GB",...) is added to the output.- One of the more than 20 possible entity names of either IEC or SI standard. In this case, the unit is not included after the number, because this way it can be optionally added to the format string by using a pair of single quotes
'.
- With the two automatic modes
IEC and SI, the namespace function FormatByteSize is used.
- For formatting the file size numbers, this method retrieves formatting hints with NumberFormat & GetNumberFormat() . With that, the details of the format can be specified "per FTree". Manipulations of this object before invoking this method, allows specifying output widths, group characters, decimal separation character, and so forth.
- Printing owner and group:
- For printing owner and group names, those have to be queried from the OS. To increase performance, the resolver utility instance received with const OwnerAndGroupResolver & GetOGResolver() const is used. The use of this instance has to be protected against racing conditions in multithreaded applications. This means if two threads invoke this method on File object that belong to the same FTree, a locking mechanism has to be used, to avoid undefined behavior. (For example, by using the class Lock.)
- Sample
- As a sample, the following format string mimics the output of GNU/Linux console command ls -l:
"ta h on gn s dm nal"
- See also
- This method is invoked by FFormat_File, which is an implementation of box-function FFormat. With hat, objects of this type can be used as arguments for FormatterPythonStyle. The format specifier passed to this method has to be placed behind the colon in the placeholder field, as in
"{:FORMATSPEC}". If no format string is given in the placeholder, the string "ta h on gn s dm nal" is used, which is resourced in camp FILES under key "FFMT".
- Parameters
-
| format | The format pattern string. |
| target | A reference to an AString that gets the result of the format processing appended. |
| targetData | If CurrentData::Keep (the default) the string is appended to target. if CurrentData::Clear, target is cleared. |
| numberFormat | The number format specification to use. Defaults to nullptr which chooses static TNumberFormat Computational. |
- Returns
- target (for convenience).
Definition at line 140 of file file.cpp.
