contrib/nvi/docs/interp/interp

   1 # @(#)interp    8.5 (Berkeley) 10/19/96
   2                         Nvi Interpreter API
   3
   4 Introduction:
   5     The intention is to provide a way to graft a fairly generic extension
   6     language into nvi.  I think that the obvious candidates are Tcl/Rush,
   7     Scheme, Python and Perl.  Since the interpretation language chosen
   8     is often a religious issue, the method should be as flexible as
   9     possible.  I don't expect to rewrite the editor in the interpreted
  10     language, so that isn't a consideration.
  11
  12     Q: Is there any reason for nvi to support multiple interpreters in
  13        a single executable?
  14
  15 Interpreter functions in nvi:
  16
  17  1: Function to get the current screen pointer.
  18
  19     SCR *inter_screen();
  20
  21         Return a pointer to the current screen.
  22
  23  2: Functions to execute both ex and vi commands.  The return value of the
  24     function will be success/failure.  The editor itself will continue to
  25     handle the display of all messages and text for the foreseeable future.
  26
  27     int inter_vicmd(SCR *, char *cmds, size_t len);
  28     int inter_excmd(SCR *, char *cmds, size_t len);
  29
  30         The byte string cmds, of length len, is entered into the standard
  31         vi or ex parser, as if typed by the user.  The characters are not
  32         mapped in any way, i.e. the user's vi mappings don't apply.  If
  33         any error occurs, an error value is returned, and the rest of the
  34         characters are discarded.
  35
  36  3: Functions to handle lines of text in the file.
  37
  38     int inter_gline(SCR *, recno_t lno, char **lp, size_t *lenp);
  39
  40         Return a pointer to the text of the line lno, into the location
  41         referenced by lp, and its length into the location referenced by
  42         lenp.
  43
  44     int inter_dline(SCR *, recno_t lno);
  45
  46         Delete the line lno from the file.
  47
  48     int inter_aline(SCR *, recno_t lno, char *lp, size_t len);
  49
  50         Append a line consisting of the len bytes of text referenced by
  51         lp to the line lno.
  52
  53     int inter_iline(SCR *, recno_t lno, char *lp, size_t len);
  54
  55         Insert a line consisting of the len bytes of text referenced by
  56         lp before the line lno.
  57
  58     int inter_sline(SCR *, recno_t lno, char *lp, size_t len);
  59
  60         Replace line lno with the len bytes of text referenced by lp.
  61
  62     int inter_lline(SCR *, recno_t *lnop);
  63
  64         Return the number of the last line in the file in the location
  65         referenced by lnop.
  66
  67  4: Function to post an error message to the user.
  68
  69     int inter_msgq(SCR *, enum msgtype, char *fmt, ...);
  70
  71     Display the message for the user.  Valid message types are:
  72
  73         M_BERR       Error: M_ERR if  verbose, else bell.
  74         M_ERR        Error: Display in inverse video.
  75         M_INFO        Info: Display in normal video.
  76         M_SYSERR     Error: M_ERR, using strerror(3) message.
  77         M_VINFO       Info: M_INFO if verbose, else ignore.
  78
  79  5: Function to manipulate cut buffers.
  80
  81     int inter_setbuf(SCR *, CHAR_T buffer);
  82
  83         Create the specified buffer if it does not exist (the
  84         buffer will have no contents).
  85
  86     int inter_getbuf(SCR *, CHAR_T buffer, TEXT **textp);
  87
  88         Return a pointer to the specified buffer in the location
  89         referenced by textp.  (Since a pointer to the real item
  90         is being returned, it can be manipulated in any way the
  91         interpreter chooses.)
  92
  93  6: Functions to manipulate marks.
  94
  95     int inter_setmark(SCR *, CHAR_T name);
  96
  97         Create the specified mark if it does not exist (the
  98         mark will have no contents).
  99
 100     int inter_getmark(SCR *, CHAR_T name, MARK **markp);
 101
 102         Return a pointer to the specified mark in the location
 103         referenced by markp.  (Since a pointer to the real item
 104         is being returned, it can be manipulated in any way the
 105         interpreter chooses.)
 106
 107  7: Function to manipulate screens.
 108
 109     SCR *inter_iscreen();
 110
 111         Create a new screen, and return a pointer to it.
 112
 113     int inter_escreen(SCR *);
 114
 115         End a screen.
 116
 117  8: Functions to get input from the user.
 118
 119     int inter_getchar(CHAR_T *chp,
 120         enum maptype {NONE, INPUT, COMMAND} mapt);
 121
 122         Return a character from the keyboard into the location referenced
 123         by chp.  Mapt can be set to INPUT, COMMAND or NONE, depending on
 124         what vi mappings should be applied to the character.
 125
 126     int inter_getline(SCR *, char *prompt, CHAR_T **linep,
 127         size_t *lenp, enum maptype {NONE, INPUT, COMMAND} mapt);
 128
 129         Return a pointer to a line entered by the user, and its length,
 130         into the locations linep and lenp.  A prompt may be specified
 131         by prompt, and mappings by mapt.
 132
 133     int inter_freeline(CHAR_T *linep);
 134
 135         Free the memory that was allocated by inter_getline();
 136
 137  9: Function to retrieve and set the cursor.
 138
 139     int inter_getcursor(SCR *, MARK *mark);
 140
 141         Store the current cursor position in mark.
 142
 143     int inter_setcursor(SCR *, MARK *mark);
 144
 145         Set the current cursor position to mark.
 146
 147 10: Function to return a motion command from the user.
 148
 149     int inter_getmotion(SCR *,
 150         MARK *start, MARK *end, enum movetype {LINE, CHAR} *mt);
 151
 152         Nvi gets a motion command from the user and returns the starting
 153         and stopping points of the movement, reordered from the beginning
 154         to the end of the file.  The standard rules for line/character
 155         motions are applied, and returned to the interpreter through the
 156         mt argument.
 157
 158 11: Functions to return pathnames.
 159
 160 12: Functions to return edit options.
 161
 162 13: Nvi commands which will send text to the interpreter.
 163
 164     Nvi will have a new ex command "inter", which will pipe the rest of
 165     the line up to the first unescaped <newline> to the interpreter, of
 166     the following form:
 167
 168         :[address[,address]] inter [count] command
 169
 170     The interface from the ex command to the interpreter is a function:
 171
 172     int inter_ex(
 173         SCR *,                          /* Current screen. */
 174         char *cmd;                      /* The command. */
 175         size_t len;                     /* The command length. */
 176         MARK *start,                    /* Starting address for INTER_EX */
 177         MARK *end,                      /* Ending address for INTER_EX */
 178         int count);                     /* Count. */
 179
 180     Nvi will have a new vi command "*<buffer>" which will pipe the contents
 181     of the named buffer to the interpreter, of the following form:
 182
 183         [count]*<buffer>
 184
 185     The interface from the vi command to the interpreter is a function:
 186
 187     int inter_vi(
 188         SCR *,                          /* Current screen. */
 189         CHAR_T buffer,                  /* Buffer. */
 190         int count);                     /* Count. */