tbFileSysTools Package

Author: GCuser99. On GitHub: GCuser99/tbFileSysTools, in the folder Package.

The tbFileSysTools contributed package, listed in the Available Packages dialog as File System Tools - Modern Replacement for FSO, reads and changes files, folders and drives, as the FileSystemObject of the Scripting Runtime does, and is written in twinBASIC. It reads and writes text files in any Windows code page, with detection of the encoding and handling of byte-order marks (BOMs), detects and converts line endings, streams files of any size, and works with paths longer than 260 characters.

It has two ways in. The FileSystemTools module holds the code, as procedures that a project calls by name, with no object to create. The FileSystemObject class has the same procedures as members of an object, for code written for the Scripting Runtime. The objects that both return, File, Folder, Drive and TextStream, and the collections Files, Folders and Drives, have the members of the Scripting Runtime’s objects of the same names, and some more.

Dim work As String, path As String
work = BuildPath(Environ$("TEMP"), GetTempName("fst", ""))
CreateFolder work
path = BuildPath(work, "notes.txt")

' Write a string as UTF-8 with a byte-order mark, then ask what the file holds.
StringToTextFile "caf" & ChrW$(233) & vbCrLf & "ok", path, encUtf8Bom
Debug.Print GetFileEncoding(path) = encUtf8Bom    ' True
Debug.Print GetFileLineEnding(path) = nlWindows   ' True
Debug.Print Len(TextFileToString(path))           ' 8

' Read it line by line; the encoding is found from the BOM.
Dim ts As TextStream
Set ts = OpenTextFile(path)
Do Until ts.AtEndOfStream
    Debug.Print Len(ts.ReadLine)
Loop
ts.Close
' Output:
' True
' True
' 8
' 4
' 2

DeleteFolder work

Note

This section documents version 1.1.1.0, the version on the package server, published under the MIT licence. The GitHub repository has moved on: its README describes version 1.8.0.0, and its change log lists changes from 1.2.0.0 on. Some members that the README names, such as FindInTextFiles, FileContainsText and IsFileLocked, do not exist in 1.1.1.0. The change log also records that later versions removed the useLongPathPrefix argument of GetAbsolutePathName and the skipIfUnchanged argument of NormalizeTextFile, which this version has, and that they changed some of the behaviour described on these pages.

The public types of the package are the module and the eight classes on these pages, and the enumerations that the module declares. Three private modules, FSTShared (shared file code and the error mapping), TextCodec (encoding, decoding and detection) and WinAPI (Windows declarations), are not part of the interface and are not described.

Differences from the Scripting Runtime

A call that works with the Scripting Runtime’s FileSystemObject keeps its name here. These are the differences.

Added members.

Whole files: StringToTextFile, TextFileToString, ArrayToTextFile, TextFileToArray, ReadStream, WriteStream, NormalizeTextFile and MergeTextFiles.
Detection: GetFileEncoding and GetFileLineEnding.
Paths and directories: CleanFileName, GetRelativePath, GetFilePaths, GetFileType, GetCurrentDir, SetCurrentDir and Rename.
On File: Encoding, ExtensionName, HasAttribute, LineEnding, Normalize, Refresh, Rename, SetAttribute, ToStream, ToString and Version. On Folder: HasAttribute, Refresh, Rename and SetAttribute. On Drive: SerialNumberHex and UnsignedSerialNumber. On TextStream: Encoding, Flush and IsStreaming.
Files, Folders and Drives return an item by position as well as by name.
Enumerations for the encodings, line endings and 25 special folders.

Members with more arguments. CreateFolder can create the folders above the new one. DeleteFile and DeleteFolder can ignore a missing target. GetAbsolutePathName takes a base directory. GetTempName takes a prefix, an extension and a folder to check.

Missing members. One: the Add method of the Folders collection, which creates a folder. CreateFolder does that. Every other member of the Scripting Runtime’s FileSystemObject, File, Folder, Drive and TextStream is here, and so are Count, Item and the enumerator of the three collections. Drives of the class FileSystemObject is a function, called with or without parentheses.

