Files

The Files portion of the Guildhall architecture deals with host files, memory files, resource attachments, and version lists. It also declares the very important TArchiveFile class which underlies the Guildhall File System as well as some helper classes.

The abstract class AHostFile adds functionality to the basic AStream protocol to allow Guildhall to work with host files. The implementation details are mostly in the Hardware Abstraction Layer but in summary it adds methods to open, open read-only, create, and close host files. It does not override the reading and writing methods of AStream because its most important subclasses, THostFile and THostData, handle those functions very differently. THostFile creates an applet friendly substructure within the host file, accommodating version and resource forks within the flat (single fork) host file. THostData maps onto the raw host file, allowing its clients to work with existing host file formats (for example, aiff data as TAIFFFile) and to implement new ones (most importantly, the Guildhall archive file format as TArchiveFile).

Memory Streams

The important TMemoryStream class is defined in this section. Constructed with a pointer to memory and a size, it can read and write data from that memory using the standard streaming operators. When constructed with just a size it allocates the memory it needs and initializes an empty stream. After writing, it can be streamed to the host file system (in a THostFile) or streamed to the Guildhall file system (in a TArchiveObject). But the problem with creating a stream for writing is that the size needed for the stream isn't known at the start of the operation. Initially I tried putting a "GetStreamedSize" method in every streamable class, but that was a pain to maintain. I could have made the memory dynamically resize, but that could end up doing a large amount of unneeded copying. I thought about chaining blocks of memory together, but that seemed too fragile. And then it occurred to me that I could create an AStream subclass, TSizingStream, that ignores all streaming calls except that it keeps track of the size of what's streamed. So grab whatever I need the size of, stream it in the normal way, and recover the size afterwards, no extra coding required. It works great!

The data contained in a TMemoryStream has no predefined structure, and that made it a good implementation vehicle for the TResource class. But since TMemoryStream supports resources, so does TResource. It is thus possible to have resources in resources in resources, etc, to whatever depth a developer wishes. In practice I have only ever used one level, but the capability to go deeper is there.

Text Files

Plain text files have a huge amount of utility, especially during bring-up of new features. They're also the storage medium for all of the textual content of the Tome applet, used to create this website. Manipulating text files, both on the host system and on a Guildhall archive, has some special classes set up to make that process easy. On the Guildhall side the Editor applet's TTxData class handles that assignment. For host text files, the THostText class does the work. Both classes subclass from ATextFile so once access is set up the client of the text file doesn't care where the text is coming from.

Pathnames

Finally, a word about pathnames. Regardless of the host OS, Guildhall uses Posix file names to specify host files. Should any translation be needed, it can be done in the host specific implementation of the Hardware Abstraction Layer. Guildhall uses a similar convention to specify objects stored on an archive in the Guildhall File System, with one important difference. Whereas a file on an external disk on macOS would be referenced starting from the "/Volumes" directory, files on a Guildhall archive follow a convention used by the Aegis file system from the old Apollo Computer company, namely that volume names start with "//" followed by the archive name. Pathnames for files on the user's home archive can just start with a single "/".

Guildhall currently uses two different classes to manage host file system paths and local archive paths, the former being THostname and the latter being TPathname. These are similar classes, and after being constructed they provide Getter functions that can return various elements of the path, for example enclosing folder or display name or extension or the full pathname. But an idea is growing on me to combine the two pathnames into a single convention. I'm considering referencing volumes on the host system with a double colon, "::", so what would be say "/Volumes/ExtDisk" on macOS would be referenced as "::ExtDisk" within Guildhall. THostname would be subsumed by TPathname and a certain amount of code would disappear. There may be pitfalls to this approach, but that's where I'm considering heading. It wasn't something I wanted to do when Guildhall was being published. As much as possible I tried to make sure I couldn't step on any user files by accident. But with publishing over, I have more options. So I think I'll give it a try and see how it works.

Abstract Classes

• AHostFile (AStream)
• ATextFile

Mix-in Classes

• MAttachment

Constructible Classes

• TTypeIterator (subclasses from MAttachment)
• TVersionList
• TResourceList
• TResource (subclasses from AStream, MAttachment)
• TResourceIterator (subclasses from MAttachment)
• TMemoryStream (subclasses from AStream)
• TSizingStream (subclasses from AStream)
• THostname
• THostFile (subclasses from AHostFile)
• TArchiveFile (subclasses from THostFile)
• THostData (subclasses from AHostFile)
• THostText (subclasses from ATextFile, THostData)