diff options
Diffstat (limited to 'contrib/nvi/docs/interp/interp')
| -rw-r--r-- | contrib/nvi/docs/interp/interp | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/contrib/nvi/docs/interp/interp b/contrib/nvi/docs/interp/interp new file mode 100644 index 0000000..3da5a8f --- /dev/null +++ b/contrib/nvi/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. */ |
