xref: /src/external/bsd/nvi/docs/internals/structures

#	@(#)structures	5.4 (Berkeley) 10/4/95

There are three major data structures in this package, plus a single data
structure per screen type.  The first is a single global structure (GS)
which contains information common to all files and screens.  It hold
global things like the input key queues, and functions as a single place
to hang things.  For example, interrupt routines have to be able to find
screen structures, and they can only do this if they have a starting
point.  The number of globals in nvi is dependent on the screen type, but
every screen type will have at least one global, __global_list, which
references the GS structure.

The GS structure contains linked lists of screen (SCR) structures.
Each SCR structure normally references a file (EXF) structure.

The GS structure has a set of functions which update the screen and/or
return information about the screen from the underlying screen package.
The GS structure never goes away.  The SCR structure persists over
instances of screens, and the EXF structure persists over references to
files.

File names have different properties than files themselves, so the name
information for a file is held in an FREF structure which is chained from
the SCR structure.

In general, functions are always passed an SCR structure, which usually
references an underlying EXF structure.  The SCR structure is necessary
for any routine that wishes to talk to the screen, the EXF structure is
necessary for any routine that wants to modify the file.  The relationship
between an SCR structure and its underlying EXF structure is not fixed,
and various ex commands will substitute a new EXF in place of the current
one, and there's no way to detect this.

The naming of the structures is consistent across the program.  (Macros
even depend on it, so don't try and change it!)  The global structure is
"gp", the screen structure is "sp", and the file structure is "ep".

A few other data structures:

TEXT	In nvi/cut.h.  This structure describes a portion of a line,
	and is used by the input routines and as the "line" part of a
	cut buffer.

CB	In nvi/cut.h.	A cut buffer.  A cut buffer is a place to
	hang a list of TEXT structures.

CL	The curses screen private data structure.  Everything to
	do standalone curses screens.

MARK	In nvi/mark.h.  A cursor position, consisting of a line number
	and a column number.

MSG	In nvi/msg.h.  A chain of messages for the user.

SEQ	In nvi/seq.h.  An abbreviation or a map entry.

TK	The Tcl/Tk screen private data structure.  Everything to
	do standalone Tcl/Tk screens.

EXCMD   In nvi/ex/ex.h.  The structure that gets passed around to the
	functions that implement the ex commands.  (The main ex command
	loop (see nvi/ex/ex.c) builds this up and then passes it to the
	ex functions.)

VICMD	In nvi/vi/vi.h.  The structure that gets passed around to the
	functions that implement the vi commands.  (The main vi command
	loop (see nvi/vi/vi.c) builds this up and then passes it to the
	vi functions.)