diff --git a/docs/xml/lazutils/lazfilecache.xml b/docs/xml/lazutils/lazfilecache.xml index ee941ed174..209b9270cd 100644 --- a/docs/xml/lazutils/lazfilecache.xml +++ b/docs/xml/lazutils/lazfilecache.xml @@ -1,13 +1,11 @@ - - Implements a caching mechanism for file and directory state information. @@ -30,7 +28,6 @@ IDE, and in the LCL package system. - Represents flag values used for files or directories in the @@ -53,47 +50,38 @@ class. - File or directory exists. - File exists and is a directory. - File is readable. - File is writable. - File is a directory and can be searched. - File is a directory and allows new files to be created. - File is a text (not an executable binary) file. - File is an executable binary file. - file age is valid. @@ -102,7 +90,6 @@ class. Physical file name for the file is valid. - Set type used to store TFileStateCacheItemFlag enumeration values. @@ -115,7 +102,6 @@ Set type used to store TFileStateCacheItemFlag enumeration values. - Contains information about a file or directory in the state caching mechanism. @@ -139,14 +125,14 @@ TFileStateCacheItem is the type creates and stored in the internal AVL tree in - + - + Constructor for the class instance. @@ -167,17 +153,14 @@ initial values for the following properties: - Name for the file or directory in the cache item. - Timestamp value for the file or directory. - Gets the memory size needed to store the class instance. @@ -188,14 +171,12 @@ initial values for the following properties: - Number of bytes needed to store the class instance and its assigned data. - Name for the file or directory in the cache item. @@ -214,7 +195,6 @@ Number of bytes needed to store the class instance and its assigned data. - Contains status flags for the cached file or directory item. @@ -224,7 +204,6 @@ Number of bytes needed to store the class instance and its assigned data. - Contains status flags that have been tested for the cached item. @@ -236,7 +215,6 @@ Contains status flags that have been tested for the cached item. - Timestamp for the cached item. @@ -261,7 +239,6 @@ invalid. - FileAge value for the file or directory. @@ -280,7 +257,6 @@ from the FileAge routine in SysUtils. - Specifies an event handler signalled when the timestamp for a cached item @@ -290,17 +266,14 @@ is changed. - Object instance for the event notification. - Name for the affected file or directory. - Implements a state caching mechanism for files and directories. @@ -331,13 +304,12 @@ access and verify state flags for the TFileStateCacheItem instances. - + - Includes or excludes a value in the Flags property. @@ -348,10 +320,12 @@ access and verify state flags for the TFileStateCacheItem instances. Identifies the Flag affected in the method. -True to include the flag, False to exclude it. + +True to include the flag, False to exclude it. + - + Constructor for the class instance. @@ -370,7 +344,6 @@ sets the initial value in the Timestamp property. - Destructor for the class instance. @@ -389,7 +362,6 @@ Destroy calls the inherited method prior to exit. - Increments the lock count for the caching mechanism. @@ -399,7 +371,6 @@ Destroy calls the inherited method prior to exit. - Decrements the lock count for the caching mechanism. @@ -414,7 +385,6 @@ method is called. - Indicates Lock has been called without a corresponding Unlock call. @@ -428,15 +398,12 @@ non-zero value. - - -True when the internal lock count has a positive non-zero value. +True when the internal lock count has a positive non-zero value. - Increments the change counter or updates an item in the state cache. @@ -467,8 +434,6 @@ class instance using the value in AFileName as an argument. - - Name for the file or directory invalidated in the cache, or an empty string @@ -476,7 +441,6 @@ to invalidate all cached items. - Ensures that a cached item has an up-to-date "file exists" flag value. @@ -504,20 +468,15 @@ the local file system. SetFlag is called to update the - - -True if the file exists on the local file system and in the cache. +True if the file exists on the local file system and in the cache. - - Name for the file to examine in the method. - Ensures that a cached item has an up-to-date "directory path exists" flag @@ -548,20 +507,15 @@ the local file system. SetFlag is called to update the - - -True if the directory exists on the local file system and in the cache. +True if the directory exists on the local file system and in the cache. - - Name of the directory to examine in the method. - Ensures that a cached item has an up-to-date "Directory is Writable" flag. @@ -589,21 +543,16 @@ given name. - - -True if the specified directory is writable in the local file system +True if the specified directory is writable in the local file system and in the cache. - - Name of the directory to examine in the method. - Ensures that the "File is Executable" flag is up-to-date for a cache item. @@ -632,18 +581,17 @@ value to the cached item. FileIsExecutable - - -True if the specified file is an executable binary. + +True if the specified file is an executable binary. + - - -Name for the file examined in the method. + +Name for the file examined in the method. + - Ensures that the "File is Readable" flag is up-to-date for a cache item. @@ -651,18 +599,13 @@ Ensures that the "File is Readable" flag is up-to-date for a cache item. - - -True if the specified file is not read-only. +True if the specified file is not read-only. - - Name for the file examined in the method. - Ensures that the "File is Writable" flag is up-to-date for a cache item. @@ -670,22 +613,17 @@ Ensures that the "File is Writable" flag is up-to-date for a cache item. - - -True if the file is writable. +True if the file is writable. - - Name for the file examined in the method. - Ensures that the "File is Text" flag is up-to-date for a cache item. @@ -693,18 +631,17 @@ Ensures that the "File is Text" flag is up-to-date for a cache item. - - -True if the file is a text file (not a binary executable). + +True if the file is a text file (not a binary executable). + - - -Name for the file examined in the method. + +Name for the file examined in the method. + - Ensures that the file age is up-to-date for a cache item. @@ -712,18 +649,15 @@ Ensures that the file age is up-to-date for a cache item.