Arguments that mean something else. The Scripting Runtime selects the encoding of a text file with a Boolean (Unicode, in CreateTextFile) or a Tristate (Format, in OpenTextFile and OpenAsTextStream). Here the argument is a TextEncoding. Code that passes True or TristateTrue, which is -1, gets encAutoDetect, and for writing that is UTF-8, not UTF-16. The defaults also differ: a text file is written in UTF-8 without a BOM, where the Scripting Runtime writes ANSI, and a file opened for reading has its encoding detected, where the Scripting Runtime reads ANSI.

Results that differ.

GetSpecialFolder returns the path as a String, where the Scripting Runtime returns a Folder. It accepts 25 folders, and not only the Windows, System and Temporary folders.
FileAttribute has no Volume (8) and no Alias (1024). The label of a volume is Drive.VolumeName, and an alias is faReparsePoint. File and Folder add SetAttribute and HasAttribute, which change and test one attribute.
Folder.Size does not enter directory junctions and symbolic links. The Scripting Runtime does, and counts the target of a link twice when it is in the same tree: 2,500 bytes there for a folder that holds 1,500.
BuildPath and GetParentFolderName turn / into \. BuildPath("C:\a", "b/c") returns C:\a\b\c and the Scripting Runtime C:\a\b/c; GetParentFolderName("C:/a/b.txt") returns C:\a and the Scripting Runtime C:/a.
GetAbsolutePathName raises error 52 for an empty string, where the Scripting Runtime returns the current directory.
GetDrive accepts a full path and reduces it to its drive: GetDrive("C:\Windows") is C:. The Scripting Runtime raises error 5.
CopyFile, CopyFolder, MoveFile and MoveFolder put the source inside an existing destination folder, whether or not the destination ends in a backslash. The Scripting Runtime does so only with a backslash. Without one it raises error 70 for CopyFile, 58 for MoveFile and MoveFolder, and CopyFolder copies the contents of the source straight into the folder.
MoveFile moves a folder when source names one. The Scripting Runtime raises error 53.
DeleteFolder of a folder that holds a read-only file raises error 75 without force; the Scripting Runtime raises 70.
GetFileVersion returns an empty string for a file that does not exist. The Scripting Runtime raises an error.
At the end of a stream, ReadAll returns an empty string and Skip does nothing, where the Scripting Runtime raises error 62. A closed stream raises 52 here and 91 there.
Files.Item, Folders.Item and Drives.Item take a position as well as a name. A name that is not in the collection raises error 5; the Scripting Runtime raises 53, 76 and 68 for the three. Drives("C:") raises error 5, and the Scripting Runtime accepts it.
GetTempName returns eight random letters and digits and .tmp. The Scripting Runtime returns rad and five hexadecimal digits.
A path longer than 260 characters works in most procedures. The Scripting Runtime does not accept it: FileExists and FolderExists return False for it, GetFile raises error 53 and OpenTextFile raises 76.
StringToTextFile, ArrayToTextFile and WriteStream replace a read-only file without an error. CreateTextFile raises error 70 for it, as the Scripting Runtime’s does.

The same. For these failures the two raise the same error numbers: a missing file (53) or folder (76) from GetFile, GetFolder, CopyFile, DeleteFile, DeleteFolder and OpenTextFile; an existing folder or destination (58) from CreateFolder, CopyFile, MoveFile and CreateTextFile; a missing parent folder (76) from CreateFolder; a drive that does not exist (68) from GetDrive; a read-only destination or file (70) from CopyFile, DeleteFile and CreateTextFile; an unreadable folder (70) from Files, SubFolders and Size; the wrong direction of a stream (54) and a read at the end (62) from TextStream. Both enter a junction or symbolic link when they delete a folder, and both match a pattern against the 8.3 name of a file too.

Using the package with the Scripting Runtime

The package declares types that have the same names as those of the Scripting Runtime library: FileSystemObject, File, Folder, Drive, Files, Folders, Drives, TextStream, and the enumerations FileAttribute, IOMode, SpecialFolderConst, StandardStreamTypes and DriveTypeConst with their members, such as ForReading, Normal and Fixed. In a project that references both libraries, a bare name is found in the library that is listed first among the references, and no error is reported for the other. With the package first, Dim fso As New FileSystemObject creates the package’s class, and Dim f As File is the package’s type. With the Scripting Runtime first, they are the Scripting Runtime’s: f.Encoding then fails to compile (TB5027, Unrecognized member ‘Encoding’ on type ‘IFile’), and fso.BuildPath("C:\a", "b/c") returns C:\a\b/c. The enumeration members (ForReading, Normal, Fixed) compile in either order, and their values are the same in both libraries.

