2 files changed, 236 insertions, 0 deletions

diff --git a/docs/interp/interp b/docs/interp/interp
new file mode 100644
index 000000000000..3da5a8f656dc
--- /dev/null
+++ b/docs/interp/interp
@@ -0,0 +1,190 @@
+# @(#)interp	8.5 (Berkeley) 10/19/96
+			Nvi Interpreter API
+
+Introduction:
+    The intention is to provide a way to graft a fairly generic extension
+    language into nvi.  I think that the obvious candidates are Tcl/Rush,
+    Scheme, Python and Perl.  Since the interpretation language chosen
+    is often a religious issue, the method should be as flexible as
+    possible.  I don't expect to rewrite the editor in the interpreted
+    language, so that isn't a consideration.
+
+    Q: Is there any reason for nvi to support multiple interpreters in
+       a single executable?
+
+Interpreter functions in nvi:
+
+ 1: Function to get the current screen pointer.
+
+    SCR *inter_screen();
+
+	Return a pointer to the current screen.
+
+ 2: Functions to execute both ex and vi commands.  The return value of the
+    function will be success/failure.  The editor itself will continue to
+    handle the display of all messages and text for the foreseeable future.
+
+    int inter_vicmd(SCR *, char *cmds, size_t len);
+    int inter_excmd(SCR *, char *cmds, size_t len);
+
+	The byte string cmds, of length len, is entered into the standard
+	vi or ex parser, as if typed by the user.  The characters are not
+	mapped in any way, i.e. the user's vi mappings don't apply.  If
+	any error occurs, an error value is returned, and the rest of the
+	characters are discarded.
+
+ 3: Functions to handle lines of text in the file.
+
+    int inter_gline(SCR *, recno_t lno, char **lp, size_t *lenp);
+
+	Return a pointer to the text of the line lno, into the location
+	referenced by lp, and its length into the location referenced by
+	lenp.
+
+    int inter_dline(SCR *, recno_t lno);
+
+	Delete the line lno from the file.
+
+    int inter_aline(SCR *, recno_t lno, char *lp, size_t len);
+
+	Append a line consisting of the len bytes of text referenced by
+	lp to the line lno.
+
+    int inter_iline(SCR *, recno_t lno, char *lp, size_t len);
+
+	Insert a line consisting of the len bytes of text referenced by
+	lp before the line lno.
+
+    int inter_sline(SCR *, recno_t lno, char *lp, size_t len);
+
+	Replace line lno with the len bytes of text referenced by lp.
+
+    int inter_lline(SCR *, recno_t *lnop);
+
+	Return the number of the last line in the file in the location
+	referenced by lnop.
+
+ 4: Function to post an error message to the user.
+
+    int inter_msgq(SCR *, enum msgtype, char *fmt, ...);
+
+    Display the message for the user.  Valid message types are:
+
+	M_BERR       Error: M_ERR if  verbose, else bell.
+	M_ERR        Error: Display in inverse video.
+	M_INFO        Info: Display in normal video.
+	M_SYSERR     Error: M_ERR, using strerror(3) message.
+	M_VINFO       Info: M_INFO if verbose, else ignore.
+
+ 5: Function to manipulate cut buffers.
+
+    int inter_setbuf(SCR *, CHAR_T buffer);
+
+	Create the specified buffer if it does not exist (the
+	buffer will have no contents).
+
+    int inter_getbuf(SCR *, CHAR_T buffer, TEXT **textp);
+
+	Return a pointer to the specified buffer in the location
+	referenced by textp.  (Since a pointer to the real item
+	is being returned, it can be manipulated in any way the
+	interpreter chooses.)
+
+ 6: Functions to manipulate marks.
+
+    int inter_setmark(SCR *, CHAR_T name);
+
+	Create the specified mark if it does not exist (the
+	mark will have no contents).
+
+    int inter_getmark(SCR *, CHAR_T name, MARK **markp);
+
+	Return a pointer to the specified mark in the location
+	referenced by markp.  (Since a pointer to the real item
+	is being returned, it can be manipulated in any way the
+	interpreter chooses.)
+
+ 7: Function to manipulate screens.
+
+    SCR *inter_iscreen();
+
+	Create a new screen, and return a pointer to it.
+
+    int inter_escreen(SCR *);
+
+	End a screen.
+
+ 8: Functions to get input from the user.
+
+    int inter_getchar(CHAR_T *chp,
+	enum maptype {NONE, INPUT, COMMAND} mapt);
+
+	Return a character from the keyboard into the location referenced
+	by chp.  Mapt can be set to INPUT, COMMAND or NONE, depending on
+	what vi mappings should be applied to the character.
+
+    int inter_getline(SCR *, char *prompt, CHAR_T **linep,
+	size_t *lenp, enum maptype {NONE, INPUT, COMMAND} mapt);
+
+	Return a pointer to a line entered by the user, and its length,
+	into the locations linep and lenp.  A prompt may be specified
+	by prompt, and mappings by mapt.
+
+    int inter_freeline(CHAR_T *linep);
+
+	Free the memory that was allocated by inter_getline();
+
+ 9: Function to retrieve and set the cursor.
+
+    int inter_getcursor(SCR *, MARK *mark);
+
+	Store the current cursor position in mark.
+
+    int inter_setcursor(SCR *, MARK *mark);
+
+	Set the current cursor position to mark.
+
+10: Function to return a motion command from the user.
+
+    int inter_getmotion(SCR *,
+	MARK *start, MARK *end, enum movetype {LINE, CHAR} *mt);
+
+	Nvi gets a motion command from the user and returns the starting
+	and stopping points of the movement, reordered from the beginning
+	to the end of the file.  The standard rules for line/character
+	motions are applied, and returned to the interpreter through the
+	mt argument.
+
+11: Functions to return pathnames.
+
+12: Functions to return edit options.
+
+13: Nvi commands which will send text to the interpreter.
+
+    Nvi will have a new ex command "inter", which will pipe the rest of
+    the line up to the first unescaped <newline> to the interpreter, of
+    the following form:
+   
+	:[address[,address]] inter [count] command
+
+    The interface from the ex command to the interpreter is a function:
+
+    int inter_ex(
+	SCR *,				/* Current screen. */
+	char *cmd;			/* The command. */
+	size_t len;			/* The command length. */
+	MARK *start,			/* Starting address for INTER_EX */
+	MARK *end,			/* Ending address for INTER_EX */
+	int count);			/* Count. */
+
+    Nvi will have a new vi command "*<buffer>" which will pipe the contents
+    of the named buffer to the interpreter, of the following form:
+
+	[count]*<buffer>
+
+    The interface from the vi command to the interpreter is a function:
+
+    int inter_vi(
+	SCR *,				/* Current screen. */
+	CHAR_T buffer,			/* Buffer. */
+	int count);			/* Count. */
diff --git a/docs/interp/spell.ok b/docs/interp/spell.ok
new file mode 100644
index 000000000000..4ca990c21720
--- /dev/null
+++ b/docs/interp/spell.ok
@@ -0,0 +1,46 @@
+API
+BERR
+Mapt
+Nvi
+Perl
+SCR
+SYSERR
+Tcl
+VINFO
+aline
+callback
+chp
+cmd
+cmds
+dline
+enum
+escreen
+excmd
+freeline
+getbuf
+getcursor
+getline
+getmotion
+gline
+iline
+int
+interp
+iscreen
+lenp
+linep
+lline
+lno
+lnop
+lp
+mapt
+maptype
+movetype
+msgq
+msgtype
+nvi
+recno
+setcursor
+sline
+strerror
+textp
+vicmd