FileAgeCached differs from the related methods in the class -instance. -It returns a LongInt value instead of a Boolean, and -contains the value from the FileAge routine in the RTL -SysUtils unit. The value represents the last date that the file -was modified, and the integer value does not include any time-related -information -for the modification timestamp. +instance. It returns a LongInt value instead of a +Boolean, and contains the value from the FileAge routine +in the RTL SysUtils unit. The value represents the last date that +the file was modified, and the integer value does not include any time-related +information for the modification timestamp.

FileAgeCached cannot be used for directory names; the value is always --1 -when used for a directory name. +-1 when used for a directory name.

FileAge is not related to the TimeStamp property for the cache. @@ -733,18 +667,50 @@ FileAge is not related to the TimeStamp property for the cache. FileAge - - File age (last modification date) for the file. - - Name for the file examined in the method. - + + +Resolves the specified file name to a physical file on the local file system. + + +

+The implementation is platform-specific. On the Windows platform, the value in +AFileName is used as the return value. On UNIX-like platforms, which +can have symbol links, the file name must be resolved to the physical file on +the local file system. The cache is recursively searched to resolve a file name +which resides on a symbolic link. +

+

+The return value contains the resolve path and file name, or an empty string if +the file name cannot be resolved. When EmptyOnError is enabled, the value in +the AFileName is returned - even when not resolved. +