Write the name of the library before the type to be sure which one is meant. Both forms compile in either order:

Dim fso As New tbFileSysTools.FileSystemObject
Dim f As tbFileSysTools.File
Set f = fso.GetFile(fso.BuildPath(fso.GetSpecialFolder(sfSystemFolder), "kernel32.dll"))
Debug.Print f.Size

The other ways out are to remove the reference to the Scripting Runtime, or to list tbFileSysTools above it in the References dialog. The procedures of the module (FileExists, GetFile, CopyFile and the rest) do not collide with anything in the Scripting Runtime, which has no module-level procedures.

Errors

The procedures raise the error numbers that VB6 uses for the same failures. Err.Source names the operation, such as CopyFile, and Err.Description names the path. The errors of OpenTextFile, CreateTextFile and the other procedures that open a stream have an empty Err.Source and only the standard text of their number, without the path. Each entry says which numbers it raises.

5 – Invalid procedure call or argument: a wildcard in a destination, a folder copied into itself, a text procedure given a binary file, a value that is not a member of an enumeration, a name that is not in a collection, and the file not found! of ReadStream.
7 – Out of memory: a whole file that is too large for one array or String (more than 2 GB).
9 – Subscript out of range: a position outside a collection.
52 – Bad file name or number: a name with a character that Windows does not allow, and a closed TextStream.
53 – File not found.
54 – Bad file mode: a read on a stream open for writing, or the reverse.
58 – File already exists. The text says File also when a folder is in the way.
62 – Input past end of file.
68 – Device unavailable: a drive letter that is not in use.
70 – Permission denied: access is refused, or the file is in use.
71 – Disk not ready: a drive with no media.
75 – Path/File access error: any other Windows failure. The text ends with the Windows code, such as 145 for a folder that is not empty and 206 for a path that is too long.
76 – Path not found.

Windows reports a failure with its own code, and the package maps it to one of those numbers: file not found (2) to 53, path not found (3) and bad directory name (267) to 76, file exists (80 and 183) to 58, access denied and the sharing violations (5, 32 and 33) to 70, and invalid name (123) to 52.

Note

Version 1.1.1.0 raises some errors that the Scripting Runtime does not raise, or other numbers. The sample shows the first three.

A file name with a character above U+7FFF, such as the Chinese character U+8A9E, the Hangul letter U+AC00 or an emoji, raises error 52 in StringToTextFile, ArrayToTextFile, CreateTextFile, OpenTextFile with create True, the output file of MergeTextFiles and Folder.CreateTextFile. The Scripting Runtime accepts the names, and so do WriteStream and CreateFolder.
A missing file raises error 5 and not 53 in TextFileToString, TextFileToArray, GetFileEncoding, GetFileLineEnding, NormalizeTextFile, ReadStream and the first file of MergeTextFiles. OpenTextFile and GetFile raise 53.
A folder that does not exist raises the unspecified error -2147467259, not 76, in StringToTextFile, ArrayToTextFile and WriteStream. CreateTextFile and OpenTextFile raise 76.
Folder.Files, SubFolders and Size raise error 76 for a folder whose path has 258 characters or more.

Dim work As String, s As String, ts As TextStream
work = BuildPath(Environ$("TEMP"), GetTempName("fst", ""))
CreateFolder work

On Error Resume Next
StringToTextFile "x", BuildPath(work, ChrW$(&H8A9E&) & ".txt")
Debug.Print Err.Number                              ' 52
Err.Clear
StringToTextFile "x", BuildPath(work, ChrW$(&H65E5&) & ".txt")
Debug.Print Err.Number                              ' 0
s = TextFileToString(BuildPath(work, "missing.txt"))
Debug.Print Err.Number                              ' 5
Err.Clear
Set ts = OpenTextFile(BuildPath(work, "missing.txt"))
Debug.Print Err.Number                              ' 53
Err.Clear
StringToTextFile "x", BuildPath(work, "nofolder\x.txt")
Debug.Print Err.Number                              ' -2147467259
Err.Clear
On Error GoTo 0

DeleteFolder work

Test with FileExists first when the number of a missing-file error matters.

Classes and modules

