SortTables Design

Created: 7-28-95
Last revision: 1-5-96

This document is an experimental attempt at presenting design documentation via HTML. It uses tables, and is essentially unreadable without a browser supporting them.

Overall Design

This section has pictures showing the design structure as a Booch diagram.

Command Structure

The Command Inheritance Structure

This program uses the Command(233) pattern as described in Design Patterns: Elements of Reusable Object-Oriented Software, Gamma et al., 1995. This pattern turns the command into an object that knows how to be executed for a given state. Each keystroke event in the main loop is turned into an appropriate command, which is executed in turn. Further, execution of the command doesn't in general depend on which type of ResultSet or Records are being used, it just depends on their abstract interface.

Record Structure

The Record Inheritance Structure

This program supports two types of records. TabRecords correspond to files with one record per line, fields separated by tabs. This is mostly used for testing, since each access to a field requires parsing the line. OffsetRecords is more complicated: there is a static file with records and fields in any order (though usually just a "TabRecords" style file), and an index file in this format:

    for each record
        for each field
            offset and length of this record/field 
            in 'original' file

The offset and length are stored in binary format.

ResultSet Structure

The ResultSet Inheritance Structure

The TableResult is the simple version. It keeps the list in memory, and sorts it on demand. The ListResult is the "custom" version. It uses a special algorithm which keeps track of buckets in memory (buckets are responsible for information about sets of records).

ResultIterator Structure

The ResultIterator Inheritance Structure

The TableIterator works with a TableResult object; the ListIterator works with a ListResult object.

Module Designs

ResultSet

**ResultSet - the set of items**
Category	Result	Name	Arguments	R/O
Standard		ResultSet	const char filename, Records record_set
		~ResultSet
		dump		x
Size	int	countEst		x
Size	bool	countIsEstimated		x
Columns	int	count_columns		x
	int	current_column		x
		reset_column
		next_column
		prev_column
Restriction		match	const char *pattern
		deleteBefore	ResultIterator *iter
		deleteAfter	ResultIterator *iter
Limits	const char *	min	int column	x
Limits	const char *	max	int column	x
Iteration	ResultIterator *	MakeIterator

ResultIterator

**ResultIterator - Lets you walk through ResultSet**
Category	Result	Name	Arguments	R/O	Notes
Standard		~ResultSet
Iteration		First
	bool	IsFirst		x
		Last
	bool	IsLast		x
		Next
		Prev
Current Item	RecordID	CurrentItem		x
Current Item	int:0..100	PositionEstPercent		x
Movement	bool	SkipTo	RecordID
	bool	SkipTo	const char *pattern
	bool	SkipTo	double percent		NYI

Records

**Records - manages record contents**
Category	Result	Name	Arguments	R/O
Standard		~Records
Access	const char *	field	RecordID, FieldID	x
	RecordID	count_records		x
	FieldID	count_fields		x

Command

**Command - Performs user actions**
Category	Name	Arguments	Notes
Standard	Command		Protected - only subclasses can create Commands
Standard	~Command
Command Execution	doit	State *
Command Execution	undo	State *	No longer used

State

**State - global state for commands**
Category	Result	Name	Notes
Data	char *	global_filename	The file being read
	char *	global_separator	Separator string
	ResultSet *	RSset	The set of items.
	ResultIterator *	RSiter	Associated iterator
	Records *	record_set	Actual records
Columns	int	col	The current column
Columns	int	maxcols	Maximum # of columns
Search	char *	searchString	The search string
Search	int	searchSize	Size of searchString
Display Management	Screen *	screen	The display
	bool	needsRedisplay, needsStatic, needsProgress, needsSearch, needsTitles, needsMinMax, needsDivider, needsBody	Bits telling which parts of screen are dirty
	size_t	formats_length[]	Length of format - longer strings must be printed using formats_long[]
	char *	formats_short[]	Format for fields that fit in defined space
	char *	formats_long[]	Formats for fields that don't fit in defined space
	char *	screen_title[]	Column titles for browsing screen
	char *	field_title[]	Row columns for one-item view window
Logging	Logger *	log	Logging facility

Display

The display module should be an object, created to know about its screen, but is still C code for historical reasons.

**Display - updates display on state change**
Category	Name	Arguments	Notes
Standard	display_init
Standard	display_fin
Display	display_message	State , char msg	Display message in the transient area
	display_header_fixed	Screen , char filename, char *title[], size_t formats[], int columns	The fixed screen information
	display_update	Screen , State	Normal update

Logger

This module provides for logging different types of events. It's mostly used at high levels to give a time-stamped log of keystrokes, help events, and other significant events. The type LogEvent is an enum describing the high-level event types.

**Logger - log events**
Category	Name	Arguments
Standard	Logger	const char *filename
Standard	~Logger
Logging	log	LogEvent
	log	LogEvent, int
	log	LogEvent, const char *
	log	LogEvent, time_t