1#         @(#)structures      5.4 (Berkeley) 10/4/95
2
3There are three major data structures in this package, plus a single data
4structure per screen type.  The first is a single global structure (GS)
5which contains information common to all files and screens.  It hold
6global things like the input key queues, and functions as a single place
7to hang things.  For example, interrupt routines have to be able to find
8screen structures, and they can only do this if they have a starting
9point.  The number of globals in nvi is dependent on the screen type, but
10every screen type will have at least one global, __global_list, which
11references the GS structure.
12
13The GS structure contains linked lists of screen (SCR) structures.
14Each SCR structure normally references a file (EXF) structure.
15
16The GS structure has a set of functions which update the screen and/or
17return information about the screen from the underlying screen package.
18The GS structure never goes away.  The SCR structure persists over
19instances of screens, and the EXF structure persists over references to
20files.
21
22File names have different properties than files themselves, so the name
23information for a file is held in an FREF structure which is chained from
24the SCR structure.
25
26In general, functions are always passed an SCR structure, which usually
27references an underlying EXF structure.  The SCR structure is necessary
28for any routine that wishes to talk to the screen, the EXF structure is
29necessary for any routine that wants to modify the file.  The relationship
30between an SCR structure and its underlying EXF structure is not fixed,
31and various ex commands will substitute a new EXF in place of the current
32one, and there's no way to detect this.
33
34The naming of the structures is consistent across the program.  (Macros
35even depend on it, so don't try and change it!)  The global structure is
36"gp", the screen structure is "sp", and the file structure is "ep".
37
38A few other data structures:
39
40TEXT      In nvi/cut.h.  This structure describes a portion of a line,
41          and is used by the input routines and as the "line" part of a
42          cut buffer.
43
44CB        In nvi/cut.h.       A cut buffer.  A cut buffer is a place to
45          hang a list of TEXT structures.
46
47CL        The curses screen private data structure.  Everything to
48          do standalone curses screens.
49
50MARK      In nvi/mark.h.  A cursor position, consisting of a line number
51          and a column number.
52
53MSG       In nvi/msg.h.  A chain of messages for the user.
54
55SEQ       In nvi/seq.h.  An abbreviation or a map entry.
56
57TK        The Tcl/Tk screen private data structure.  Everything to
58          do standalone Tcl/Tk screens.
59
60EXCMD   In nvi/ex/ex.h.  The structure that gets passed around to the
61          functions that implement the ex commands.  (The main ex command
62          loop (see nvi/ex/ex.c) builds this up and then passes it to the
63          ex functions.)
64
65VICMD     In nvi/vi/vi.h.  The structure that gets passed around to the
66          functions that implement the vi commands.  (The main vi command
67          loop (see nvi/vi/vi.c) builds this up and then passes it to the
68          vi functions.)
69