+ + + + + +Path amd file name for a file name on symbolic links. + + + + +File name resolved in the method. + + + + +True if an unresolved is empty when an error occurs. False if the +value in AFileName is used when an error occurs. + + + Gets (or creates) the cached item with the specified name. @@ -782,23 +748,16 @@ FindFile is used to implement the Check and - - Cached item with the specified name, or Nil. - - Name for the file or directory to locate in the cache. - - -True to create a cache item if it does not already exist. +True to create a cache item if it does not already exist. - Checks the specified cache item to get a specific flag value. @@ -871,33 +830,22 @@ including: - - -True if the flag is has been tested and set for the cache item. +True if the flag is has been tested and set for the cache item. - - File or directory to locate in the cache. - - Flag to examine for the cache item. - - The cache item examined in the method. - - -True if the flag was tested and set for the cache item. +True if the flag was tested and set for the cache item. - Adds the specified handler routine to the class instance. @@ -905,13 +853,10 @@ Adds the specified handler routine to the class instance. - - Handler routine added in the method. - Removes the specified handler routine in the class instance. @@ -919,13 +864,10 @@ Removes the specified handler routine in the class instance. - - Handler routine removed in the method. - Gets the memory size needed for the class instance and its data. @@ -944,13 +886,10 @@ the String values in FileName and PhysicalFilename. TObject.InstanceSize - - Memory size needed to store the class instance and its data. - Timestamp (or revision) value for the cache storage. @@ -961,7 +900,6 @@ Timestamp (or revision) value for the cache storage. - Unit global variable with the class instance for the state caching mechanism. @@ -979,7 +917,6 @@ the variable is Nil (unassigned). - Gets the File Exists flag value for the specified file name. @@ -987,18 +924,13 @@ Gets the File Exists flag value for the specified file name. - - -True if the file exists on the local file system. +True if the file exists on the local file system. - - File name examined in the routine. - Gets the Path Exists flag value for the specified directory path. @@ -1006,18 +938,13 @@ Gets the Path Exists flag value for the specified directory path. - - -True if the path exists on the local file system. +True if the path exists on the local file system. - - Path to the directory examined in the routine. - Gets the Directory is Writable flag value for the specified path. @@ -1025,20 +952,15 @@ Gets the Directory is Writable flag value for the specified path. - - -True if the specified directory allows files or sub-directories to be created. +True if the specified directory allows files or sub-directories to be created. - - Path examined in the routine. - Gets the File is Executable flag value for the specified file name. @@ -1046,22 +968,17 @@ Gets the File is Executable flag value for the specified file name. - - -True if the specified file is an executable (binary) file. +True if the specified file is an executable (binary) file. - - Name for the file examined in the routine. - Gets the File is Readable flag value for the specified file name. @@ -1069,22 +986,17 @@ Gets the File is Readable flag value for the specified file name. - - -True if the specified file is readable. +True if the specified file is readable. - - Name for the file examined in the routine. - Gets the File is Writable flag value for the specified file name. @@ -1092,22 +1004,17 @@ Gets the File is Writable flag value for the specified file name. - - -True if the specified file is writable (not read-only). +True if the specified file is writable (not read-only). - - Name for the file examined in the routine. - Gets the File is Text flag for the specified file name. @@ -1115,22 +1022,17 @@ Gets the File is Text flag for the specified file name. - - -True if the specified file is a text (not a binary executable) file. +True if the specified file is a text (not a binary executable) file. - - Name for the file examined in the routine. - Gets the file age for the specified file or directory. @@ -1138,13 +1040,9 @@ Gets the file age for the specified file or directory. - - File age for the specified file or directory. - - File or directory name examined in the routine. @@ -1193,10 +1091,9 @@ Calling the GetPhysicalFilename routine. File name resolved in the routine. -True to return an empty string if AFilename is not found. +True to return an empty string if AFilename is not found. - Invalidates one or more items in the state cache. @@ -1217,58 +1114,73 @@ empty string (''), all items in the cache are invalidated. - Name for the file or directory invalidated in the cache. - - - - -TODO + +Gets the relative order for the file names in the specified TFileStateCacheItem +entries. + + +

+Used as the sort/compare routine for the TAVLTree instance in TFileStateCache. +

+ + + +CompareFilenames + - - - + +Returns 0 if the UTF-8 file name have the same value. Returns -1 if the file +name in Data1 comes before the file name in Data2. Returns 1 if the file name +in Data1 comes after the file name in Data2. + - - - + +TFileStateCacheItem item with the file name compared in the routine. + - - - + +TFileStateCacheItem item with the file name compared in the routine. + - - + +Compares a value to a file name in a TFileStateCacheItem instance. + - -TODO + + +CompareFilenames + - - - + +Returns 0 if the UTF-8 file name have the same value. Returns -1 if the file +name in Data1 comes before the file name in Data2. Returns 1 if the file name +in Data1 comes after the file name in Data2. + - - - + +Pointer to the string value compared to the file name in the file state cache +entry. + - - - + +Pointer to the TFileStateCacheItem instance with the file name compared in the +routine. + - Integer value used as the invalid timestamp value for the cache mechanism. @@ -1277,7 +1189,6 @@ Integer value used as the invalid timestamp value for the cache mechanism. - Int64 value used as the invalid timestamp value for the cache mechanism. @@ -1286,31 +1197,24 @@ Int64 value used as the invalid timestamp value for the cache mechanism. - Increments the specified Integer timestamp value. - - Timestamp value modified in the routine. - Increments the specified Int64 timestamp value. - - Timestamp value modified in the routine. - Specifies an event handler signalled to get the "file exists" flag for an item @@ -1319,18 +1223,13 @@ in the cache. - - -True if the file exists on the local file system. +True if the file exists on the local file system. - - File name examined in the event handler. - Specifies an event handler signalled to get the file age for an item in the @@ -1339,18 +1238,13 @@ cache. - - File age for the specified file or directory. - - File or directory examined in the handler. - Event handler signalled to get the File Exists flag for the specified file @@ -1360,7 +1254,6 @@ name. - Event handler signalled to get the file age for the specified file name.