I am the in-memory representation of a Celeste mail database. A mail database named "current" consists of three files:

current.messages -- an append-only file containing the full content of all messages
current.index -- an index of all messages in the messages file that maps unique
message ID's to index entries containing some header information
and the offset of the full message in the .messages file
current.categories -- maps category names to collections of message ID's

Each open mail database has a MailDB object that manages these three files. Operations such as fetching a message given its unique ID and finding out which messages are in which category are supported by the MailDB object. It also supports incorporating new messages (reading mail), message editing and deletions, and message file compaction and recovery.

canRenumberMsgIDs is used only during compacting the message file. It controls whether renumbering can happen for messages which have duplicate (and therefore not unique) messageIDs. It is an instance variable so that it can control behaviour in subsequent compactions. Please do not use it for other behaviour.

lastIssuedMsgID contains the most recently issued message ID. It is mostly private to nextUnusedID, though it is also cleared in the compact routine. Otherwise, please do not read or write it.

	copying
	veryDeepCopyWith:

	fetch-import-export
	fetchMailFromPOP:userName:password:doFormatting:deleteFromServer: fetchMessageCount:fromPOPConnection:doFormatting: fetchNewsFrom:doFormatting:deleteInbox: importMailFrom:intoCategory: mergeMessages:from: removeMessageCount:fromPOPConnection:

	housekeeping
	appendMessages:messageFile:indexFile: cleanUpCategories compact copyUndeletedTo:indexFile: fileDuplicatesIn: findDuplicates nextUnusedID

	initialize-release
	close openOn:

	messages
	addNewMessage: deleteAll: getMessage: getTOCentry: getTOCstring: getTOCstringAsColumns: getText: newText:for:

	open-create-save
	createDB dbStatus openDB recoverDB rootFilename saveDB

	printing
	printOn:

	testing
	selfTest

	private
	dbStatusFor:

	shut down
	shutDown

	utilities
	readIntegerLineFrom: readStringLineFrom: skipRestOfLine:

	categories	top
	addCategory: Create a category with the given name if one doesn't already exist.
	allCategories Answer a list of categories sorted in alphabetical order, including the special categories.
	categoriesThatInclude: Answer a collection of names for real categories that include the message with the given ID. Pseudo-categories (such as '.unclassified.') are not considered real categories.
	file:inCategory: File the message with the given ID in the given category.
	fileAll:inCategory: File all the messages with ID's in the given list in the given category.
	messagesIn: Answer a collection of message ID's for the messages in the given category, sorted in ascending time order. If the category does not exist, answer an empty collection. The pseudo-categories '.all.' and '.unclassified.' are computed dynamically, which may take a little time.
	remove:fromCategory: Remove the message with the given ID from the given category.
	removeAll:fromCategory: Remove all the messages with ID's in the given list from the given category.
	removeCategory: Remove the category with the given name. This does nothing if the category does not exist or if it is a pseudo-category.
	removeFromAllCategories: Remove the message with the given ID from all categories. The message will appear in 'unclassified'.
	renameCategory:to: Rename the given category. This does nothing if the category does not exist or if it is a special category ('.all.' or '.unclassified.').
	sortedKeysForMessages: use a heuristic to choose method of obtaining sorted message list

	copying	top
	veryDeepCopyWith: don't copy MailDB's -- they refer to external state in files, and the user almost certainly does not intend for a completely independent MailDB to be created

	fetch-import-export	top
	fetchMailFromPOP:userName:password:doFormatting:deleteFromServer: Download mail from the given POP3 mail server and append it this mail database. Answer the number of messages fetched. If doFormatting is true, messages will be formatted as they are received. If deleteFromServer is true, then messages will be removed from the POP3 server after being successfully retrieved. (Note: If there is a failure while fetching mail, all messages will be left on the server.)
	fetchMessageCount:fromPOPConnection:doFormatting: Download the given number of messages from the given open POP3 connection. If doFormatting is true, messages will be formatted as they are received.
	fetchNewsFrom:doFormatting:deleteInbox: Append the messages from the given news inbox file to this mail database. Answer the number of messages fetched.
	importMailFrom:intoCategory: Append the messages from the given mail file to this mail database, and store them in the given category. Answer the number of messages imported.
	mergeMessages:from: Merge the given collection of messages from the source database into the receiver. When a message being added has the same message ID as an existing message, check to see if the two message texts are identical. If so, do not store the duplicate message. If the texts are different, make a new ID for the message being added. This operation will also copy the category information from the sourceDB, creating new catetories if necessary.
	removeMessageCount:fromPOPConnection: Remove messages 1 through msgCount from the given POP3 server.

	housekeeping	top
	appendMessages:messageFile:indexFile: Append the given collection of messages to the message file. msgBuffer is a collection of (message ID, message text) pairs.
	cleanUpCategories Prune the dead wood out of all categories.
	compact Compact the message file and rebuild the index file. Answer an array containing with the number of messages and the number of bytes recovered.
	copyUndeletedTo:indexFile: Copy all the undeleted messages in my current message file into the new message file, recording their locations in the new index file. Also eliminates duplicate messageIDs. Answer an array containing with the number of messages and the number of bytes recovered, as well as the number of messages still remaining.
	fileDuplicatesIn: MailDB someInstance fileDuplicatesIn: '.duplicates.'
	findDuplicates MailDB someInstance findDuplicates
	nextUnusedID Answer the next unused message identifier number.

	initialize-release	top
	close Close up the database in preparation for closing celeste
	openOn: Open a mail database with the given root file name.

	messages	top
	addNewMessage: Add the given message to the database, and answer its message id.
	deleteAll: Delete all the messages with ID's in the given list from the message file. This is permanent!
	getMessage: Answer the MailMessage with the given ID.
	getTOCentry: Answer the table-of-contents entry for the message with the given ID.
	getTOCstring: Answer the table-of-contents string for the message with the given ID.
	getTOCstringAsColumns:
	getText: Answer the text for the message with the given ID.
	newText:for: Replace the text for the message with the given ID.

	open-create-save	top
	createDB Create a new mail database.
	dbStatus
	openDB Open an existing mail database.
	recoverDB Open a mail database with the given root file name.
	rootFilename Answer my root filename.
	saveDB Write all database files to disk.

	printing	top
	printOn: Append to the argument, aStream, a sequence of characters that identifies the receiver.

	testing	top
	selfTest This is purely for testing purposes. It checks out various things to make sure that everything is well formed and looks as it should. This can be a bit slow, but is very useful because it tests much of Celeste using every message in the mail database

	instance creation	top
	isADBNamed: return whether there is a MailDB on disk with the specified name
	openOn: Open or create a mail database with the given root filename. If an instance of me exists with the given root filename, return a reference to that instance rather than creating a new one. This allows multiple MailReaders to be open on the same database without synchronization problems.

	private	top
	dbStatusFor: See if the named databes exists. Since the database has several components, the answer is one of: #exists all files exist, and were created in the right order #partialDatabase only some of the files exist #doesNotExist none of the files exist

	shut down	top
	shutDown snapshot all mail databases to disk

	utilities	top
	readIntegerLineFrom: Read a positive integer from the given stream. Answer zero if there are no digits. Consume the stream through the next carriage return.
	readStringLineFrom: Read and answer the next line from the given stream. Consume the carriage return but do not append it to the string.
	skipRestOfLine: Consume characters from the given stream through the next carriage return.