FileSystemTools – the module that holds the procedures, and the enumerations
- ArrayToTextFile – writes the elements of a String array to a text file, one per line
- BuildPath – joins a folder path and a name
- CleanFileName – removes from a file name the characters that Windows does not allow
- CopyFile – copies one or more files
- CopyFolder – copies a folder and everything in it
- CreateFolder – creates a folder
- CreateTextFile – creates a text file and returns a TextStream open for writing
- DeleteFile – deletes one or more files
- DeleteFolder – deletes a folder and everything in it
- DriveExists – returns whether a drive exists
- FileExists – returns whether a file exists
- FolderExists – returns whether a folder exists
- GetAbsolutePathName – returns the full path for a path specification
- GetBaseName – returns the last component of a path without its extension
- GetCurrentDir – returns the current directory
- GetDrive – returns a Drive object
- GetDriveName – returns the drive part of a path
- GetDrives – returns a Drives collection of every drive
- GetExtensionName – returns the extension of the last component of a path
- GetFile – returns a File object
- GetFileEncoding – returns the text encoding of a file
- GetFileLineEnding – returns the line-ending style of a text file
- GetFileName – returns the last component of a path
- GetFilePaths – returns the paths of the files in a folder
- GetFileType – returns the type description of a file or folder
- GetFileVersion – returns the version of an executable file
- GetFolder – returns a Folder object
- GetParentFolderName – returns the path of the folder that holds the last component of a path
- GetRelativePath – returns the path that leads from one path to another
- GetSpecialFolder – returns the path of a well-known Windows folder
- GetStandardStream – returns a TextStream for standard input, output or error
- GetTempName – returns a random name for a temporary file or folder
- MergeTextFiles – joins two text files into one
- MoveFile – moves one or more files
- MoveFolder – moves one or more folders
- NormalizeTextFile – rewrites a text file with a chosen encoding and line ending
- OpenTextFile – opens a text file and returns a TextStream
- ReadStream – reads a file into a byte array
- Rename – renames a file or folder in place
- SetCurrentDir – sets the current directory
- StringToTextFile – writes a string to a text file
- TextFileToArray – reads a text file into an array of lines
- TextFileToString – reads a text file into a string
- WriteStream – writes a byte array to a file
- TextEncoding, NewlineType, IOMode, SpecialFolderConst, FileAttribute, FileVersionSource and StandardStreamTypes – the enumerations
FileSystemObject – a class with the procedures of the module as members, for code written for the Scripting Runtime
Drive – a disk drive or a network share
- AvailableSpace – returns the free bytes that the current user can use
- DriveLetter – returns the letter of the drive
- DriveType – returns the type of the drive
- FileSystem – returns the name of the file system
- FreeSpace – returns the free bytes on the volume
- IsReady – returns whether the drive can be queried
- Path – returns the path of the drive (default member)
- RootFolder – returns the root folder of the drive
- SerialNumber – returns the serial number as a signed Long
- SerialNumberHex – returns the serial number in the form that Explorer shows
- ShareName – returns the network path of the drive
- TotalSize – returns the size of the volume
- UnsignedSerialNumber – returns the serial number as an unsigned number
- VolumeName – returns or sets the label of the volume
Drives – the collection of the drives
File – a file
- Attributes, DateCreated, DateLastAccessed, DateLastModified, Drive, Encoding, ExtensionName, HasAttribute, LineEnding, Name, ParentFolder, Path, ShortName, ShortPath, Size, Type, Version – the properties
- Copy, Delete, Move, Normalize, OpenAsTextStream, Refresh, Rename, SetAttribute, ToStream, ToString – the methods
Files – the collection of the files of a folder
Folder – a folder
- Attributes, DateCreated, DateLastAccessed, DateLastModified, Drive, Files, HasAttribute, IsRootFolder, Name, ParentFolder, Path, ShortName, ShortPath, Size, SubFolders, Type – the properties
- Copy, CreateTextFile, Delete, Move, Refresh, Rename, SetAttribute – the methods
Folders – the collection of the folders of a folder
TextStream – reads or writes a text file a piece at a time
- AtEndOfLine, AtEndOfStream, Column, Encoding, IsStreaming, Line – the properties
- Close, Flush, Read, ReadAll, ReadLine, Skip, SkipLine, Write, WriteBlankLines, WriteLine – the methods

tbFileSysTools Package

Differences from the Scripting Runtime

Using the package with the Scripting Runtime

Errors

Classes and modules

See Also