Koryn's Units
Koryn Grant, Macintosh Developer



pascalflavouredmac picture

Text File Folders

Author: Koryn Grant
Copyright: 1998 Koryn Grant
Email: koryn@kagi.com
Date: 10 June 1998

Summary

KGTextFilesFolder is an Object Pascal unit that implements an object that looks after a bunch of text files from a single folder. Setting it up is a two-step process, involving giving the object an FSSpec to the folder of text files and then asking the object to read the folder. KGTextFilesFolder requires MyAssertions from Peter Lewis' PNL Libraries, available from http://www.stairways.com/ ; KGLists and KGTextFiles, available from http://www.ukc.ac.uk/IMS/maths/people/K.D.Grant/macdev/ and Pascal Central http://www.pascal-central.com/ ; and MoreFiles, available from http://members.aol.com/JumpLong/ , infomac and the CodeWarrior CDs.

Environment

Although KGTextFilesFolder is provided as a unit, it is still environment-dependent. In particular, I use the Metrowerks scope keywords (public/protected/private) in object declarations.

Conditions of use

You may use KGTextFilesFolder in any project you wish, provided that an acknowledgement is made in your application's AboutBox and ReadMe. A suitable acknowledgement would be

"YourApplication uses KGTextFilesFolder, written by and copyright 1998 Koryn Grant."

Complimentary copies of any freeware, shareware or commercial applications that use KGTextFiles would be appreciated but are not required.

Unmodified copies of "KGTextFilesFolder.p" may be freely distributed provided that they are accompanied by the file "About KGTextFilesFolder". Modified copies may not be distributed without the author's permission.

Disclaimer: KGTextFilesFolder is provided as is, with no warranties about its suitability for any purpose whatsoever.

How to use KGTextFilesFolder

The strategy for using TextFileFolderObjects is as follows

  1. Get yourself a new TextFileFolderObject.
  2. Give it the FSSpec of the folder containing the text files.
  3. Tell it to read the files.
  4. You can now retrieve files (as TextFileObjects, see KGTextFiles for more information about these beasts) by name using GetTextFile or by index using GetNumberOfMembers and GetTextFileNumber.

KGTextFilesFolder interface

{ Constants for errors. }
kTextFileFolderNoError = 0;
kTextFileFolderAddTextFileError = 1;

TextFileFolderObject = object(ListObject)
	{ Private data fields. }
	private FolderSpec : FSSpec;
	
	{ Methods. }
	procedure Initialise; override;
	procedure Finished; override;
	procedure GetTextFile(theName : ConstStr31Param; var theTextFileObject : TextFileObject);
	procedure GetTextFileNumber(theNumber : SInt16; var theTextFileObject : TextFileObject);
	procedure SetFolderSpec(theFSSpec : FSSpec);
	procedure ReadTextFiles;
	procedure AddTextFile(theFSSpec : FSSpec);
	end;
		{ of TextFileFolderObject }

KGTextFilesFolder methods

procedure Initialise; override;

Initialises the internal data structures.

procedure Finished;

Disposes of memory used by the TextFileFolderObject and the object itself. After calling this method all references to the TextFileObject are invalid.

procedure GetTextFile(theName : ConstStr31Param; var theTextFileObject : TextFileObject);

This method returns the TextFileObject in the folder with the name theName. If no such file exists, theTextFileObject is nil.

procedure GetTextFileNumber(theNumber : SInt16; var theTextFileObject : TextFileObject);

This method returns the requested indexed TextFileObject. Note that the method for retrieving the number of text files belongs to the superclass ListObject, and is documented in the KGLists documentation.

procedure SetFolderSpec(theFSSpec : FSSpec);

This method sets the FSSpec for the folder that the TextFileFolderObject is to read its files from.

procedure ReadTextFiles;

This method tells the TextFileFolderObject to read in all the text files it can find in the given folder. The folder must be set with SetFolderSpec before this method is called.

procedure AddTextFile(theFSSpec : FSSpec);

This method is used internally by the TextFileFolderObject to add a file to its list of files. Under normal circumstances there is no need to call this method directly.

Example use (from SlashMUD)

This is a method taken straight from SlashMUD. SlashMUD relies on several folders of text files, one of which defines the areas (rooms) in the MUD. This code gets an FSSpec for the area files folder (it's called "SlashMUD Areas") and reads in all the files in that folder.

gAreaFilesManager is a global variable of type TextFileFolderObject.

kAreaFilesFolderName is a constant string, "SlashMUD Areas".

procedure GameObject.LoadAreaFiles;
	var
	theErr : OSErr;
	
	begin
	{ Find SlashMUD Areas folder at the same level as the SlashMUDServer application. }
	theErr := FSMakeFSSpec(SlashMUDFSSpec.vRefNum, SlashMUDFSSpec.parID, kAreaFilesFolderName, AreaFilesFolderFSSpec);
	
	gAreaFilesManager.SetFolderSpec(AreaFilesFolderFSSpec);
	gAreaFilesManager.ReadTextFiles;
	end;
		{ of procedure GameObject.LoadAreaFiles }

Credits

Download KGTextFilesFolder



Copyright ©1998 Koryn Grant.