REF VEDPROCS                              Dan Perri & Aaron Sloman, 1989
                                           Updated John Gibson, Nov 1995

     COPYRIGHT University of Sussex 1995. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<    VED SYSTEM PROCEDURES    >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file lists  most of the  Ved system procedures:  some of these  are
built into  the Poplog  system, others  are autoloadable  library  files
defined in the Pop-11 library  $popvedlib. Some of these procedures  are
mapped to Ved logical keys.
    Additional Ved  procedures are  described in  REF * VEDCOMMS  (which
deals with Ved <ENTER> commands) and REF * VEDTERMINALS (Screen  control
and key  mappings). REF * VEDSEARCH  gives a  comprehensive overview  of
searching in Ved.

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction
      1.1   Ved Buffers
      1.2   Real-File and Pseudo-File Buffers
      1.3   Note on Line/Column Coordinates

  2   File/Buffer Management
      2.1   filearg Argument to vededit, vedopen and vedreadfile
      2.2   Creating/Selecting Buffers
      2.3   Ved Initialisation Procedures
      2.4   Per-File Initialisation Procedures
      2.5   Quitting a File

  3   Reading and Writing Files
      3.1   Ved File Representation
            ... Character Attributes
            ... Special Characters
            ... Embedded Strings & Words
      3.2   Reading
      3.3   Writing

  4   Ved Buffer Utilities

  5   Refreshing All or Part of a Ved Window

  6   Changing or Testing Cursor Location

  7   Ved Input and Output
      7.1   Low Level
      7.2   Higher Level
      7.3   Mapping Input Characters to Procedures

  8   The Ved Main Loop

  9   Inserting and Deleting Text
      9.1   Inserting
      9.2   Deleting

 10   The Command/Status Line

 11   Text Editor Functions

 12   Searching Procedures

 13   Program Editor Functions

 14   Window Management

 15   Screen Management

 16   Ved Special Characters
      16.1  Graphics Characters
      16.2  Special Spaces Etc

 17   Ved-Buffer Devices and "Immediate Mode"

 18   Marked Range

 19   Embedded Text Actions
      19.1  Constructing Text Actions
      19.2  Standard Text Actions

 20   Miscellaneous Utilities
      20.1  Bracket Matching

 21   User-Definable Procedures

 22   Other Facilities
      22.1  Procedures for Acting on Rectangular Blocks of Text
      22.2  Reading Output from a Shell Command into a Ved Buffer (Unix Only)



---------------
1  Introduction
---------------

1.1  Ved Buffers
----------------
The unit of editing  in Ved, a  buffer, is stored  in a Ved  file/buffer
structure, which has a  large number of fields  (currently 35) to  store
the values of all  associated variables. For more  details refer to  the
section Variables Associated With Each Ved File in REF * VEDVARS.

One field holds the value of vedbuffer, which stores the content of  the
file itself. vedbuffer is a vector with one element for each line of the
file, where each element is  a vedstring (string or dstring)  containing
that line.

(Dstrings are an alternate  form of string  allowing attributes such  as
'bold' and  'underline' to  be  represented for  each character  --  see
Display Strings in  REF * STRINGS. A  vedstring is a  string or  dstring
which may have embedded  data associated with any  of its characters  --
see Vedstrings in REF * STRINGS.)

The file structure for the current  file is held in the active  variable
ved_current_file. When  assigned  to,  it automatically  saves  the  Ved
global variables in the current file structure, and then assigns all the
globals from the new file structure.

The Ved  file structure  for each  currently active  file is  stored  in
vedbufferlist. (See also * ved_rb in REF * VEDCOMMS).


1.2  Real-File and Pseudo-File Buffers
--------------------------------------
Ved buffers can  represent edits of  actual disk files,  or they can  be
'pseudo  files'.  Once  created,  this  distinction  is  encoded   for a
particular buffer  by  the value  of  the variable  veddirectory,  which
contains either  a  directory string  for  a  real file,  or  false  for
anything else.

However, the real/pseudo distinction is initially determined by the name
under which the  buffer is  created (the  value of  the buffer  variable
vedcurrent). On the basis  that no (sensible) filename  for a real  file
will contain a  space character,  a buffer  whose vedcurrent  contains a
space is deemed to be  a pseudo file. (Note  that this accords with  the
fact that the basic command for editing real files, <ENTER> ved,  treats
space-separated parts in its argument as indicating multiple files to be
edited, and thus cannot create or select any buffer with a space in  its
name.)

Hence the setting  of veddirectory is  determined by whether  vedcurrent
contains a space. For a real  filename without a space, veddirectory  is
set to  the directory  path string  needed to  make vedcurrent  into  an
absolute pathname. (I.e. nullstring  if vedcurrent is already  absolute,
or  current_directory  otherwise.  The  full  pathname  is  assigned  to
vedpathname.)

For a pseudo-file with a space  in the name, veddirectory is set  false.
Such a buffer can be one of two types:

  # A 'working' text buffer. This exists only inside Ved, and cannot  be
    written to  disk. (At  least,  not directly  --  a command  such  as
    <ENTER> wr can be  used to write  all or part  of the contents  to a
    specified file.) Such buffers can  be created with <ENTER> work  (or
    an existing buffer changed to one with <ENTER> name -w).

  # A special-purpose  buffer  for  which 'writing'  has  a  nonstandard
    meaning. (Such  buffers  have  a special  value  for  the  procedure
    ved_write_current_file, which will transform the buffer text in some
    way when  'written', and  may or  may not  involve actually  writing
    something to disk.)


1.3  Note on Line/Column Coordinates
------------------------------------
There are three different sets  of co-ordinates used by Ved  procedures:
buffer  co-ordinates  (vedline,  vedcolumn),  window  co-ordinates,  and
screen coordinates (vedscreenline, vedscreencolumn)

Some of the procedures (e.g. vedjumpto) take a line and a column in  Ved
buffer co-ordinates. I.e. the line is counted from the beginning of  the
file, and the column from the beginning of the current line of text. The
variables vedline and vedcolumn indicate the current location in  buffer
coordinates. The variable vedlineoffset indicates how many lines of text
are above the visible portion of the buffer.

Buffer co-ordinates are  represented below simply  as line, col,  line1,
col1, etc.

Some of the procedures (e.g. vedwindowpoint) take a line and a column in
WINDOW coordinates. I.e. the  status line is line  1, the first  visible
line of text  is line 2.  Similarly the leftmost  column of the  window,
reserved for "range"  marks (See  HELP * MARK) is window  column 1,  and
window column 2 is the first column  available for text. If the text  in
the window has scrolled left, then vedcolumnoffset indicates by how many
columns it has scrolled. If Ved is being used to display two windows  at
once on the same screen (e.g. on a VDU, or a single X window), then  the
variable vedscreenoffset represents  the location of  the first line  of
the current window  relative to the  screen. E.g.  it is 0  for the  top
window and for the lower window it  is the size of the upper window,  in
lines.

Window co-ordinates are represented as wline, wcol, etc.

Some of the procedures  (e.g. vedscreenxy) take a  line and a column  in
screen coordinates, where the  top left corner of  the screen is  line 1
column 1.  However, in  a multi-window  screen managed  by Sunview  or X
windows, the screen co-ordinates refer to the window used by the current
process, or  the  current Ved  window  if  each Ved  file  has  separate
windows.  The  variables  vedscreenline  and  vedscreencolumn  represent
current location on the "screen".

Screen coordinates are represented as sline, scol.

The following equations hold, in virtue of the above comments:

        wline   = vedline - vedlineoffset + 1
        wcol    = vedcolumn - vedcolumnoffset + 1

        wline   = vedscreenline - vedscreenoffset

There is  (at  present)  no vedscreencolumnoffset,  which  is  why  only
horizontal divisions within a screen are supported.




-------------------------
2  File/Buffer Management
-------------------------

2.1  filearg Argument to vededit, vedopen and vedreadfile
---------------------------------------------------------
The procedure vedreadfile is called by vededit and vedopen to make a new
Ved buffer, and  takes an  argument filearg  to specify  how the  buffer
should be constructed. This  argument may also be  given to vededit  and
vedopen, and is passed to vedreadfile in the case where the buffer  does
not already exist.  (Additionally for  vededit, filearg can  be used  to
control how the buffer window is initially displayed.)

The filearg argument to all three procedures takes the following values:

  (1) A file, that is, a filename  string or a device open for  reading.
      This may appear  either by itself,  or as the  first element  of a
      list in one of the forms

              [ file vedfileprops ]
              [ file vedfileprops subsystem_varname ]
              [ file vedfileprops " subsystem ]

      Except in the case where file  names a nonexistent file (OR,  is a
      pseudo-filename containing a  space -- see  above), the  vedbuffer
      lines of the new Ved buffer  will be read by calling vedreadin  on
      file (and collecting up the resultant strings in a vector).

      If file is nonexistent or  a pseudo-filename, vedbuffer is set  to
      an empty vector (and the new result from the procedure vedreadfile
      will be true -- note that new will be false in all other cases).

  (2) A reference containing a 2 or 3 element vector whose first element
      is any of the above, i.e.

              consref( { file_or_list ...} )

      If the second  element of  this vector is  false, file_or_list  is
      just processed as for case (1).

      Otherwise, the second element must be a procedure get_buffer_p  to
      create  the  actual  Ved  buffer.  Regardless  of  the  value   of
      file_or_list, this will be called as

              get_buffer_p(setting_on_screen) -> vedbuffer

      that is, the procedure is expected to return the actual  vedbuffer
      vector.  (The   setting_on_screen   value  is   as   supplied   to
      vedreadfile, and will be true for vededit, false for vedopen.)

      Irrespective of  the second  element's value,  if the  vector  has
      non-false third  element,  this  is supplied  by  vededit  as  the
      initarg argument to the  call of vedsetonscreen  to display a  new
      file. (See * vedsetonscreen below for possible values.)

In the new buffer, vedcurrent is set  to file (if that is a string),  or
device_open_name(file) if  a device;  vedpathname and  veddirectory  are
then  initialised  from  vedcurrent  (see  the  descriptions  of   those
variables in  REF * VEDVARS). Also  at  this point,  vedsetfiletypes  is
called on vedfiletypes to perform any variable initialisations based  on
the extension of vedcurrent, etc.

If a list  was present  in filearg, vedfileprops  is then  set from  its
second element.  Otherwise, vedfileprops  defaults to  "workbuff"  for a
pseudo-file, or false for a real file.

If the filearg list has a third element, subsystem is initialised either
to the  (" prefixed)  word  subsystem  or  to  the  valof  of  the  word
subsystem_varname. Otherwise, subsystem defaults to "pop11".

Following  these  initialisations,  the  defaults_p  argument  given  to
vededit, vedopen and vedreadfile  (such as vedveddefaults, for  example)
is called to set any other  user default values for the file  variables.
vednamestring is then set.

Finally, vedreadin or get_buffer_p is called to get vedbuffer. With  the
new  file   completely  set   up,   vedreadfile  calls   the   procedure
vedinitialise (with the vedreadfile new result as argument).

For vededit  and vedopen,  only  the buffer  name (i.e.  the  vedcurrent
value) is used when selecting an existing buffer. All other  information
applies to a new buffer only.


2.2  Creating/Selecting Buffers
-------------------------------

vededit(vedfilearg)                                          [procedure]
vededit(vedfilearg, setfocus)
vededit(vedfilearg, defaults_p)
vededit(vedfilearg, defaults_p, setfocus)
        The main entry point to Ved: selects an existing Ved buffer,  or
        creates a new one, setting up Ved first if this has not  already
        been done.  vedsetonscreen is  called  to display  the  selected
        buffer, which assigns it to ved_current_file, and makes it first
        in vedbufferlist.

        The vedfilearg argument can be  either a Ved file structure  for
        an  existing   buffer,  or   any  valid   filearg  argument   to
        * vedreadfile as described in the section above (e.g. a filename
        string).

        The optional defaults_p is a procedure for setting defaults;  if
        omitted,  the  procedure   in  vedveddefaults   is  used.   (See
        REF * vedveddefaults and also HELP * vedveddefaults.)

        setfocus is an optional boolean  argument. If true (the  default
        when omitted), the file  selected is assigned to  vedinputfocus;
        otherwise vedinputfocus  remains  unchanged  by  the  call.  (In
        general, use vededit(vedfilearg, false)  for any file that  will
        only be output  to; this  ensures that  the input  focus is  not
        taken away from a file that should keep it.)

        Setting Up
        If Ved has not already been set up, vededit first calls vedsetup
        (see * vedsetup below). Then, if vedinvedprocess is not  already
        true, it gets inside a call of vedprocess by adding the closure

            vededit(% vedfilearg, defaults_p, setfocus %)

        to Ved's input stream  (ved_char_in_stream), sets up  vedprocess
        as a process in vedprocessproc, and then runs it. Thus the first
        action performed by vedprocess will be to call vededit again  to
        get the file.

        In non-XVed, the process will not exit until there are no  files
        left (or vedexit is called); on exit, vededit resets the  screen
        for normal use and sets  vedupperfile and vedlowerfile false  to
        indicate there are no Ved windows on the screen.

        In XVed, however, the process is suspended whenever there is  no
        Ved input waiting  (see The Ved  Main Loop below).  vedupperfile
        (which is always set to the current file when that has a window)
        is not touched, because the window still exists.

        Once Ved is Set Up
        If vedfilearg is already a Ved file structure, then

                vedsetonscreen(vedfilearg, false)

        is called to display the file.

        Otherwise, vedfilearg  must be  a filearg  as described  in  the
        section above, and  the buffer  name (i.e.  vedcurrent part)  of
        this is  extracted and  given to  vedpresent to  determine  if a
        buffer of that  name already  exists. If  so, vedsetonscreen  is
        called on the file structure returned by vedpresent.

        If no buffer of the given name already exists,

            vedreadfile(vedfilearg, defaults_p, true)
                                        -> (new, vedfile_struct)

        is called  to  construct  a  new  vedfile_struct  (as  described
        above). The vedsetonscreen for this will have its initarg  (i.e.
        second) argument chosen thus:

          # if filearg contained an initarg  value (see above), that  is
            used;

          # if the new result from vedreadfile was true, then the string
            'NEW FILE name' or 'NEW  BUFFER name' (depending on  whether
            * veddirectory is false, qv);

          # otherwise, false.


vededitat(vedfilearg, defaults_p, int_or_string)             [procedure]
        Same as

                vededit(vedfilearg, defaults_p);

        but  with  * vvedgotoplace   set  to   int_or_string,  so   that
        vedsetonscreen will initially  position the buffer  at the  line
        numbered int, or the first line containing string.


edit(vedfilearg)                                             [procedure]
        Same as vededit(vedfilearg),  i.e. vedveddefaults  will be  used
        as the defaults procedure.


vedobey(vedfilearg, p)                                       [procedure]
        Runs the  procedure p  with vedfilearg  temporarily set  as  the
        current Ved file, restoring the previous environment afterwards.

        If the system is already inside vedprocess, vededit is called on
        vedfilearg, p is executed, and vededit is called to restore  the
        previous current file.

        If  not  already  inside   vedprocess,  vededit  is  called   on
        vedfilearg to get inside Ved, after adding to ved_char_in_stream
        a procedure which will call p, restore any old file, and then do
        vedexit(identfn) to return out of Ved.


vedfileselect()                                              [procedure]
        Prompts for a file to go to from vedbufferlist, by printing  out
        a list  of  the  buffer  names (on  the  status  line  if  space
        permits), with numbers  to choose the  one required.

        If more  than 9  files  are being  edited  then some  files  are
        referred to by  a number  and others  by a  letter. (There  is a
        limit of 35  files that  can be  selected in  this way.)  Typing
        anything but a  number or  letter corresponding to  a file  will
        return to the last file (e.g. just typing <RETURN>).

        If there  are too  many files  to display  on the  status  line,
        vedfileselect will edit a temporary buffer to show the names  of
        the files.

        (Note that for most keyboards,  vedfileselect is set on the  key
        sequence <ESC> e. If this setting is inconvenient, vedsetkey can
        be used to change it. E.g. putting the line

            vedsetkey('\e\^P', vedfileselect);

        in your  'vedinit.p'  would  set the  sequence  <ESC> CTRL-P  to
        activate vedfileselect.)


vedopen(vedfilearg)                        -> vedfile_struct [procedure]
vedopen(vedfilearg, defaults_p)            -> vedfile_struct
vedopen(vedfilearg, addtolist)             -> vedfile_struct
vedopen(vedfilearg, defaults_p, addtolist) -> vedfile_struct
        This  procedure  is  like   vededit,  but  instead  of   calling
        vedsetonscreen to  display  the  file,  it  merely  returns  the
        vedfile_struct for the file. (It  also does not assign the  file
        to ved_current_file, nor set up vedprocess, etc.)

        The vedfilearg and defaults_p arguments  are as for vededit.  If
        vedfilearg is already a Ved file structure, that is returned. If
        vedfilearg is a filearg,  vedpresent is used to  look for it  in
        vedbufferlist, and failing that,

            vedreadfile(vedfilearg, defaults_p, false)
                                        -> (, vedfile_struct)

        is called to create a new file.

        The optional boolean  addtolist argument says  whether the  file
        should be added to vedbufferlist. If  true (and the file is  not
        already there),  if  will  added at  the  END  of  vedbufferlist
        (unlike vedsetonscreen, which always makes it first).


2.3  Ved Initialisation Procedures
----------------------------------
These procedures are used to set up Ved initially.


vedsetup()                                                   [procedure]
        Called by vededit when  Ved is first used.  Does nothing if  the
        variable vedsetupdone is true. Otherwise, it

          # compiles   user    initialisation    files    (by    calling
            * vedinitcomp);

          # sets Ved up for  the type of  terminal currently being  used
            by calling  * vedinitterm (note  that  the XVed  version  of
            vedinitterm also calls * vedxvedinit);

          # executes any Ved  "runtime actions" stored  in the  variable
            * ved_runtime_actions;

          # executes the user-definable procedure * vedinit.

        Finally, it sets the variable vedsetupdone true, to prevent  the
        initialisation process being  repeated for  subsequent calls  to
        vededit.


vedinitcomp()                                       [procedure variable]
        Called by  vedsetup to  compile the  'vedinit.p'  initialisation
        files. These files  may contain  any Pop-11  code for  tailoring
        Ved. Both a site-wide  and a per-user  'vedinit.p' file will  be
        compiled if found: the site-wide file is sought in the directory
        $popsys; the  per-user file  is sought  first in  the  directory
        $poplib, and  failing that,  in the  current directory.  Neither
        file need exist. See HELP * INITIAL for more information.

        Note that the way  to create a saved  image with your  vedinit.p
        pre-compiled is to call vedinitcomp explicitly, and then  assign
        identfn to it, i.e.

            vedinitcomp();
            identfn -> vedinitcomp;

        This will stop Ved compiling it again on startup.


ved_runtime_apply(p)                                         [procedure]
        Used to defer Ved initialisations (e.g. key mappings) until  Ved
        is  first  used.   Adds  the   procedure  p  to   the  list   of
        initialisation    procedures     ved_runtime_actions,     unless
        vedsetupdone is true, in which case p is executed immediately.

        (The procedures in ved_runtime_actions are run immediately prior
        to running the vedinit procedure.)


ved_runtime_action                                              [syntax]
        This `define form' provides  syntactic sugar for notating  calls
        to ved_runtime_apply - the expression:

            define :ved_runtime_action <name>;
                <actions>
            enddefine;

        is precisely equivalent to

            ved_runtime_apply(
                procedure() with_props <name>;
                    <actions>
                endprocedure)

        (Note that <name> is optional, in which case the pdprops of  the
        procedure passed  to  ved_runtime_apply  are  false).  See  also
        LIB * DEFINE_VED_RUNTIME_ACTION and HELP * DEFINE_FORM.


vedinit()                                           [procedure variable]
        User-definable procedure called by vedsetup after compiling  the
        'vedinit.p' files  and setting  the terminal  type. Its  default
        value is identfn  and so does  nothing; it can  be redefined  to
        perform any user-specific tailoring.

        See also HELP * INITIAL, REF * VEDTERMINALS and HELP * TERMINAL.



2.4  Per-File Initialisation Procedures
---------------------------------------
These procedures are used  to assign global variables  every time a  new
Ved buffer is created.


vedsetfiletypes(list)                                        [procedure]
        This  procedure  is  applied  to  the  user-definable  list   of
        condition-action rules, vedfiletypes, (see  HELP * VEDFILETYPES)
        whenever a  new Ved  buffer is  created (Cf  vedveddefaults  and
        vedinitialise), to set the attribute variables according to  the
        file extension of the current file. It is also run when ved_name
        is used  to  rename a  Ved  file. vedsetfiletypes  can  also  be
        invoked  explicitly  by  users,   e.g.  in  the   user-definable
        procedure * vedveddefaults.


vedsearchfiletypes(filename, varname) -> (found, value)      [procedure]
        Searches vedfiletypes for a rule whose "condition" is  satisfied
        by filename, and whose "actions" reference the variable varname.
        If such a  rule is found,  vedsearchfiletypes returns the  value
        associated with  varname,  and  true  (indicating  a  successful
        search). Otherwise, false and false are returned.

        An example:

            vedsearchfiletypes('foo.lsp', "subsystem") =>
            ** <true> lisp

        Notes:

            (1) vedfiletypes is searched in reverse order
            (2) procedures in the "action" part of a rule are ignored


vedveddefaults()                                    [procedure variable]
        User assignable procedure run whenever a new Ved file is created
        or read in (defaults to identfn).

        This procedure is run after vedsetfiletypes, and BEFORE the file
        is read in. (In  contrast to vedinitialise,  which is run  AFTER
        the file is read in). See also HELP * VEDVEDDEFAULTS.


vedinitialise(item)                                 [procedure variable]
        User definable  procedure invoked  by  vedreadfile after  a  new
        buffer has  been created,  or after  ved_name has  been used  to
        change the name of the file.

        It allows initialisation actions to be performed after the  text
        buffer  exists,   unlike   vedvedefaults   and   the   call   of
        vedsetfiletypes(vedfiletypes), which occur  before the text  has
        been read in. The  argument item can take  one of the  following
        values, with the interpretations specified:

            true
                invoked by  vedreadfile  when  it creates  a  new  empty
                buffer because no file was found on disk.

            false
                invoked by vedreadfile  when it  has found  the file  on
                disk and read it in.

            "ved_name"
                invoked by ved_name when used  to change the name of  an
                existing file.

        (XVed Note:  When vedinitialise  is run  inside vedreadfile,  no
        window has yet been created for the new file, and wvedwindow  is
        false  (the  window  is  not  created  until  vedsetonscreen  is
        called). You can safely call vedputmessage during vedinitialise,
        since this  will put  the  message out  on  the window  for  the
        previous file (or on the basewindow), but you should not perform
        any other window operations.)


vedinitfile()                                       [procedure variable]
        User definable procedure called whenever a file is set on screen
        (defaults to identfn).

        You should not normally need to use this procedure. For  setting
        general  file  defaults,  use  the  vedfiletypes  mechanism   or
        vedveddefaults, which  operate  BEFORE a  file  is read  in,  or
        vedinitialise, which operates AFTER a file is read in.



2.5  Quitting a File
--------------------

vedqget(edit_p)                                              [procedure]
vedqget(edit_p, create_new_window)
        Quits the current file (checking if it needs writing), then runs
        the procedure edit_p to edit a new file.

        The optional boolean argument create_new_window says whether the
        new file should create  a new window in  XVed or use the  window
        from the file being quit; if  true, a new window is created,  if
        false (the default), the old window is used. (This argument  has
        no effect in non-XVed.)

        This procedure is used to define ved_qget, ved_qhelp,  ved_qref,
        etc: these are all procedures  that quit the current file,  then
        start up a new one (using the current window in XVed).

        For example, ved_qved is defined thus:

            define vars ved_qved();
                ;;; quit current edit and start another
                if vedargument = nullstring then chain(ved_q) endif;
                vedqget(ved_ved);   ;;; reuse old window in XVed
            enddefine;




----------------------------
3  Reading and Writing Files
----------------------------

The procedures below are used to get Ved files from disk, and write them
back again.  The most  basic  procedures are  vedfile_line_repeater  and
vedfile_line_consumer  (which   process   single   lines),   while   the
higher-level  vedreadfile  and  vedwritefiles  deal  directly  with  Ved
buffers.


3.1  Ved File Representation
----------------------------
This section describes  how Ved buffer  characters are represented  when
written to disk.

...  Character Attributes
-------------------------
From Poplog Version 14.11, Ved is  able to represent attributes such  as
'bold', 'underline',  and a  colour  number for  each character  in  the
buffer. (These can be inserted, for example, with the command

        <ENTER> chat

See REF * ved_chat for a description of the available attributes.)

When Ved  buffer lines  are  written to  a  file, characters  that  have
attributes are translated into sequences containing control  characters.
For  example,  the  word  'foo'  underlined  will  be  translated   to 3
underscores followed by  3 backspace characters,  followed by the  word,
i.e.

         _ _ _ <BS> <BS> <BS> f o o

Thus if  the file  is printed,  the  'foo' will  be overprinted  on  the
underscores, making it appear underlined.  This is also how  alternative
font (italic)  will appear  (although that  includes extra  non-printing
control characters to distinguish it from underlining).

Other attributes  are encoded  by  just inserting  non-printing  control
characters, and  will therefore  not show  up at  all when  the file  is
printed. Regardless  of this,  all  characters attributes  are  uniquely
represented, and will be correctly restored  when the file is read  back
into Ved.

...  Special Characters
-----------------------
Ved graphics and special space characters are also represented in  files
by special  control  sequences,  which  cause them  to  print  as  their
ordinary substitute  characters.  See Ved  Special  Characters below.

...  Embedded Strings & Words
-----------------------------
From Poplog Version 15+, any character  in a Ved buffer string can  have
an arbitrary data item attached to it. This is called embedded data (and
is   implemented   by   the   "vedstring"   procedures   described    in
REF * STRINGS). However, only embedded strings, dstrings or words can be
written to a  file, and  if any  character in  a buffer  has other  data
attached to it, attempting to write the buffer will cause a mishap.

An embedded string or word is written out as a sequence of  non-printing
control characters, immediately preceding  the character it is  attached
to. (In general,  embedded characters will  occupy 1.25 -  1.5 times  as
many bytes on the output file.)



3.2  Reading
------------

vedreadfile(filearg, defaults_p) -> (new, vedfile_struct)    [procedure]
vedreadfile(filearg, defaults_p, setting_on_screen)
                               -> (new, vedfile_struct)
        This procedure  creates and  returns a  new Ved  file  structure
        vedfile_struct,  given  an   input  specification  filearg and a
        defaults   procedure    defaults_p.   The    optional    boolean
        setting_on_screen says whether the  new file is being  displayed
        or not.

        The section filearg Argument to vededit, vedopen and vedreadfile
        above gives full details of the possible values for the  filearg
        argument.


vedreadin(file)        -> (line1, ..., lineN, N)             [procedure]
vedreadin(file, plain) -> (line1, ..., lineN, N)
vedreadin(file)        -> false
vedreadin(file, plain) -> false
        Using vedfile_line_repeater, reads in all the lines from a  file
        or device file, converts them to buffer strings, and leaves them
        on the stack.

        Both the file argument and  the optional plain argument are  the
        same as for  vedfile_line_repeater (see below),  and are  passed
        directly to that procedure.

        The number of  lines read, N,  is returned as  the last  result.
        However, if an error or interrupt occurs while reading the file,
        false is returned instead (and no lines).


vedfile_line_repeater(file)        -> line_repeater          [procedure]
vedfile_line_repeater(file, plain) -> line_repeater
        This is  the most  basic  Ved read  procedure,  and is  used  by
        vedreadin, vedreadfile, vedselect, ved_r, etc.

        It takes a file  name or input  device file (corresponding  to a
        disc  file,  pipe  or  mailbox,  etc).  It  returns  a  repeater
        procedure for Ved buffer lines, i.e. a procedure of the form

                line_repeater() -> string_or_termin

        Each time line_repeater is called,  it reads the next line  from
        the file/device, converts it to a buffer string, and returns it.
        termin is returned at end of file.

        As described in Ved File Representation above, certain sequences
        of control  characters appearing  in  lines are  interpreted  as
        character attributes, Ved special characters, or embedded string
        data. Where any character in  a line has attributes, the  result
        of line_repeater will be a dstring rather than an ordinary  one;
        if any character in a line has an embedded string attached,  the
        string  will  have  an   entry  in  * vedstring_data_prop   (see
        REF * STRINGS).

        However, the  optional plain  argument may  be used  to  disable
        these interpretations. If true, the  file is read 'as is',  with
        no  control  characters  being  interpreted  (and  all   strings
        returned will be ordinary ones).

        If plain is  omitted, it defaults  to the current  value of  the
        variable vedreadinplain (whose default value is false). Thus you
        can   use   vedreadinplain    to   control    the   action    of
        vedfile_line_repeater  when   called   indirectly   from   other
        procedures (like vedreadin, vededit, etc).

        Normally,  you   would  use   a  true   value  for   plain   (or
        vedreadinplain) if you wanted to read in an ASCII file that  was
        produced by a program  other than Ved,  and which also  contains
        control characters that should not be interpreted as attributes,
        etc.

        However, certain operating-system utilities (such as nroff  used
        by the  Unix  man  command)  produce  files  with  'underlining'
        represented in a  similar way  to Ved's  underlining (i.e.  with
        underscores and backspaces).  To specify  that such  underlining
        (only) should be interpreted in terms of Ved attributes (but not
        other   control    characters),   the    plain   argument    (or
        vedreadinplain) may  also be  an integer  character,  containing
        only attribute bits; 'underlined' characters will then be  given
        those attributes.

        For example, ved_man uses

                vedreadin(pipe, `\[bi]`)

        to read  lines  from  a  Unix  pipe,  with  the  plain  argument
        specifying 'bold italic'. (See  REF * ITEMISE for a  description
        of the  \[...]  form  for  specifying  character  attributes  in
        character constants.)

        The behaviour of vedfile_line_repeater  is also affected by  the
        variables   vedindentstep,    vedreadintabs,    vednotabs    and
        vedreadintrailspaces.   See   the    entries   for   these    in
        REF * VEDVARS.


3.3  Writing
------------

vedwritefiles()                                              [procedure]
        Write all writeable  and changed files  in vedbufferlist;  calls
        ved_write_current_file(false)  with  each   such  file  set   as
        ved_current_file.


ved_write_current_file(explicit)          [protected procedure variable]
        Procedure called  by  ved_w1  and  vedwritefiles  to  write  the
        current file ved_current_file.

        explicit is true if the  file is being written explicitly,  i.e.
        if called from ved_w1 (as opposed to being written implicitly by
        vedwritefiles).

        The standard value of this procedure does

            vedwriterange(vedpathname, 1, vvedbuffersize);

        to write the  buffer contents to  disk, providing vedchanged  is
        true and veddirectory is not  false. (If veddirectory is  false,
        the buffer does not  correspond to an actual  disk file, and  an
        error will result if explicit  is true, otherwise the  procedure
        does nothing.)

        (N.B. This procedure  is locally redefined  for special  buffers
        where 'writing'  the buffer  means something  other than  simply
        writing the contents to disk.)


vedwriterange(file, line1, line2)                            [procedure]
vedwriterange(line1, line2, file)
        Using  vedfile_line_consumer,  writes  text  lines  from  buffer
        line1 to line2 inclusive to the filename or device file.

        file may appear either as the first argument (first form) or the
        last argument (second form) but the first form is preferred.

        Note that if file is a  device, vedwriterange will not close  it
        afterwards.


vedappendrange(file, line1, line2)                           [procedure]
        Similar to  vedwriterange, except  that the  lines of  text  are
        appended to the existing contents of file.

        If file is a device, then it should have been opened for reading
        and writing -- i.e. with access  mode 2 -- to allow for  reading
        to the end of file before updating. See REF * SYSIO.


vedfile_line_consumer(file)        -> line_consumer          [procedure]
vedfile_line_consumer(file, plain) -> line_consumer
        This is  the most  basic Ved  write procedure,  and is  used  by
        vedwriterange, etc.

        It takes  a  filename  or  output  device  file,  and  returns a
        consumer for Ved buffer lines, i.e. a procedure of the form

                line_consumer(string_or_termin)

        (If file is a  filename, a device is  first created for it  with
        syscreate.)

        Each time line_consumer is called  with a string as argument  it
        writes the line to the device. If the given string is a  dstring
        containing character attributes, and/or the string has  embedded
        string data (i.e. an  entry in * vedstring_data_prop), then  the
        appropriate encodings are  performed (as described  in Ved  File
        Representation above). Ved special characters in the string  are
        also translated.

        Calling line_consumer(termin) will close the output device (i.e.
        either the one supplied or the one created).

        The optional argument plain can be used to prevent special  data
        being encoded in the output, as follows:

            Plain Value     Action
            -----------     ------
            0 (or false)    Character attributes, Ved special characters
                            (graphics, etc),  and embedded  strings  are
                            encoded in the output (the normal mode).

            1               Character attributes  and  embedded  strings
                            are ignored, but Ved special characters  are
                            recognised and translated  to their  default
                            substitute characters. (This  gives a  plain
                            ASCII equivalent of the file.)

            2               Character attributes  and  embedded  strings
                            are ignored, and  no special characters  are
                            interpreted  except   trailing   space   and
                            trailing newline.

            3 (or true)     Same  as  2,   without  trailing  space   or
                            trailing newline being interpreted either.

        If the plain  argument is  omitted, it defaults  to the  current
        value of the variable  vedwriteoutplain (whose default value  is
        false). Thus you can use vedwriteoutplain to control the  action
        of  vedfile_line_consumer  when  called  indirectly  from  other
        procedures (like vedwriterange, or ved_w, etc).

        For example, the following procedure could be used to filter out
        all special control characters  from a Ved  file (and write  the
        result to the standard output):

           define filter(file);
               lvars file, procedure (repeater, consumer), string;
               vedfile_line_repeater(file) -> repeater;
               vedfile_line_consumer(popdevout, 1) -> consumer;
               until (repeater() ->> string) == termin do
                   consumer(string)
               enduntil;
           enddefine;




-----------------------
4  Ved Buffer Utilities
-----------------------

vedappfiles(p)                                               [procedure]
        Apply the procedure p to every file structure in vedbufferlist.

        ved_current_file is locally set to each file in turn, and p() is
        called  (with  no   arguments).  (Note  that   for  each   file,
        ved_on_status is locally set false before calling p.)


vedbufferextend()                                            [procedure]
        Ensure there  is enough  room  for at  least  one more  line  in
        vedbuffer.


vedbuffername(vedfile_struct)       -> string                [procedure]
vedbuffername(vedfile_struct, true) -> string
        Returns  the  name  of  the  vedfile_struct,  i.e.  the   string
        corresponding to vedcurrent. If  the optional true is  included,
        the full pathname, i.e. the string corresponding to  vedpathname
        is returned. See REF * VEDVARS.


vedpresent(vedfile) -> vedfile_struct_or_false               [procedure]
        The argument is  either a  file name  or a  Ved file  structure.
        Tests whether  there  is a  buffer  for the  file  currently  in
        vedbufferlist and returns the vedfile_struct for that if  found,
        otherwise false. See also REF * vedsearchlist.


ved_save_file_globals()                                      [procedure]
        Saves  the  values  of  the  global  Ved  variables  (the   file
        attributes) in the file structure for the current Ved file (i.e.
        ved_current_file). See REF * ved_current_file.


is_vedfile_local(ident)                 -> bool              [procedure]
is_vedfile_local(ident, vedfile_struct) -> bool
bool -> is_vedfile_local(ident)
bool -> is_vedfile_local(ident, vedfile_struct)
        This procedure represents a mechanism  whereby the idval of  any
        identifier ident  can be  localised  to the  Ved file  given  by
        vedfile_struct.   If   omitted,   vedfile_struct   defaults   to
        ved_current_file.

        When localised, the file maintains its own private value for the
        identifier -- that  is, whenever vedfile_struct  is assigned  to
        ved_current_file, the  private  value is  set  as the  idval  of
        ident, and when  vedfile_struct ceases to  be the current  file,
        the current private value is saved and the public (or some other
        file-private) value restored.

        The  base  procedure   returns  true  if   ident  is  local   to
        vedfile_struct,  false  otherwise.  This  applies  for  all  the
        standard Ved file variables also, e.g.

            is_vedfile_local(ident vednotabs) =>
            ** <true>

        For the updater,  if bool is  true then ident  is made local  to
        vedfile_struct  (if   not   already).   If   vedfile_struct   is
        ved_current_file, subsequent changes  to the identifier's  value
        will be private to this file. For example,

            true -> is_vedfile_local(ident current_directory);

        would cause  any  subsequent  directory  changes  while  in  the
        current file (e.g.  with <ENTER> cd)  to have no  effect on  the
        current directory while in other files.

        If bool is false, ident is de-localised from vedfile_struct  (if
        it was local). If vedfile_struct is ved_current_file, the public
        value of ident  (at the time  the file became  current) will  be
        restored (or some other file-private value).

        (Note that a mishap  will result if  you attempt to  de-localise
        one of the standard Ved file variables from a file.)


newvedfileprop() -> prop                                     [procedure]
        Returns a  property  (see REF * PROPS)  which  is keyed  to  the
        current Ved file, i.e. to ved_current_file.

        That is, prop is procedure of the form

            prop() -> item
            item -> prop()

        which will associate a  given item with  the current file.  E.g.
        after

            vars owner = newvedfileprop();

        an assignment such as

            "me" -> owner();

        will cause "me" to be returned for the file which is current  at
        the time of the assignment, i.e.

            owner() =>
            ** me

        but not for any other file. Note that the default value of  prop
        for any particular file is undef.


isvedfileprop(item) -> bool                                  [procedure]
        Returns  true   if   item   is   a   property   constructed   by
        newvedfileprop, false otherwise.




-----------------------------------------
5  Refreshing All or Part of a Ved Window
-----------------------------------------

vedrefresh()                                                 [procedure]
        Refresh current window.  Often mapped onto  a function key.  Use
        vedrestorewindows   to   refresh   both   windows.   See   also:
        vedrefreshline,         vedrefreshrange,         vedrefreshtail,
        vedrefreshstatus.


vedrefreshline(blank, wline, string, char_or_false)          [procedure]
        Refresh the  window line  wline (line  1 =  status line),  using
        characters from the string (starting from window column 2).

        If the boolean  blank is  true then the  line is  assumed to  be
        blank already, otherwise it is cleared first.

        If char_or_false is an integer character (e.g.  -vedscreenmark),
        then output that character in column 1, otherwise output a space
        in column 1.

        N.B. This procedure doesn't check that wline <= vedwindowlength.

        See also * vedrefreshrange, * vedrefreshtail.


vedrefreshpartline(bool, wline, wcol, n, num, string)        [procedure]
        Refresh part  of a  line in  the current  window, starting  from
        wline, wcol (in window co-ordinates, i.e. wline 1 = status line)
        Use num characters from string, starting from n'th character  in
        string. If num  = 0  use all the  characters in  the string.  If
        there are not enough  characters in the  string leave the  extra
        space blank. If bool  is true, assume that  the line is  already
        blank, otherwise first blank the portion to be over-written.

        NB doesn't check that wline <= vedwindowlength, or that wcol  <=
        vedscreenwidth. See  also:  * vedrefreshtail,  * vedrefreshline,
        * vedscreenblankpartline.


vedrefreshtail(bool, wline, wcol, n, string)                 [procedure]
        Refresh right hand part of line in current window, starting from
        location wline,  wcol (in  window coordinates).  Use  characters
        from string, starting from n'th character in string.

        If bool  is  true,  assume  that  the  line  is  already  blank,
        otherwise first blank it.

        N.B. Doesn't check that wline  <= vedwindowlength, or that  wcol
        <=     vedscreenwidth.      See      also      * vedrefreshline,
        * vedrefreshpartline.


vedscreenblankpartline(wline, wcol, num) -> bool             [procedure]
        On window line wline, starting from window column wcol blank num
        spaces, leaving Ved buffer unchanged.  Return true if only  part
        of the tail of the line was blanked, false if it was all blanked
        (using vedscreencleartail as a short cut).


vedresize(n_lines, n_cols)                                   [procedure]
vedresize(n_lines, n_cols, redraw)
        Resizes the display to fit an output window of n_lines x n_cols.
        Used for  screens  which  support  variable-sized  windows.  The
        optional third  parameter redraw  is a  boolean flag  indicating
        whether the resized display should be redrawn: if this is false,
        the effect of the resize will not be visible until the next time
        the display is refreshed. The default is true.


vedrestorescreen()                                  [procedure variable]
        If any printing  has been  done (vedprintingdone  is true)  then
        print 'VED HERE' message, wait for user to press a key, and then
        restore screen.


vedrestorewindows()                                 [procedure variable]
        Refreshes both ved windows. Useful if screen has been corrupted.


vedsetscreen(string)                                         [procedure]
        Refresh screen,  making  sure  current location  is  in  visible
        portion, with string as message. Defined as

            vedalignscreen();
            vedputmessage(string);




--------------------------------------
6  Changing or Testing Cursor Location
--------------------------------------

This section deal with cursor movement, relative to the current position
or file location, and through use of the cursor position stack. Note the
last two entries, vedtrimline and vedsetlinesize which must be  executed
whenever vedline (the  line number  of the current  cursor position)  is
changed. Procedures that move the cursor  up or down alter the value  of
vedline. Those that move it left or right alter the value of vedcolumn.


vedatend() -> bool                                           [procedure]
        True if at end of file (i.e. after last line of text in file).


vedatstart() -> bool                                         [procedure]
        True if at the beginning of the first line of the file.


vedchardown()                                                [procedure]
        Move down to next line. Increments vedline


vedchardownleft()                                            [procedure]
        Move down diagonally to the left. Changes vedline and vedcolumn


vedchardownleftlots()                                        [procedure]
        Move down diagonally to the left, several times.


vedchardownlots()                                            [procedure]
        Move down several lines.


vedchardownright()                                           [procedure]
        Move down diagonally to the right.


vedchardownrightlots()                                       [procedure]
        Move down diagonally to the right, several times.


vedcharleft()                                                [procedure]
        Move left one location (decrementing vedcolumn). If necessary go
        to previous line.


vedcharleftlots()                                            [procedure]
        Move left several locations.


vedcharmiddle()                                              [procedure]
        Move to middle of text in current line.


vedcharnext()                                                [procedure]
        Move forward one location, incrementing vedcolumn. If  necessary
        go to next line.


vedcharright()                                               [procedure]
        Move right one location, incrementing vedcolumn


vedcharrightlots()                                           [procedure]
        Move right several locations.


vedcharup()                                                  [procedure]
        Move up a line, decrementing vedline. Error if at top of file.


vedcharupleft()                                              [procedure]
        Move up diagonally to left.


vedcharupleftlots()                                          [procedure]
        Move up diagonally to left, several times.


vedcharuplots()                                              [procedure]
        Move up several lines.


vedcharupright()                                             [procedure]
        Move up diagonally to right.


vedcharuprightlots()                                         [procedure]
        Move up diagonally to right, several times.


vedendfile()                                                 [procedure]
        Go to end of the current file.


vedendwordright()                                            [procedure]
        Moves the cursor to  just after the end  of the current word  or
        the next word if starting in a space. * vedatitemend is used  to
        determine the end.


vedinparagraph() -> item                            [procedure variable]
        True if  the  current  line  can  be  considered  as  part  of a
        paragraph. If item is of any  type other than boolean, then  the
        current line is assumed to be the first line of a paragraph.

        The default  definition returns  false  for empty  lines,  lines
        starting with a `.`, and  lines starting with a format-space  or
        standard graphics character;  it returns 1  for lines which  are
        indented from vedleftmargin, and true otherwise.


vedreturn()                                                  [procedure]
        This ought,  logically,  to be  the  procedure mapped  onto  the
        RETURN key  in  Ved. Instead  the  procedure is  called  veddocr
        described above.


vedstartwordleft()                                           [procedure]
        Moves the cursor  to the beginning  of the current  word or  the
        beginning of  the  next word  to  the  left if  already  at  the
        beginning of a word or in  a space. * vedatitemstart is used  to
        determine the start.


vedexchangeposition()                                        [procedure]
        Swap current  location  with  top of  ved  position  stack.  See
        vedpositionpush.


vedjumpto(line, col)                                         [procedure]
vedjumpto(struct2)
        Move cursor to  specified location  in Ved  buffer. The  integer
        line and  col  arguments  may  also be  passed  in  a  structure
        struct2, which can be a  vector {^line ^col}, a 2-element  list,
        or any other indexable structure with at least 2 elements.


vedmoveitem() -> item                                        [procedure]
        Return next Pop-11 text item in file, move cursor past it. (This
        procedure, unlike * vedwordright, uses * incharitem.)


vednextline()                                                [procedure]
        Places the cursor at the start of the next line in the file. See
        also vedprevline.


vednextpara()                                                [procedure]
        Places the cursor at  the next start of  a paragraph within  the
        current file. The extent of  a paragraph is determined by  calls
        to vedinparagraph. See also vedprevpara.


vednextparaend()                                             [procedure]
        Places the cursor  at the  next end  of a  paragraph within  the
        current file. The extent of  a paragraph is determined by  calls
        to vedinparagraph. See also vedprevparaend.


vednextscreen()                                              [procedure]
        Displays the  next  screenful  of the  current  file.  See  also
        vedprevscreen.


vednextsent()                                                [procedure]
        Places the cursor at the start of the next sentence in the file.
        Sentences are assumed to finish with one of the characters ".?!"
        (optionally followed  by one  of the  following characters  "]",
        "}", ")", """, or '), followed by a capital letter. Either  this
        or  be  separated   by  blank  lines.   See  also   vedprevsent,
        vednextsentend, and vedprevsentend.


vednextsentend()                                             [procedure]
        Places the  cursor  at  the  next occurrence  of  the  end  of a
        sentence in the  current file.  See vednextsent  for details  of
        what is  considered  to be  the  end  of a  sentence.  See  also
        vedprevsent and vedprevsentend.


vedpositionpush()                                            [procedure]
        Pushes  the  current  cursor  position  onto   vedpositionstack.


vedpushkey()                                                 [procedure]
        Push current  position  onto  vedpositionstack,  truncating  the
        position stack if there are  more than 5 items. Also  displays a
        message. (Usually assigned to a key.)


vedpositionpop()                                             [procedure]
        Restores  the   most  recently   saved  cursor   position   from
        vedpositionstack. Only vedline and vedcolumn are restored.


vedpopkey()                                                  [procedure]
        Like   vedpositionpop,    except    that    vedlineoffset    and
        vedcolumnoffset are also restored,  so that the window  contents
        are the same as when the position was saved. (E.g. if you save a
        position with the procedure starting  at the top of the  screen,
        then when it  is popped the  procedure will again  start at  the
        top.)

        In addition, if the stack contains less than 5 saved  positions,
        the restored position is moved to the back of the stack (instead
        of being discarded).


vedprevline()                                                [procedure]
        Places the cursor at the start of the previous line in the file.
        See also vednextline.


vedprevpara()                                                [procedure]
        Places the cursor at  the previous start  of a paragraph  within
        the current file.  The extent  of a paragraph  is determined  by
        calls to vedinparagraph. See also vednextpara.


vedprevparaend();                                            [procedure]
        Places the cursor at the previous end of a paragraph within  the
        current file. The extent of  a paragraph is determined by  calls
        to vedinparagraph. See also vednextparaend.


vedprevscreen()                                              [procedure]
        Displays the previous  screenful of the  current file. See  also
        vednextscreen.


vedprevsent()                                                [procedure]
        Places the cursor at the previous start of a sentence within the
        current file. See vednextsent for  what is considered to be  the
        end of a sentence. Also see vednextsentend and vedprevsentend.


vedprevsentend()                                             [procedure]
        Places the  cursor  at  the  last occurrence  of  the  end  of a
        sentence in the  current file.  See vednextsent  for details  of
        what is  considered  to be  the  end  of a  sentence.  See  also
        vedprevsent and vednextsentend.


vedscreendown()                                              [procedure]
        Move cursor to bottom of window  or down a window if already  at
        bottom. Changes vedline.


vedscreenleft()                                              [procedure]
        Move cursor to beginning of line. Alters vedcolumn


vedscreenmiddle()                                            [procedure]
        Move  cursor  to  middle  of  screen  on  current  line.  Alters
        vedcolumn


vedscreenright()                                             [procedure]
        Move cursor to right of window. Changes vedcolumn.


vedscreenup()                                                [procedure]
        Move cursor to top of window, or up a window if already at  top.
        (i.e. changes vedline but not vedcolumn)


vedsetcursor()                                               [procedure]
        Put the screen cursor in right  place if current position is  in
        visible window.


vedtableft()                                                 [procedure]
        Move cursor one tab stop left.


vedtabright()                                                [procedure]
        Move cursor one tab stop right.


vedtextleft()                                                [procedure]
        Move to beginning of text on current line.


vedtextright()                                               [procedure]
        Move to right of text on current line.


vedtoperror()                                                [procedure]
        Abort processing, and print 'TOP OF FILE' message.


vedenderror()                                                [procedure]
        Standard end of file error, like vedtoperror.


vedtopfile()                                                 [procedure]
        Move to top of file.


vedwordleft()                                                [procedure]
        Move word to left.  If the Ved cursor  is at the beginning  of a
        line, or more than  one character beyond the  end of a line,  or
        anywhere on an empty  line, this moves the  cursor back to  just
        after the end  of the  last non-empty line.  Otherwise it  moves
        left, using  * vedatitemstart to  determine when  it is  at  the
        beginning of  a text  item. Thereafter  it traverses  any  space
        characters on the  left, until it  is just to  the right of  the
        next text item, or at the beginning of a line. If there are tabs
        in the file each is treated as  a word, and the cursor stops  at
        tab boundaries.  Like  * vedwordright,  the  behaviour  of  this
        procedure can be controlled by redefining * vedchartype. (It  is
        redefined for LISP, for example.)


vedwordright()                                               [procedure]
        Move word right.  This procedure  moves the  Ved cursor  right a
        character at a time, using  * vedatitemend to determine when  it
        has reached a text item boundary.  Unless it is at the end  of a
        line it then traverses any spaces, to reach the beginning of the
        next item. If  invoked at  the end  of a  line, it  goes to  the
        beginning of the next non-empty line, or, if there isn't one, to
        the beginning of the next line. Like * vedwordleft its behaviour
        can be controlled by redefining * vedchartype. If there are  any
        tabs they are treated  as separate words. I.e.  it stops at  tab
        boundaries (unlike * vedmoveitem, which uses the Pop-11  lexical
        analyser, * incharitem).


vedsetlinesize()                                             [procedure]
        Must  be  called   every  time  vedline   is  changed.   Updates
        vvedlinesize.


vedtrimline()                                                [procedure]
        Use this before vedline is  altered, to remove any extra  spaces
        from the right hand end.




-----------------------
7  Ved Input and Output
-----------------------

7.1  Low Level
--------------

From Poplog version 14.1 all input and output in Ved is handled by a set
of redefinable  procedures which  are listed  below. All  Ved input  and
output should operate via these procedures.

The procedures are redefined according to the type of Ved being used: in
XVed, for example,  they send  and receive  data from  the current  XVed
window. (Any  assumptions  about  them  referring  to  poprawdevin   and
poprawdevout, or rawcharin and rawcharout, are incorrect.)

Note that in XVed, when called  from inside vedprocess (as they  usually
are),   vedscr_read_input    and    vedscr_read_ascii    will    suspend
vedprocessproc if no input is waiting.

vedscr_read_input() -> char_or_p                    [procedure variable]
        Read the  next  character  from  the  keyboard.  In  XVed,  this
        procedure can also  return a  procedure to be  executed (e.g  to
        switch files if input is not for the current window).


vedscr_read_ascii() -> char                         [procedure variable]
        Like vedscr_read_input, but is guaranteed to return a character.
        In XVed, input from  windows other than  the current is  blocked
        while waiting for a character.


vedscr_input_waiting() -> int_or_false              [procedure variable]
        Returns an integer count of the number of input items that  have
        yet to be read into Ved from the input source, or false if there
        are none.


vedscr_clear_input()                                [procedure variable]
        Clears the queue of items that have yet to be read from the  Ved
        input source.


vedscr_char_out(char_or_string)                     [procedure variable]
        Writes the character or string to the current screen or window.


vedscr_substring_out(string, n, len)                [procedure variable]
        Writes len characters of string string to the current screen  or
        window, starting at the n-th character.


vedscr_flush_output()                               [procedure variable]
        Writes any outstanding  characters in the  Ved output buffer  to
        the screen.


7.2  Higher Level
-----------------
The following section gives  higher level input/output procedures  which
use the low-level variable procedures outlined in the previous section.

They also use the  list * ved_char_in_stream to  buffer input; this  can
contain characters, strings,  and procedures, and  provides a  mechanism
for simulating Ved input, e.g. for defining macros, abbreviations,  etc.
(Note that when read, a string appearing in ved_char_in_stream will have
its  first   character  returned   and  the   remainder  put   back   on
ved_char_in_stream.)

The procedure  vedinput provides  a convenient  way of  adding items  to
ved_char_in_stream.

In XVed,  when called  from  inside vedprocess  (as they  usually  are),
vedgetinput and vedinascii  will suspend vedprocessproc  if no input  is
waiting.

vedgetinput() -> char_or_p                                   [procedure]
        Returns   the   next   input   character   or   procedure   from
        ved_char_in_stream   if   that   is   non-empty,   or    reads a
        character/procedure with vedscr_read_input otherwise.


vedinascii() -> char                                         [procedure]
        Like vedgetinput, but is guaranteed  to return a character.  Any
        procedures buffered on ved_char_in_stream are discarded, and  if
        ved_char_in_stream   contains   no   characters   or    strings,
        vedscr_read_ascii is  called  to  get a  character  (instead  of
        vedscr_read_input).

        Calling vedscr_read_ascii means that in XVed, input from windows
        other than the current is blocked while waiting for a character.


vedinputwaiting() -> bool                                    [procedure]
        Returns true  if  there  is unprocessed  Ved  input,  i.e.  when
        vedscr_input_waiting    returns    a    non-false    value    or
        ved_char_in_steam is a non-empty list.


vedclearinput()                                              [procedure]
        Writes any  outstanding characters  in  the Ved  output  buffer,
        clears the input buffer and resets ved_char_in_stream to [].


vedinput(item_or_list)                                       [procedure]
        Adds item at  the front of  ved_char_in_stream, or  concatenates
        list to the beginning of it. item (or each item in list) must be
        be a character, string, or procedure.

        (In XVed, this procedure also  calls XptSetXtWakeup, so that  if
        used in an X callback context it will tell Poplog to return from
        processing   X    events    and    allow    Ved    to    process
        ved_char_in_stream.)


vedinkeys(string)                                            [procedure]
        Prints the string on the command  line as a prompt to the  user,
        then reads  in  keys. The  codes  transmitted by  each  key  are
        inserted into  the current  file in  a manner  suitable for  the
        itemiser to build a string containing them. vedinkeys exits when
        the user types three ESCs Used  by VED_DK and VED_DM to read  in
        sequences of key strokes.


vedreadinteger() -> (integer, char)                          [procedure]
        Returns an  integer  (ie  sequence  of  digits)  read  from  the
        keyboard, returns when a non-digit  is typed, the terminator  is
        returned as char.


vedrepeat()                                                  [procedure]
        Reads an integer  (N) from the  keyboard (using  vedreadinteger)
        then reads  a key  sequence  which maps  onto some  action.  The
        action is repeated N times.


vedscreenbell()                                     [procedure variable]
        Ring terminal  bell. Sometimes  just flashes  the screen.  User-
        definable.


ved_get_reply(mess, answer_chars) -> char           [procedure variable]
        Rings the  bell  and  displays  the  message  string  mess  with
        vedputmessage, and  then  calls  vedinascii  to  read  a  single
        character in response (which is always translated to lowercase).

        Only  characters  contained  in  the  string  answer_chars   are
        accepted; any other character typed is ignored (and the bell and
        message are  repeated). When  an  acceptable character  char  is
        typed, this is returned.



7.3  Mapping Input Characters to Procedures
-------------------------------------------
Using the  Ved  character  input tables  (* vednormaltable  etc),  these
procedures map sequences of input characters onto procedures.

vedgetproctable(char_or_string_or_char_rep) -> p_or_undef    [procedure]
        Returns the Ved action procedure p associated with

            (1) a character char  (plus further  input characters  where
                necesssary);

            (2) the sequence of characters in a string string;

            (3) the sequence  of  characters  supplied  by  a  character
                repeater procedure char_rep.

        The characters  are  used  to work  through  the  Ved  character
        tables, starting  from  vednormaltable,  until  a  procedure  or
        "undef" is found. (Each  character is assigned to  ved_last_char
        as it is processed.)  In the char case,  if the tables  indicate
        that  one  or  more  continuation  characters  are  required  to
        interpret char, these are read using vedinascii.

        If no procedure is associated  with the character sequence  then
        the word "undef" is returned.

        See also * vednormaltable, * vedescapetable, * vedquerytable.


vedkeyproc(string) -> p                                      [procedure]
        Returns the procedure associated with the key that transmits the
        control codes given in string. Gives a vederror if no  procedure
        is associated with the characters in string or if more than  one
        procedure is  associated with  the  characters in  string.  Uses
        vedgetproctable.


vedsetkey(string, item)                                      [procedure]
        Alter Ved's character  tables so that  the characters in  string
        are mapped onto item. See HELP * VEDSETKEY for more details.  An
        alternative mechanism that  uses a more  readable syntax and  is
        probably more suitable for non-Pop-11 programmers is the  vedset
        keys construct described in HELP * VEDSET.




--------------------
8  The Ved Main Loop
--------------------

These procedures  control  the  main  processing loop  of  Ved.  In  all
versions of Ved, vedprocess  is run as  the process vedprocessproc;  for
non-XVed, this is done  by vededit and the  process does not exit  until
there are no files remaining (or vedexit is called).

In XVed, however, the  process is suspended whenever  there is no  input
waiting, and  resumed  (via  vedprocess_try_input)  whenever  Ved  input
becomes available while Poplog is in a wait state, e.g. when waiting for
input from an interactive device  (such as a terminal/pipe/mailbox),  or
during a syshibernate.

vedprocess()                                                 [procedure]
        Repeatedly reads in  and processes input  characters and  action
        procedures, using vedprocesschar. It calls vedprocesstrap before
        reading each input item.

        This procedure  constitutes  the  Ved top  level  loop,  and  is
        constructed as a process in vedprocessproc. (It must not be  run
        except as runproc(vedprocessproc).)

        Inside vedprocess,  the  variable vedinvedprocess  is  set  true
        (this is a protected variable and must not be assigned to).  The
        variable vedediting is also set true on entry to vedprocess.


vedprocesschar()                                             [procedure]
        Repeatedly called by vedprocess. Each call reads a character  or
        action  procedure   using  vedgetinput   (and  assigns   it   to
        ved_last_char).

        If  a  character  is  returned,  vedgetproctable  is  called  to
        translate it to an action  procedure (which may involve  reading
        further characters, see * vedgetproctable).

        The action procedure returned by vedgetinput or  vedgetproctable
        is then  executed. (Often,  this  will be  vedinsertvedchar,  to
        insert the last character assigned to ved_last_char.)

        In XVed, the call to vedgetinput etc will suspend vedprocessproc
        if no input is waiting.


vedprocess_try_input()                                       [procedure]
        Except for XVed, this procedure does nothing.

        In XVed, it tests whether vedinputwaiting is true and if so (and
        vedinvedprocess is not already true), it runs vedprocessproc  to
        re-activate the top-level  Ved loop  and deal  with the  waiting
        input  (after  first  ensuring  that  vedprocessproc  is   live,
        constructing a new process if not). If no Ved input is  waiting,
        it just returns.


vedexit(p)                                                   [procedure]
        Exits from  vedprocess (and  in non-XVed,  the call  of  vededit
        which invoked it), then chains to p.

        It ensures that the global variables of all files are updated in
        their file structures. Note  that the command procedure  ved_pop
        is simply defined as

            vedexit(identfn)

        Since in XVed, vedprocessproc is being suspended and resumed all
        the time, the  only effect  of calling  vedexit is  to kill  the
        current vedprocessproc and force vededit or vedprocess_try_input
        to create a new one next time.




------------------------------
9  Inserting and Deleting Text
------------------------------

9.1  Inserting
--------------

These routines are  used to  insert text  into the  file. This  normally
causes the altered text to be displayed  on the screen. The text may  be
either characters  read  from  the  keyboard,  or  strings  supplied  by
commands or procedures. Procedures to  output information on the  status
line are documented separately, in the section dealing with the  command
line. Normally when  Ved is  in its top-level  loop (see  * vedprocess),
ordinary printing  characters  read  in are  simply  inserted  into  the
current Ved buffer (or the command line, if appropriate) at the  current
cursor location. This uses * vedinsertvedchar.

Additional text-insertion  procedures  are  the  "yank"  procedures  for
undoing deletions, e.g. ved_y, ved_yankl, ved_yankw, ved_splice.


vedcharinsert(char)                                          [procedure]
        Inserts  the  character  char  at  the  current  location,   and
        (providing vedstatic is  false), moves  the cursor  to the  next
        column, i.e. adds 1 to vedcolumn.

        char is a  24-bit integer representing  an ASCII character  with
        attributes; note that any attributes (bits  16 - 23) set in  the
        variable vedcharinsert_attr are or'ed into char before inserting
        it. (This also applies to vedinsertstring and vedinsertvedchar.)

        char may also be a pair of the form

            conspair(integer-char, data)

        representing a character with associated data item data. In this
        case, as well as inserting the integer character, the item  data
        will be attached to it in the current Ved buffer line.


veddocr()                                           [procedure variable]
        Normally mapped onto the <RETURN> key. It will normally insert a
        line break (like vedcharinsert(`\n`)) unless either the file  is
        an "immediate  mode" file,  or the  cursor is  currently on  the
        status line.

        If invoked with vedonstatus true  (i.e. currently on command  or
        status line)  this is  equivalent to  vedredocommand  (described
        below).

        If the  current  file is  an  "immediate mode"  file,  then,  if
        vedcrinteractive is false veddocr inserts a line break. If  true
        it sends  the current  line to  the suspended  compiler  process
        associated with the file.

        For more  on  immediate  mode see  * vedsetpop,  and  HELP * IM,
        * IMCSH (Unix), * IMSH (Unix), * IMDCL (VMS).


vedinsertstring(string_or_word)                              [procedure]
vedinsertstring(char1, ..., charN, N)
        In the first form, inserts  the characters of string_or_word  at
        the  current  location.  In  the  second  form,  inserts   the N
        characters char1, ..., charN at the current location.


vedinsertvedchar()                                           [procedure]
        Takes   last   character   read   in   (using   vedinascii)   by
        vedprocesschar  or  vedgetproctable  (stored  in  the   variable
        ved_last_char) and  inserts  it into  the  current file  at  the
        cursor position.


vedlineabove()                                               [procedure]
        Insert blank  line  above  current line.  Use  vedleftmargin  to
        locate cursor.


vedlinebelow()                                               [procedure]
        Insert blank  line  below  current line.  Use  vedleftmargin  to
        locate cursor.


9.2  Deleting
-------------

Besides the procedures listed here see also procedures in REF * VEDCOMMS
e.g. * ved_d and * ved_cut (delete text between two stacked  positions).
Some of the delete  procedures store the last  item deleted in a  global
variable and have corresponding "yank"  procedures to reinsert what  was
last deleted, e.g * ved_y,  * ved_yankl, * ved_yankw, and  * ved_splice.
See HELP * VEDBLOCKS for additional facilities, e.g. * ved_dtb, ved_ytb,
and * vedcutblock (described below).


vedchardelete()                                              [procedure]
        Delete character to left of cursor.


vedclearhead()                                               [procedure]
        Delete current line to left of cursor. Undo with * ved_yankw


vedcleartail()                                               [procedure]
        Delete current line to right of cursor. Undo with * ved_yankw


veddotdelete()                                               [procedure]
        Deletes the character under the cursor.


vedendwordrightdelete()                                      [procedure]
        Deletes all the characters  up to the end  of the current  word,
        using * vedendwordright to determine where to delete to.


vedlinedelete()                                              [procedure]
        Delete current line in buffer. Undo with * ved_yankl


vedspandelete(col_1, col_2, item)                            [procedure]
        Delete  some  text  from  the  current  line,  specifically  the
        characters between col_1 and  col_2 (in buffer coordinates).  If
        the item is not false, then  the text is saved in  vvedworddump,
        which is returned.


vedstartwordleftdelete()                                     [procedure]
        Delete all the characters from the cursor, left to the beginning
        of   the   current   word,   or   the   previous   word,   using
        * vedstartwordleft to determine where to delete to.


vedwordleftdelete()                                          [procedure]
        This procedure uses * vedwordright to move the cursor, and  then
        deletes text between the initial and final cursor locations. The
        deleted text is saved in  * vvedworddump and can be  re-inserted
        using * ved_yankw


vedwordrightdelete()                                         [procedure]
        Exactly like * vedwordleftdelete,  using * vedwordright  instead
        of * vedwordleft to move the cursor. Undo with * ved_yankw




---------------------------
10  The Command/Status Line
---------------------------

These are the procedures  used to handle the  command line, and  command
execution. They handle command line input and interpretation, writing to
the command line, and switching from the command line to the body of the
current file.

veddebug(string)                                             [procedure]
        For debugging Ved procedures. Displays the string on the command
        line, wiggles cursor  at current  location, then  waits for  the
        user to  type a  key. Pressing  <RETURN> causes  the program  to
        continue. Any other key causes a popready break. On return  from
        the  break   it  restores   the  screen.   See   LIB * VEDDEBUG,
        HELP * POPREADY


veddo(string)                                                [procedure]
veddo(string, put_on_status)
        Acts as if string had been typed on command line.  HELP * VEDDO.
        If put_on_status is true and the  string is not the same as  the
        current status line command, then vedputcommand is called to put
        string on the command line.


veddocommand()                                               [procedure]
        Parses and obeys command line.


vedenter()                                                   [procedure]
        This prepares Ved for user commands to be typed in on the status
        line.  Unless   ved_on_status   is  already   true,   it   calls
        vedstatusswitch to  put Ved  into  status buffer  editing  mode,
        setting ved_on_status true,  marking the left  hand edge of  the
        cursor line  in  the current  Ved  buffer, and  switching  Ved's
        global variables to refer to the status buffer.

        It then does vedendfile() to get to  a blank line at the end  of
        the  status  buffer,   leaving  previous  status-line   commands
        accessible via vedcharup().  The cursor is  left visible on  the
        empty command line.

        When the veddocr key (normally  RETURN) is pressed, the  command
        is analysed and obeyed, by veddocommand

        See also vedstatusswitch (below) and HELP * VEDCOMMANDS.


vederror(string)                                    [procedure variable]
        Aborts processing, prints string on the status line and  bleeps.
        This procedure is invoked by Ved  to handle errors for which  it
        would be overkill to call mishap.

        (See also REF * EXCEPTION, HELP * MISHAP.)


vedputcommand(string)                                        [procedure]
vedputcommand(string, at_end)
        Puts string onto the command line (where it can later be  obeyed
        by veddocommand  or  vedredocommand). If  the  optional  boolean
        at_end is true (the default if omitted), a new line is added  at
        the end of  the status line  buffer; otherwise, string  replaces
        the current line.


vedputmessage(string)                               [procedure variable]
        Display message  string on  status  line, unless  vedediting  is
        false. If  outside of  Ved  or there  is  no current  file,  the
        message is printed on standard  output, regardless of the  value
        of vedediting.


vedredocommand()                                             [procedure]
        Executes the command shown on the Ved status line. If  necessary
        it calls vedstatusswitch to ensure that -ved_on_status is  true,
        then it calls a system procedure  to tidy up the line, and  then
        calls veddocommand.


vedrefreshstatus()                                           [procedure]
        Refresh the status line.


vedsetstatus(string, paren, redraw)                          [procedure]
        (For system use.)

        Re-build the status  line with  string as message.  If paren  is
        true, then put  the message  between parentheses.  If redraw  is
        true then redraw  the status  line on  screen (but  if the  true
        value  is  the  word  "undef",  don't  flush  the  output).  See
        * vedputmessage.


vedsetnormalmessage(flush)                          [procedure variable]
        (For system use.)

        Called at the end of every vedprocess loop, this procedure  uses
        vedsetstatus to set the  normal message on  the status line  and
        set the cursor where it should be. The message displayed will be
        (a) empty when on the  status line, (b) vedmessage otherwise  if
        it is not empty. If  vedmessage is empty, the message  displayed
        is vednamestring.

        If flush is true, vedscr_flush_output is called afterwards.


vedstatusswitch()                                            [procedure]
        Switch cursor  from status  line  to Ved  file, or  vice  versa,
        erasing or leaving  a "mark"  at the  left edge  of the  current
        cursor line. It is basically the same as

                not(ved_on_status) -> ved_on_status

        except that cursor line mark is drawn when going onto the status
        line, or erased when coming off it.


vedexpandchars(char) -> p                                     [property]
        A property table associating characters with procedures. Used in
        the expansion  of  command  line  abbreviations,  the  character
        following the occurrence of vedexpandchar  is looked up in  this
        table, and  the  associated  procedure  is  executed.  See  also
        HELP * VEDEXPAND.




-------------------------
11  Text Editor Functions
-------------------------

This  suite  of  procedures  perform  additional  text  related   editor
functions, e.g. case changing.

vedcapword()                                                 [procedure]
        Capitalises the initial letter of  the current word, then  moves
        right to next word.


vedchangecase()                                              [procedure]
        Change chase of current character and move right one.


vedchartype(char) -> char                           [procedure variable]
        Returns a char which typifies  the class of characters of  which
        the given char is  a member. Thus, if  given a-z returns a,  0-9
        returns 0 etc.

        This procedure controls the  behaviour of both  * vedatitemstart
        and * vedatitemend, and can  be redefined to  suit the needs  of
        different programming  languages.  The default  definition  (for
        Pop-11 users) is (approximately):

            define vars vedchartype(char) -> type;
                lvars char, type;
                checkinteger(char, 0, false);
                if char == ` ` then ` `
                elseif locchar(char, 1, '()[]{}",;%.') then `.`
                elseif isalphacode(char) then `a`
                elseif isnumbercode(char) then `0`
                elseif locchar(char, 1, '+-><*=^!#$&~|\@:/?')
                      then `+`
                else    char    ;;; control character, `_`, `'`, ```
                endif
            enddefine;


vedcurrentchar()    -> char                                  [procedure]
char -> vedcurrentchar()
vedcurrentdchar()   -> char                                  [procedure]
char -> vedcurrentdchar()
vedcurrentvedchar() -> char                                  [procedure]
char -> vedcurrentvedchar()
        These procedures return  or update the  character at the  cursor
        position (without moving it).

        The difference between  them is that  vedcurrentchar returns  or
        updates only the character-code (ASCII) part of each  character,
        vedcurrentdchar returns or updates the character and its display
        attributes  (i.e.  a  24-bit  integer),  and   vedcurrentvedchar
        returns or  updates  both the  full  integer character  and  any
        associated data  item (see  Display  Strings and  Vedstrings  in
        REF * STRINGS).

        Thus vedcurrentchar returns an ASCII character,  vedcurrentdchar
        an  ASCII  character  with  attributes,  and   vedcurrentvedchar
        returns an integer character or  pair if there is an  associated
        data item.

        For any of  the updaters, char  may be an  integer character  or
        pair (as for * vedcharinsert above), but only the relevant  part
        is used.


vedcurrentchartype() -> char                                 [procedure]
        Returns a character  which typifies the  class of characters  of
        which the character to the left of the cursor is a member.  Thus
        any number returns `0`, any letter returns `a` etc.

        N.B.  This  procedure  is  misnamed  --  it  should  be   called
        vedlastchartype.


veddecodetabs(string) -> string                              [procedure]
        Remove the extra tabs put  into a string by  vedcharinsert(tab).
        veddecodetabs is controlled by vedindentstep.


vedencodetabs(string) -> string                              [procedure]
        See veddecodetabs.


vedlinestart(string)                                         [procedure]
        True if  string occurs  at beginning  of current  line and  is a
        separate text item (see HELP * issubitem).


vedsetstatic()                                               [procedure]
        Switch static mode on or off. Toggles vedstatic


vedsetwindow()                                               [procedure]
        Make current window fill whole screen, or return to half screen.
        Usually mapped to <ESC> w.


vedswapfiles()                                      [procedure variable]
        Switch cursor  to other  file. Set  it on  screen if  necessary.
        Usually mapped to <ESC> x.


vedthisline() -> string                                      [procedure]
string -> vedthisline()
        Returns or updates the  (string or dstring) string  representing
        the current line.


vedthisstring() -> string                                    [procedure]
        Equivalent to veddecodetabs(vedthisline()).


vedwiggle(line, col)                                         [procedure]
        Put cursor at the given (line, col) location in the buffer,  and
        make it wiggle. The cursor can be made to wiggle on the  command
        line by specifying  line = 0.  The length of  time for which  it
        wiggles is  determined  by  the  variable  vedwiggletimes  which
        defaults to 5, probably far too little for modern terminals  and
        workstations. E.g.  try  35  on  a Sun3/60,  more  on  a  faster
        machine.



------------------------
12  Searching Procedures
------------------------

See REF * VEDSEARCH for a comprehensive overview of the facilities for
searching Ved buffers, and for details of the following procedures:

    * ved_try_search    * ved_check_search
    * ved_set_search    * ved_query_last_search
    * ved_search_or_substitute
    * ved_search        * ved_re_search
    * ved_backsearch    * ved_re_backsearch



----------------------------
13  Program Editor Functions
----------------------------

These procedures handle functions of Ved related to program files.  I.e.
compilation etc.


vedargint(string) -> integer                                 [procedure]
        Returns the  integer  represented  by  the  given  string  (like
        strnumber), or the integer 1 if the string does not  represent a
        valid number. If it represents a number but not an integer, then
        unlike * vedargnum, this produces an error.


vedargnum(string) -> number                                  [procedure]
        Returns  the  number  represented  by  the  given  string  (like
        strnumber), or the integer 1 if the string does not  represent a
        valid number. Compare * vedargint


vedatitemend(n, string, m)                                   [procedure]
        True if location n is a legitimate text item boundary in string,
        treating characters beyond location m as spaces. This is used by
        * vedwordright, * vedendwordright, and * issubitem.

        The behaviour of this  procedure, like * vedatitemstart, can  be
        altered by redefining * vedchartype.


vedatitemstart(n, string, m)                                 [procedure]
        True if location  n is  a legitimate start  for a  text item  in
        string treating characters beyond location m as spaces. This  is
        used by * vedwordleft, * vedstartwordleft, and * issubitem.

        The behaviour of this  procedure, like * vedatitemstart, can  be
        altered by redefining * vedchartype (as is done for LISP).


vedcompilefiles()                                            [procedure]
        Compile all compilable and changed files.


vedcompilevedargument()                                      [procedure]
        Interprets vedargument  as a  fragment of  Pop-11 code.  Assumes
        that the first  character of  vedargument is a  colon, which  it
        removes.


vedconvertword(test_p, conv_p, N_or_string, moveright)       [procedure]
        Applies procedure test_p to each character of the N words to the
        left or right of the cursor, characters for which test_p returns
        true being converted with procedure conv_p.

        N_or_string may  specify the  integer N  directly, or  may  be a
        string such that the  result of applying  strnumber to it  gives
        the integer N.

        The direction  is  specified  by  the  boolean  moveright,  true
        meaning right and false  left. (Note that  if the cursor  starts
        off in the middle of a word, that whole word is the first one.)

        test_p is a procedure of the form

                test_p(CHAR) -> BOOL

        All characters for which it  returns a true result are  replaced
        by the  result of  applying  conv_p to  them, i.e.  conv_p  is a
        procedure of the form

                conv_p(CHAR) -> NEWCHAR


vedconvertline(test_p, conv_p, N_or_string)                  [procedure]
        Applies procedure  test_p  to  each character  of  the  N  lines
        starting from  the current  line,  characters for  which  test_p
        returns true being converted with procedure conv_p.

        N_or_string may  specify the  integer N  directly, or  may  be a
        string such that the  result of applying  strnumber to it  gives
        the integer N.

        test_p and conv_p are the same as for vedconvertword above.


vedconvertrange(test_p, conv_p)                              [procedure]
        Applies procedure test_p to each  character of all lines in  the
        current marked range, characters  for which test_p returns  true
        being converted with procedure conv_p.

        test_p and conv_p are the same as for vedconvertword above.


vedconvertseln(test_p, conv_p)                               [procedure]
        Applies procedure conv_p to each  character in the current  Xved
        selection that  satisfies  the  procedure test_p.  An  error  is
        signalled if the current Ved window is not an Xved window, or if
        it does not  contain a  selection. vedconvertseln  is called  by
        ved_chat to implement the s option.


veddointerrupt()                                             [procedure]
        Abort current processing, flush input and output. Return to  Ved
        top level. The default action when an interrupt occurs.


vedfindpdheader(name, exact) -> line                [procedure variable]
        Searches the  current  file for  the  definition of  the  Pop-11
        procedure named name, which (if exact is true) is the exact name
        of the procedure, or (if exact is false) is some initial part of
        a procedure name. name should be a string or a word. Returns the
        number of the line where  the matching procedure definition  was
        found, or false if a matching definition could not be located.


vedloadline()                                                [procedure]
        Loads current line  without altering the  marked range.  Usually
        mapped to <ESC> d.


vednextitem() -> item                                        [procedure]
        Returns the  next Pop-11  text  item in  the current  file,  but
        leaving the current  cursor unchanged.  (It uses  * vedmoveitem,
        then goes back to the original position.)


vedout(file, returntofile, onscreen, initialise)             [procedure]
                                            ->  char_cons
        For printing into a file. See HELP * VEDOUT.


vedpopexit()                                                 [procedure]
        This procedure  is  run  on  exit from  Poplog,  i.e.  when  the
        procedure * sysexit is called.  sysexit first runs the  variable
        procedure * popexit (which defaults to identfn), and then  calls
        vedpopexit.

        vedpopexit checks if  there are  changed files left  in the  Ved
        buffers, and if appropriate writes them to disk. You can make it
        ask whether to write the files by assigning true to the variable
        * vedalwaysask.


ved_pr_exception(item1, ..., itemN, N,              [procedure variable]
                        mess, idstring, severity)
        Version of * pop_pr_exception used by Ved.


vedrangerepeater(line1, line2) -> char_rep                   [procedure]
        Returns a  character repeater  that  reads characters  from  the
        current file between  line1 and line2  (in buffer  coordinates).
        Compare * vedblockrepeater.


vedrepeater()    -> char                                     [procedure]
veddrepeater()   -> char                                     [procedure]
vedvedrepeater() -> char                                     [procedure]
        These procedures  return the  character  at the  current  cursor
        position, and move the cursor one place forward.

        The difference between them is that vedrepeater returns only the
        character-code (ASCII)  part  of  each  character,  veddrepeater
        returns the character and its display attributes (i.e. a  24-bit
        integer), and  vedvedrepeater  returns  both  the  full  integer
        character and any associated data item (i.e. a pair if there  is
        an associated data item). See Display Strings and Vedstrings  in
        REF * STRINGS.

        N.B. These procedures  set poplastchar (to  the ASCII  character
        only).


vedlinerepeater() -> string                                  [procedure]
        Returns the current line  of the current Ved  file (a string  or
        dstring), and  moves the  cursor to  the beginning  of the  next
        line.  Removes   unnecessary   tabs   from   the   line   (using
        veddecodetabs). Similar to vedrepeater.




---------------------
14  Window Management
---------------------

These procedures are used to  display files in vedbufferlist on  screen,
and to  control  the windows,  ensuring  that the  window  displays  the
section of the file around the cursor.


vedalignscreen()                                             [procedure]
        Refresh screen,  making  sure  current location  is  in  visible
        portion.


vedcheck()                                                   [procedure]
        Ensure current  window includes  cursor position.  If not  shift
        window   and   refresh   screen.   Changes   vedlineoffset   and
        vedcolumnoffset if necessary.


vedchecksize(n_rows, n_cols) -> bool                         [procedure]
        Returns  true   if  the   dimensions   of  the   usable   screen
        (vedscreenlength x vedscreenwidth) are correctly set for a given
        actual screen  size  of (n_rows  x  n_cols). If  this  procedure
        returns  false  you   should  use  vedresize   to  correct   the
        discrepancy.

        This procedure takes account of  the fact that if  vedscreenwrap
        is true, then vedscreenwidth  should be n_cols  - 1, to  prevent
        problems with characters in the final column.


vedcursorset() -> bool                                       [procedure]
        True if  (vedline,  vedcolumn)  defines a  location  in  visible
        window.


vedmidwindow()                                               [procedure]
        Repositions the current line as close as possible to the  middle
        of the window. See also vedtopwindow.


vedfileisonscreen(vedfile_struct_or_string) -> onscreen      [procedure]
        Returns true if the given file structure, or the file  structure
        referred to by the name string, is on screen.

        For terminal  Ved  this  means  the  file  structure  is  either
        vedupperfile or vedlowerfile. For  windowed Ved it merely  means
        the file has an associated window (which note is not necessarily
        open, i.e. could be iconic).

        vedfileisonscreen can therefore  be used to  test whether  there
        are window contents to be updated when changing a file buffer.


vedsetonscreen(vedfile_struct, initarg)             [procedure variable]
        Sets the file represented by vedfile_struct on the screen/window
        (tidying up any previous window), makes it ved_current_file, and
        sets it first in vedbufferlist.

        If vvedgotoplace is an integer, the file is positioned with  the
        cursor at that line  number; if vvedgotoplace  is a string,  the
        cursor is positioned  at the first  line containing that  string
        (note that this mechanism is intended to be used only when a new
        buffer is first displayed).

        After this, initarg is processed:  this may be false, a  message
        string, or a procedure. If a procedure, it is called as

            initarg(redisplay) -> (redisplay, initarg)

        and is expected to return false  or a message string to  replace
        itself. The  redisplay value  is a  boolean saying  whether  the
        window contents are  new and need  redisplaying or not  (initarg
        may change the return value for this if it wishes to.)

        The  resulting  value  of  initarg  then  controls  the  message
        displayed on the status line:

            initarg             message displayed
            -------             -----------------
            non-empty string    initarg

            empty string        empty
            (redisplay false)

            false               Message produced by vedsetnormalmessage
            (redisplay false)

            empty or false      vednamestring concatenated  with  'lines
            (redisplay true)    LINES' where lines is vvedbuffersize

        (Thus the  'vednamestring, lines  LINES' message  is shown  only
        when redisplay  is  true  and  no  other  non-empty  message  is
        supplied.)

        Finally, vedfile_struct is  assigned to vedinputfocus  (although
        note that when this  procedure is called  from vededit, a  false
        setfocus argument to  the latter  causes this  assignment to  be
        undone).


ved_file_change_apply(arg1, ..., argN, changes_p,            [procedure]
                                        vedfile_struct)
        Enables a procedure  changes_p to call  Ved editing routines  to
        change the buffer  of a  file vedfile_struct  without having  to
        worry about  whether the  file has  a window  or not  (and  thus
        whether the window contents needs updating).

        In all cases, changes_p is applied (taking arguments arg1,  ...,
        argN) with ved_current_file locally set to vedfile_struct  (thus
        ved_current_file will be unchanged after the call).

        If the condition

            vedediting and vedfileisonscreen(vedfile_struct)

        is true,  the file  is made  current by  calling  vedsetonscreen
        (unless vedfile_struct is already the current file). Any changes
        made be will then  be correctly reflected  in the window  (after
        which vedsetonscreen is called  to restore the previous  current
        file, if necessary).

        Otherwise, if vedediting  is false  anyway, or the  file has  no
        window, changes_p is applied with vedediting locally set  false.
        Thus Ved  procedures  will  not attempt  to  update  any  window
        contents.


vedscreencooked()                                            [procedure]
        System procedure called by vedscreenreset when Ved exits,  which
        sets the terminal  to it's "normal"  state (with echoing  etc.),
        including re-setting the  numerical keypad,  in preparation  for
        normal printing. Compare vedscreenraw. (User definable)


vedscreenraw()                                      [procedure variable]
        System procedure used to set the terminal into "raw" mode, where
        characters are not echoed, etc. Compare vedscreencooked


vedscreenreset()                                    [procedure variable]
        Prepare to produce  normal printout,  or read  in characters  at
        bottom  of   screen,  in   non   raw  ("cooked")   mode.   Calls
        vedscreencooked.

        Set vedprintingdone true.


vedscrollvert(nlines)                               [procedure variable]
vedscrollup()                                                [procedure]
vedscrolldown()                                              [procedure]
        Given a  signed  integer nlines,  scroll  the text  up  or  down
        abs(nlines), where positive means up (equivalently, window moves
        down) and negative means  down (equivalently, window moves  up).
        vedlineoffset is incremented by nlines.

        vedscrollup is the same  as vedscrollvert(1), and  vedscrolldown
        the same as vedscrollvert(-1).


vedscrollhorz(ncols)                                [procedure variable]
vedscrollleft()                                              [procedure]
vedscrollright()                                             [procedure]
        Given a  signed integer  ncols, scroll  the text  left or  right
        abs(ncols), where  positive  means  left  (equivalently,  window
        moves right),  and negative  means right  (equivalently,  window
        moves left). vedcolumnoffset is incremented by ncols.

        vedscrollleft   is   the    same   as   vedscrollhorz(1),    and
        vedscrollright the same as vedscrollhorz(-1).


vedscrollregion(wtop, wbottom, nlines, buffline)    [procedure variable]
        Scrolls a region of  text on the  screen, without affecting  the
        Ved buffer or any variables. (Typically used to alter the screen
        after some  text has  been  deleted from  or inserted  into  the
        buffer, e.g. using ved_d or ved_y).

        wtop and wbottom  indicate which part  of the window  has to  be
        scrolled, in  window line  numbers.  nlines indicates  how  many
        lines to scroll down (positive) or up (negative).  (Confusingly,
        this is the opposite signing from vedscrollvert.)

        buffline is the number of the line in vedbuffer corresponding to
        window line TOP.


vedtopwindow()                                               [procedure]
        Repositions the current line at the top of the window. See  also
        vedmidwindow.


vedvt52select()                                     [procedure variable]
        Procedure which is  run to distinguish  between vt52  look-alike
        terminals. The default for this is identfn (Ved can't tell).


windows                                                        [library]
        LIB * WINDOWS is a  facility for  using Ved with  more than  two
        visible windows on the same VDU screen or Xterm window, etc.  It
        is most convenient if  the screen displays  more than 30  lines.
        For full details see HELP * WINDOWS




---------------------
15  Screen Management
---------------------

Procedures for outputting text to the screen, inserting or deleting text
on the  screen  or moving  the  cursor on  the  screen. Users  will  not
normally invoke  these procedures  directly  as they  are  automatically
invoked when  the cursor  movement  procedures are  called, or  text  is
inserted or deleted in  the current buffer. Note  that attempts to  move
the screen cursor may be defeated by the fact that the top level loop of
Ved  (* vedprocess)  always  moves  the  cursor  back  to  the  position
corresponding to the current Ved location (* vedline, * vedcolumn).

vedoutascii(char_or_string)                                  [procedure]
        Uses vedscr_char_out  to  output  char  (or  the  characters  in
        string) to  the screen. (Since  vedscr_char_out can  now  take a
        string instead  of a  single character  there is  no longer  any
        reason for using vedoutascii.)


vedscreenchardown()                                 [procedure variable]
        Move cursor down a line (on screen only).


vedscreencharleft()                                 [procedure variable]
        Move cursor left (on screen only).


vedscreencharright()                                [procedure variable]
        Move cursor right (on screen only).


vedscreencharup()                                   [procedure variable]
        Move cursor up (on screen only).


vedscreenclear()                                    [procedure variable]
        Clear the screen completely.


vedscreencleartail()                                [procedure variable]
        Delete line to right of cursor (on screen only).


vedscreendeletechar()                               [procedure variable]
        Delete current character (on screen only).


vedscreendeleteline()                               [procedure variable]
        Delete current line (on screen only).


vedscreenescape(char_or_string_or_p)                         [procedure]
        If the argument is a procedure then apply it, otherwise,  output
        vedescape, followed by CHAR, or the characters of STRING.  (This
        procedure is now mostly replaced by vedscreencontrol).


vedscreenflush()                                             [procedure]
        Synonym for vedscr_flush_output. To be withdrawn.


vedscreeninsertchar(char)                           [procedure variable]
        Insert char at the current cursor position (on screen only).


vedscreeninsertline(n)                              [procedure variable]
        Insert line (on screen only) below screen line n.


vedscreenoutput(char)                                        [procedure]
        Outputs the character char to the screen, where char is a 24-bit
        integer in the form

              23            16 15            8 7               0
             ---------------------------------------------------
             |   Attributes   |       0       | Character Code |
             ---------------------------------------------------

        The general action of vedscreenoutput is to

            #   Strip off the attribute part  of char, and assign it  to
                vedscreencharmode  to   set   the   display   attributes
                appropriately;

            #   Give the remaining  part of char  to vedscr_char_out  to
                display it on the screen.

        This general  behaviour is  modified  in the  following  special
        cases:

            #   If the character-code part  of char is  a tab (code  9),
                replace it with a space.

            #   If the character-code part of char is any other  control
                character (i.e.  is  <  16:20),  then  replace  it  with
                vedscreencontrolmark  (with  the  original   character's
                attributes   or'ed   in   to   any   already   set    on
                vedscreencontrolmark).

            #   If the character-code part of char is a 'special  space'
                character then  replace  it  with it  with  its  display
                character  (with  the  original  character's  attributes
                or'ed in to any already  set on the display  character).
                See Special Spaces in this file.

            #   If the character-code  part now lies  between 16:81  and
                16:9D inclusive, then this is (or may be) a Ved standard
                graphics character, and vedscreengraphtrans is called to
                perform  an  appropriate  translation.  This   procedure
                returns the translated  character and  a boolean  saying
                whether to output it in graphics mode; if the latter  is
                true, VEDCMODE_GRAPHIC  is set  in  the value  given  to
                vedscreencharmode before sending the character out.

            #   If (after any translations) the character-code part is a
                space (code 32), any attributes that are not significant
                on whitespace (e.g. bold or alternate font) are cleared.

        In addition, vedscreencolumn is  incremented by 1 after  sending
        out the character.

        See INCLUDE * VEDSCREENDEFS  for  definitions of  the  character
        attribute bits and VEDCMODE_GRAPHIC.

        (Note that  char may  also be  a  character-with-associated-data
        pair, as for vedcharinsert etc. The data part is ignored  unless
        ved_on_status is true, in which case the data is embedded on the
        character in vedstatusline.)


vedscreenovermode()                                          [procedure]
        Set the terminal into  "overwriting" mode (opposite of  "insert"
        mode).


vedscreenpulldown(n)                                [procedure variable]
        Pull text down window  above window line  n. (Screen only,  i.e.
        leave Ved buffer unchanged.)


vedscreenpullup(n)                                  [procedure variable]
        Pull text up window below window line n. (Screen only).


vedscreenpushdown(n)                                [procedure variable]
        Push text down window below window line n. (Screen only)


vedscreenpushup(n)                                  [procedure variable]
        Push text up window above window line n. (Screen only)


vedscreenscrollregiondown(wline_1, wline_2)         [procedure variable]
        Scroll text down between the (window) lines wline_1 and wline_2.
        (Affects screen only)


vedscreenscrollregionup(wline_1, wline_2)           [procedure variable]
        Scroll text up between the  (window) lines wline_1 and  wline_2.
        (Affects screen only)


vedvt100screeninteger(int)                                   [procedure]
        Outputs the given  integer in decimal  form (for sending  escape
        sequences to a vt100).


vedwindowpoint(wline, wcolumn)                               [procedure]
        Move cursor (on  screen only)  to location  (wline, wcolumn)  in
        window coordinates. Status line =  1. (Does not alter  * vedline
        or * vedcolumn.




--------------------------
16  Ved Special Characters
--------------------------

16.1  Graphics Characters
-------------------------
From Poplog 14.11,  Ved defines  a standard  set of  codes to  represent
various graphics  characters  that are  not  available in  the  ordinary
character set.  In particular,  these include  a set  of characters  for
drawing lines and line junctions.

The Pop-11  itemiser  allows  'backslash'  sequences  to  specify  these
characters in  strings  and character  constants,  as shown  below  (see
REF * ITEMISE for more  details). You can  also insert these  characters
directly into a file by

        <ENTER> ic seq

with the backslash omitted (see REF * ved_ic):

        Seq     Name                             Default display
        ---     ----                             ---------------
        \Gle    left end of horizontal line            -
        \Gre    right end of horizontal line           -
        \Gte    top end of vertical line               |
        \Gbe    bottom end of vertical line            |

        \Gtl    top left corner junction               -
        \Gtr    top right corner junction              -
        \Gbl    bottom left corner junction            -
        \Gbr    bottom right corner junction           -

        \Glt    left T-junction                        |
        \Grt    right T-junction                       |
        \Gtt    top T-junction                         -
        \Gbt    bottom T-junction                      -

        \G-     full horizontal line                   -
        \G|     full vertical line                     |
        \G+     crossed full horiz/vert lines          +

        \Go     degree sign                            o
        \G#     diamond                                #
        \G.     centred dot                            .

These characters are translated  to an appropriate  form for the  screen
being used by the terminal-dependent procedure vedscreengraphtrans  (see
REF * VEDTERMINALS), which  is called  by vedscreenoutput  when  given a
graphics character.

Some (old)  terminals  and some  other  displays (e.g.  the  normal  Sun
screen), do not support graphic characters at all, and some support  the
line-drawing  characters  but  not  the  others.  Thus  each  of   these
characters has an ordinary character defined as its default  replacement
(the rightmost column in the table above).

(However, note  that  those screens  which  do support  display  of  the
line-drawing characters do  NOT support the  half-line 'end'  characters
Gle, Gre,  Gte and  Gbe; these  are therefore  always displayed  as  the
corresponding full-line characters G- or G|. The reason for representing
the 'end' characters as separate codes is to make it easy for facilities
like veddrawline (see below) to  produce the correct combined  character
when 'overdrawing' one character on another.)

The procedure vednographics assigns  to vedscreengraphtrans a  procedure
which just displays all graphics characters as their default.

This is also the way in which the characters will display in a Ved  file
when printed  out. When  written  to a  file,  a graphics  character  is
represented as a special control sequence whose only printing  character
is the corresponding  default character (for  example, G- translates  to
Ctrl-R followed by `-`).


vednographics()                                     [procedure variable]
        Replaces vedscreengraphtrans with  a procedure which  translates
        the  Ved  standard  graphics  characters  to  ordinary  printing
        characters when output to the screen (as described above).


veddrawline(col1, line1, col2, line2)                        [procedure]
veddrawline(point1, point2)
        This procedure draws a line between the points (col1, line1) and
        (col2,  line2)  in  the  current   Ved  buffer,  using  the   15
        line-drawing graphics characters described above.

        The 4 coordinates  may be specified  either as separate  integer
        arguments (first form),  or as  2 two-element  lists point1  and
        point2 (second form), where

                point1 = [^col1 ^line1]
                point2 = [^col2 ^line2]

        The line can only be horizontal or vertical (which means it must
        be that either line1 = line2 or col1 = col2).

        The line  is  notionally  'drawn' between  the  centres  of  the
        character  cells  specified  by  the  coordinates.  That   is, a
        horizontal line is drawn as the graphics characters

                 Gle G- ... G- Gre

        etc, and a vertical line as

                        Gte
                        G|
                        .
                        .
                        .
                        G|
                        Gbe

        However, the line is also superimposed on any existing lines  in
        the buffer, i.e.  the characters  of the new  line are  combined
        with any existing line-graphics characters already in the buffer
        to form the appropriate composite line or junction.

        (Note  in  this  respect  that  the  15  line-drawing   graphics
        characters are all built up by superimposing combinations of the
        characters Gle, Gre, Gte and Gbe  (e.g. G- is Gre combined  with
        Gle), and that the characters are encoded in such a way that the
        superimposition  of  any  two  is  got  by  simply  taking   the
        bitwise-or of their codes. E.g.

            G-   = Gre || Gle
            Gtl  = Gte || Gle
            Gtt  = G-  || Gte

        etc.)

        Alternatively, if  the  variable rubout  is  true, the  line  is
        erased instead of being drawn. Any existing graphics  characters
        on the  track of  the  line are  replaced with  the  appropriate
        characters representing the line removed.


drawline(col1, line1, col2, line2)                  [procedure variable]
drawline(point1, point2)
        This  variable  procedure   is  used  by   facilities  such   as
        LIB * SHOWTREE to draw lines.  Its default value is  veddrawline
        to draw  lines in  the Ved  buffer, but  if required  it can  be
        redefined to  produce line-drawing  output in  other forms.  The
        arguments are the same as for veddrawline above.

        (Note that drawline is not autoloadable, so

            uses drawline;

        is required).


rubout -> bool                                                [variable]
bool -> rubout
        This boolean controls whether the drawline procedure should  rub
        out  lines  (true)  as  opposed  to  drawing  them  (false).  It
        therefore affects the behaviour of veddrawline.


16.2  Special Spaces Etc
------------------------
In addition to the graphics characters described above, Ved also defines
several kinds of special space character and a special newline.

These codes (together  with the ISO  Latin 'no-break' space  character),
can also be represented by  'backslash' sequences in Pop-11 strings  and
character constants (and inserted into a file by

        <ENTER> ic seq

with the backslash omitted).

To allow the special space characters in a file to be made visible  when
required, each has  a corresponding variable  which contains the  actual
character (possibly  plus  attributes)  that  the  character  should  be
displayed as:

        Seq     Name                         Displayed As
        ---     ----                         ------------
        \Ss     Ved no-break space           vedscreennobreakspacemark
        \Sn     ISO Latin no-break space     vedscreennobreakspacemark
        \Sf     format-control space         vedscreenformatspacemark
        \Sp     prompt-marker space          vedscreenpromptspacemark
        \St     trailing space               vedscreentrailspacemark
        \Sh     Ved hair space               vedscreenhairspacemark
        \Nt     trailing newline             vedscreentrailnewlinemark

Except for  vedscreentrailspacemark and  vedscreentrailnewlinemark,  the
above variables all default to an ordinary space. They may be set to any
appropriate display  character (normally  done  with vedset  chars,  see
HELP * VEDSET).

(The Ved command <ENTER>  dssp causes all the  above to be displayed  as
visible characters in the current file only. See REF * ved_dssp.)

No-break Spaces
    These characters can  be used  for inter-word  spacing to  prevent a
    sequence of words being split  across lines when text is  justified,
    etc.

    Written to a file, the Ved character \Ss is represented by a special
    control sequence whose only printing  character is a space (i.e.  it
    will print as a space). \Sn, on the other hand, is the standard  ISO
    Latin no-break space  code (16:A0) and  is written to  a file as  an
    ordinary character (and  will therefore not  necessarily print  as a
    space, although it may on some printers).

Format-control Space
    This character is used in  Poplog documentation files to mark  lines
    that must not be reformatted  when run through the  manual-producing
    program. It is written  to a file as  a control sequence whose  only
    printing character is a space.

Prompt-marker Space
    The 'prompt-marker' space is the character in * vvedpromptchar  when
    in immediate mode, used  to delineate the end  of the prompt. It  is
    also used in place of  a format-control space on lines  representing
    program code examples. It is written to a file as a control sequence
    whose only printing character is a space.

Trailing Space
    A 'trailing space' character allows spaces  at the end of a line  to
    be written  to,  or  read  from,  a  file.  Normally,  Ved  discards
    end-of-line spaces while editing, or  when writing a file.  However,
    inserting a 'trailing space'  as the last character  on a line  will
    prevent this, because  (a) Ved editing  operations will preserve  it
    intact, and  (b)  when  a  file is  written,  a  trailing  space  is
    translated to an ordinary space character.

    When a file is  read in with vedreadintrailspaces  true, a space  at
    end of line is translated to  a trailing space. This preserves  both
    that  character   and   any   other   spaces   preceding   it.   (If
    vedreadintrailspaces is false -- the default -- trailing spaces  are
    stripped from input lines.)

    On output to the screen, a trailing space character is displayed  as
    the character  in the  variable vedscreentrailspacemark  (normally a
    bold `S` in inverse video).

Ved hair space
    In variable-width  mode in  XVed  this character  displays as  a  1-
    pixel-wide space. Otherwise,  it displays  as the  character in  the
    variable vedscreenhairspacemark  (normally  a bold  `H`  in  inverse
    video).

Trailing Newline
    A 'trailing  newline'  character similarily  allows  trailing  blank
    lines to be written or  read at end-of-file. Normally, Ved  discards
    end-of-file blank  lines  while editing,  or  when writing  a  file.
    However, making  the  last  such line  contain  a  single  'trailing
    newline' will prevent  this, since (a)  Ved editing operations  will
    preserve it  intact, and  (b) when  a file  is written,  a  trailing
    newline is output as no character (the line it represents will  have
    an ordinary newline added, like any other line).

    When a file is read in with vedreadintrailspaces true, a blank  line
    at end-of-file is translated  to a line  containing just a  trailing
    newline. This preserves  both that  line and any  other blank  lines
    preceding it. (If  vedreadintrailspaces is false  -- the default  --
    trailing blank lines are stripped from input files.)

    On output to the screen,  a trailing newline character is  displayed
    as the character in the variable vedscreentrailnewlinemark (normally
    a bold `N` in inverse video).




-------------------------------------------
17  Ved-Buffer Devices and "Immediate Mode"
-------------------------------------------

Ved-buffer devices are  pseudo (or 'user')  devices which enable  device
input and output to  be performed on Ved  buffers. They are  constructed
using consveddevice  for a  given  filename. As  with those  created  by
sysopen etc, Ved devices may be  input only, output only, or both  input
and output. The first time such a device is used, the corresponding  Ved
buffer is set up if it doesn't already exist.

Ved devices are the basis  of the "immediate mode" facilities  described
in  HELP * IM.  These  work  by  calling  vedsetpop,  which  creates  an
input/output Ved  device  and  assigns  it  to  the  standard  variables
pop_charin_device,  pop_charout_device   and  pop_charerr_device.   Thus
output to charout  and input from  charin are redirected  to/from a  Ved
buffer.

When output is sent to a Ved device, characters written to it are simply
inserted into the buffer,  either at the current  position or at end  of
file (this can be selected when the device is created).

However, when input  is requested  from a  Ved device,  the sequence  of
events is somewhat more complicated:

The basic idea is that input  through Ved buffers should be  user-driven
rather than program-driven. That is,  rather than have the whole  system
hang up waiting for input when a program asks for it, the program should
instead 'suspend', and control should return to the top-level Ved  loop.
The user is then back in ordinary  editing mode, and can decide when  to
supply input to the program.

To effect this scheme, Ved devices use the Poplog process mechanism (see
REF * PROCESS). When input is first requested from a device, the program
asking for it  is turned into  a process using  consproc_to (where  'the
program' in this context means all procedure calls inside the  top-level
Ved loop). This  process is then  suspended, and added  to a  per-buffer
list of processes waiting for input from that buffer.

The per-buffer list of  processes is held  in the variable  vedprocwait.
When this is  non-empty for  a buffer, it  causes the  behaviour of  two
things to change:

    (a)  typing <RETURN> in the  buffer (i.e. inserting a  newline  with
         vedcharinsert, which causes veddocr to be called), and

    (b)  loading a marked  range with ved_lmr.

In both cases, the waiting process (that is, the first one on the  list)
is removed from vedprocwait and run (with runproc).

When run, input text  is passed to  the process, to  be returned as  the
result of reading  the Ved device.  For (a)  this is the  line on  which
<RETURN> was typed, while for (b) it  is the whole of the marked  range.
(In both cases, the input text is  also copied to the end of the  buffer
if it is not already there.)

Subsequent reads  on the  device will  then return  any remaining  input
text, and when this is exhausted, the process will suspend again and  be
put back on vedprocwait. Each time the process suspends, it prompts  for
input by writing a prompt string into the buffer. (The current value  of
popprompt is  used  for  this,  but with  a  special  character,  a  Ved
prompt-marker space,  added at  the  end to  enable Ved  to  distinguish
prompts in  buffers  from other  text.  While a  file's  vedprocwait  is
non-empty, the variable * vvedpromptchar is also set to this  character,
causing various editing operations to treat the character specially.)

In  addition,   the  buffer's   status  line   displays  the   character
vedscreenstatusinputmark (normally `I`) to the  left of the line  number
whenever there are processes waiting for input.

The input  stream  for  a  process can  be  terminated  by  calling  the
procedure ved_end_im. This can be done either as a Ved command  (<ENTER>
end_im), or in the default Ved  key bindings by typing the sequence  ESC
Ctrl-Z. It causes  the first waiting  process on vedprocwait  to be  run
with 'end of file' as input.


consveddevice(filename, access_mode, insert_at_eof) -> dev   [procedure]
        Constructs a Ved-buffer device dev for a file named filename.

        Permissible values for the integer  access_mode are the same  as
        for sysopen, i.e.

                0   Read only
                1   Write only
                2   Read and Write

        insert_at_eof is  a  boolean that  says  whether output  to  the
        device should be inserted at the end of the buffer (true) or  at
        the current position in the buffer (false). For an input device,
        this also affects where input prompts are put.

        The behaviour of a Ved device when read or written is  described
        in the introduction to this section.

        Note that a  Ved device  is a type  of pseudo  or 'user'  device
        produced using  consdevice. It  is classified  as a  'terminal',
        i.e. systrmdev will return true for it; its device_full_name  is
        the full pathname of the Ved file.


isveddevice(item) -> bool                                    [procedure]
        Returns true  if item  is a  device produced  by  consveddevice,
        false otherwise.


vedprocswaiting() -> bool                                    [procedure]
        As described in the introduction  to this section, the  variable
        vedprocwait contains a list  of suspended processes waiting  for
        Ved-buffer device  input from  the  current buffer.  (Each  list
        entry is a vector containing the actual process record and  some
        associated data.)

        However, vedprocwait  being non-empty  does not  guarantee  that
        there are actually live processes waiting for input, since  some
        of  them  may  have  died   (due  to  having  mishap'ed,   etc).
        vedprocswaiting is therefore provided:  it returns true only  if
        the vedprocwait  list contains  at least  one entry  for a  live
        process.

        Both   ved_lmr    and    veddocr   behave    differently    when
        vedprocswaiting() is true: instead of their normal action,  they
        both run the (first) waiting  process, supplying it with  input.
        For ved_lmr, the input is  the whole marked range; for  veddocr,
        it is the  current line.  (However, note that  for veddocr  this
        behaviour is  dependent on  the boolean  vedcrinteractive  being
        true -- otherwise, it behaves as normal.)


vedsetpop()                                                  [procedure]
        This procedure starts a compiler  process which will take  input
        from, and send output to, the current Ved buffer.

        It does  this  simply  by creating  an  input/output  Ved-buffer
        device for the current file with consveddevice, and assigning it
        locally  to  the   standard  I/O  variables   pop_charin_device,
        pop_charout_device and pop_charerr_device.

        It then calls pop_setpop_compiler to begin compilation with  the
        compiler for  the  current  subsystem given  in  subsystem  (see
        REF * pop_setpop_compiler).  As   described  above,   when   the
        compiler tries  to read  input from  charin, the  Ved device  in
        pop_charin_device  will  turn  all  procedure  calls  upto   and
        including vedsetpop into a process, suspend it, and place it  on
        vedprocwait.

        Input can then be supplied to the process in the ways  described
        above, i.e by typing <RETURN>  on a buffer line, or  'loading' a
        marked range with ved_lmr.

        Apart from  its  interaction  with  the  Ved  device  mechanism,
        vedsetpop is intended to behave  like setpop (for more  details,
        see REF * SYSTEM). In particular, any attempt to exit abnormally
        through vedsetpop is trapped, and compilation is restarted. Thus
        calling setpop inside vedsetpop only  resets to the latter.  (To
        exit abnormally from inside a  vedsetpop you must call  sysexit;
        this  works  because  vedsetpop  locally  redefines  popexit  to
        perform a special untrapped exitfrom(vedsetpop).)

        vedsetpop also sets  pop_charin_escapes locally to  [], so  that
        the characters $, % and ! at the beginning of an input line will
        not spawn operating-system child processes.


ved_chario_file -> filename_or_false                   [active variable]
filename_or_false -> ved_chario_file
        This active  variable  enables  input from  and  output  to  the
        standard devices

            # pop_charin_device
            # pop_charout_device
            # pop_charerr_device

        to be redirected to a Ved buffer while inside Ved.

        Assigning a string filename to ved_chario_file will cause Ved to
        create a  Ved-buffer  device  for filename  and  set  the  above
        variables locally to that device inside vedprocess. If  filename
        is false, input/output will be  restored to the devices as  they
        are outside of vedprocess.

        If ved_chario_file is assigned to  outside of Ved (i.e.  outside
        of vedprocess),  it  will  have  no effect  until  Ved  is  next
        (re)entered.

        Note that inside  a vedsetpop,  the Ved device  created by  that
        will  locally  override  the   ved_chario_file  one.  That   is,
        assigning to ved_chario_file does not affect input and output in
        "immediate mode"  files,  only that  performed  as a  result  of
        executing Ved commands (although the  same file can be used  for
        both purposes).


vedimshell(ved_file_p)                                       [procedure]
        This procedure  initiates  an  operating-system  immediate  mode
        process, and is used by ved_imcsh, ved_imsh (Unix) and ved_imdcl
        (VMS).

        ved_file_p is a procedure to get an appropriate Ved file and set
        the file's subsystem value  to the name  of the subsystem  whose
        compiler  is  to  be  run.  (E.g.  ved_cshfile,  ved_shfile,  or
        ved_dclfile, which respectively load

            # LIB * CSH_SUBSYSTEM
            # LIB * SH_SUBSYSTEM
            # LIB * DCL_SUBSYSTEM

        and set subsystem to "csh", "sh", or "dcl".)

        ved_file_p  is  called  after  adding  to   ved_char_in_stream a
        procedure which will begin the immediate mode process by calling
        vedsetpop.

        See Immediate Mode Commands in REF * VEDCOMMS.




----------------
18  Marked Range
----------------

The marked range is a facility to specify particular sections of a  file
for manipulation by certain editor functions. These procedures are  used
to set, display and remove the marked range.


vedmarklo()                                                  [procedure]
        Make current line start of marked range.


vedmarkhi()                                                  [procedure]
        Make current line end of marked range.


vedmarkfind()                                                [procedure]
        Move cursor to the beginning of the marked range.


vedendrange()                                                [procedure]
        Move cursor to the end of the marked range.


vedmarked(line) -> char_or_false                             [procedure]
        Returns false if line in the buffer is not in the marked  range.
        If it  is,  returns  vedscreenmark  if  vvedmarkprops  is  true,
        otherwise space character `\s`. See HELP * MARK.


vedmarkpush()                                                [procedure]
        Used for temporarily altering the position, or visibility of the
        marked range.  Saves vvedmarkhi,  vvedmarklo, vvedmarkprops  and
        vvedscreenmark on a stack of marked ranges.

        This stack is local  to the current file,  i.e. is saved in  the
        Ved file structure.  (The `status  line' file also  has its  own
        stack.) Compare vedmarkpop.


vedmarkpop()                                                 [procedure]
        Pops the top  item off  the stack  of marked  ranges created  by
        vedmarkpush, resetting the  marked range  and vvedmarkprops  and
        remarking the screen if necessary.


vedmarkset(line, char)                                       [procedure]
        Displays the character char (on screen only) at the left of  the
        line numbered line in the buffer. Used for marking ranges.  (See
        HELP * MARK).


vedrefreshrange(line_1, line_2, mark_flag)                   [procedure]
        Redraw buffer lines line_1 to line_2 of the current file, if any
        appear on the screen. If mark_flag is true, mark lines, if false
        don't, if "undef" mark lines between vvedmarklo and vvedmarkhi.


vedmarkparagraph()                                           [procedure]
        Marks  the  paragraph  surrounding  the  current  line,  or  the
        preceding paragraph  if  the  current  line  is  not  part  of a
        paragraph. The extent of the paragraph is determined by calls to
        vedinparagraph.


ved_mark_named_range(range_name)                             [procedure]
        Marks a named range in  the current file, where range_name  is a
        word. range_name is  looked up  in vedmarkclasses,  which is  an
        association list of alternating names and marking procedures, ie

            [<name> <marking procedure> ... ]

        If name  is  found  in vedmarkclasses,  then  the  corresponding
        procedure is  run,  otherwise  the  error  'unknown  mark  name'
        results.

        By default, vedmarkclasses  contains procedures associated  with
        the following range names:

            Name            Procedure Action
            ----            ----------------

            "start"         Mark current line as start of range (just
            "lo"            runs vedmarklo).

            "end"           Mark current line as end of range (just runs
            "hi"            vedmarkhi).

            "line"          Mark the current line (runs vedmarklo
                            followed by vedmarkhi).

            "procedure"     Mark the current procedure (runs ved_mcp).

            "paragraph"     Mark the current paragraph (uses
                            vedmarkparagraph).

            "tostartfile"   Mark from first line of file to current
                            marked range end (runs ved_mbf).

            "toendfile"     Mark from current marked range start to last
                            line of file (runs ved_mef).

            "window"        Mark all lines in the current window.

            "file"          Mark whole file from first line to last
                            (runs ved_mbe).

        Note  that   the   command  '<ENTER>   mark   range_name'   runs
        ved_mark_named_range on the given argument.




-------------------------
19  Embedded Text Actions
-------------------------

As described in the  section Ved Buffers above,  any character in a  Ved
buffer may have an embedded data item associated with it. Together  with
the 'active' character  attribute, this  facility is  used to  implement
embedded text  actions,  i.e.  actions  that can  be  fired  off  by  an
appropriate mouse  or keyboard  event such  as clicking  on text.  Among
other things, text actions can be  used to implement hot links to  other
documents.


19.1  Constructing Text Actions
-------------------------------
Text actions  are built  as follows:  First, the  textual extent  of  an
action is  delineated  as  an  active segment,  that  is,  a  contiguous
sequence of characters in  a line all having  the active attribute  (any
other attributes the characters  may have are  irrelevant). This can  be
done (for example) with <ENTER> chat (see REF * ved_chat).

The action to execute  is then attached to  the segment by embedding  an
item on its first non-whitespace character:

                      - active segment  -
      ---------------------------------------------------
      | | | | | | | | |A|A|A|A|A|A|A|A|A| | | | | | | | |
      ---------------------------------------------------
                         ^
                         Action item attached to
                         1st non-whitespace character

Given a  line  and column  number  pointing anywhere  inside  an  active
segment, this  construction  allows  the  associated  data  item  to  be
retrieved (by the procedure ved_text_action_data, see below).

A special feature (allowing  text actions to extend  over more than  one
line), is  that  the  associated  item may  be  an  empty  string  (e.g.
nullstring). This marks the segment as a continuation of a previous one,
and causes  ved_text_action_data to  search  backwards through  the  Ved
buffer for  a preceding  segment, providing  this is  separated only  by
whitespace (spaces, tabs or newlines)  from the original. The  preceding
segment may itself be a continuation of another one, and so on.

(Note that various Ved editing functions deal automatically with  active
continuation markers. E.g. if <ENTER> chat is applied to a marked  range
or XVed selection that extends over  more than one line, and the  active
attribute is being added, then nullstring continuation markers are added
where necessary. Similarily, splitting an active segment by  inserting a
line break will  add a continuation  marker, and deleting  a newline  to
join two lines will remove  one where appropriate. The procedures  ved_j
and ved_jj also maintain the integrity of text actions.)

After creating an active segment, the command

    <ENTER> tact

can be used to attach an  action to it (see * ved_tact). Normally,  this
will be a string command suitable for execution by  * ved_do_text_action
(described in the next section).

You can also create text  actions directly inside Pop-11 quoted  strings
(see REF * ITEMISE). For  example, using the  'character input'  command
supported by  ved_do_text_action,  quoted  strings  can  have  temporary
character   input   'buttons'   in   messages   displayed   (e.g)   with
vedputmessage or ved_get_reply. Thus

    ved_get_reply(
     '\{1A} \[+u'>y']yes \[]  \[+u'>n']no \[]  \[+u'>c']continue \[] ',
     'ync');

will display three inverse video buttons

         yes   no   continue

which can be  clicked on  in XVed  to supply  the appropriate  character
response.

(Another possibility is to  use * vedputcommand to  put a quoted  string
containing active buttons on the status line, each with a different  Ved
command attached.)



19.2  Standard Text Actions
---------------------------
The procedure  ved_do_text_action  implements  a standard  set  of  text
actions. When  called  outside  of  a text  action,  it  also  processes
cross-references  in  Poplog  documentation   and  library  files   (see
HELP * VEDGETSYSFILE).

It is called in the following situations:

      # To execute  an  action,  or get  a  documentation  file,  by
        vedgetsysfile (usually mapped to <ESC> h);

      # To execute an action,  or get a  documentation file from  an
        active segment of text, by vedmouse__do_text_action in  XVed
        (mapped to a mouse button click);

      # To display an action in XVed when the mouse pointer is moved
        into an active segment of text (any such display is  cleared
        when the pointer is moved out of the segment).

For ved_do_text_action, the item embedded in  a text action must be  one
of the following:

    (1) A (non-empty) string (representing  either a Ved command  or
        character input);

    (2) A procedure (or a pair conspair(procedure, string));

    (3) A word, which dereferences with * recursive_valof to  either
        (1) or (2).

For (1), the string  consists of a command,  preceded by optional  flags
and followed by an optional comment field:

        [ (flags) ]  command  [ ;;;comment ]

The command part is  any valid Ved command,  or the special  'command' >
(greater than  sign).  The  latter  form  when  executed  adds  all  the
characters following the  > as  input to  ved_char_in_stream (note  that
there cannot be a comment field in this case).

If present, flags is a parenthesised sequence of the following letters:

        Letter  Meaning
        -----   -------
          S     Set the text cursor (i.e. vedline and vedcolumn) to  the
          L     position of  the  text  action's  embedded  data  before
                executing the command. For L, this is done only locally,
                i.e. vedline and vedcolumn are restored after execution.
                The default is to leave the text cursor alone.

          M     XVed display mode optionally  displays a message on  the
          N     status line (with  vedputmessage). The  default for  Ved
                commands is to display  comment if present, and  command
                otherwise; N means  no message. For  procedure/character
                input, the default is no message: M can be used to force
                a message (which for character  input will be the  whole
                input string starting with >).

          i     In XVed display  mode, highlight the  active segment  by
          b     (i) inverting its foreground and background colours, (b)
          p     drawing a  box around  it, and  (p) changing  the  mouse
                pointer to pointer2shape. Any  combination of these  can
                be used; when none are  specified, the default is p  for
                Ved commands and i for procedure/character input.

A procedure action  (case (2)) may  also supply the  optional flags  and
comment fields via a pair whose front is the procedure and whose back is
a string containing only  those fields. Note that  (as described in  Ved
File Representation:  Embedded Strings  &  Words above),  only  embedded
string/word data can actually be written to Ved files; hence case (2) is
directly usable only  by programs  that create  temporary buffers  which
will not be written to disk.


ved_do_text_action(wline, wcol, select, mode)       [procedure variable]
                                        -> result
        This procedure processes standard text actions, as well as cross
        references in Poplog documentation and library files.

        The arguments  wline and  wcol specify  a text  position in  the
        current Ved window where  (e.g) the mouse has  been moved to  or
        clicked -- that is, a line and column in window coordinates (see
        Note on Line/Column Coordinates above).  if wline = 1, the  text
        in vedstatusline  is  examined  (not the  status  buffer  line),
        otherwise the corresponding Ved buffer line.

        The procedure  first  calls  ved_text_action_data  on  the  text
        position to  see  if  it  is within  a  text  action  having  an
        associated action  item;  failing  this, the  text  position  is
        examined to see if it  lies in a Poplog documentation  reference
        indicated by  a "*";  otherwise, the  default is  to provide  an
        appropriate help file on the word at the text position.

        However, the  select  argument is  an  integer mask  whose  bits
        specify which  of  these  types of  action  should  actually  be
        processed.   If   a   given   type   is   not   selected    for,
        ved_do_text_action does nothing and returns false.

        select may be or'ed together from any of the following,  defined
        in INCLUDE * VED_DO_TEXT_ACTION:

            VDTA_TYPE_CHARS     Allow a  character input  string  from a
                                text action.

            VDTA_TYPE_PDR       Allow a procedure from a text action.

            VDTA_TYPE_COMM      Allow a Ved command  string from a  text
                                action.

            VDTA_TYPE_A_DOC_REF With    no    text    action,    allow a
                                documentation reference  containing  "*"
                                if the text has the active attribute.

            VDTA_TYPE_DOC_REF   With    no    text    action,    allow a
                                documentation reference  containing  "*"
                                whether  the   text   has   the   active
                                attribute or not.

            VDTA_TYPE_ANY_HELP  With  no   text   action  or   "*"   doc
                                reference, allow help on any word.

            VDTA_TYPE_ANY       Allow anything.

        The mode argument is an integer specifying how the action is  to
        be  processed.  The  following   values  are  also  defined   in
        INCLUDE * VED_DO_TEXT_ACTION:

            VDTA_MODE_DISPLAY   Display only.

            VDTA_MODE_EXECUTE   Execute immediately (same as INPUT for a
                                character input string).

            VDTA_MODE_INPUT     Put on ved_char_in_stream to execute  on
                                the next top-level Ved loop cycle.

        When mode  is EXECUTE  or  INPUT, the  procedure or  command  is
        executed,   either   immediately   or    by   putting   it    on
        ved_char_in_stream; before execution, vedline and vedcolumn  are
        set to the position  of the text action's  embedded data if  the
        action requested  it (see  above). The  result returned  is  the
        VDTA_TYPE_ value for whatever was executed.

        When mode is DISPLAY,  the only effect is  to display a  message
        with vedputmessage if the command  requests it (see above),  and
        return  result.  Depending  on  the  action  and  any  flags  it
        contained (see above), result will  be or'ed from the  following
        bits defined in INCLUDE * VED_DO_TEXT_ACTION:

            VDTA_DISP_DID_MESS  A message was displayed.

            VDTA_DISP_INVERT    Invert foreground/background colours  in
                                the active segment.

            VDTA_DISP_BOX       Draw a box around the active segment.

            VDTA_DISP_POINTER   Change  the  mouse   pointer  shape   to
                                pointer2shape.


ved_text_action_data(line, col)                              [procedure]
                -> (data_or_false, retn_line, retn_col)
        Given a line and  a column number,  tests whether the  specified
        column in the line is within a text action (as described above),
        and returns any associated data item if so.

        line may be  either (a) a  string, or (b)  a line number  within
        vedbuffer. For (a), the search  is limited to the given  string,
        whereas for (b) the specified buffer line and (where applicable)
        previous lines are searched.

        In both  cases, col  must be  the column/subscript  at which  to
        begin the  search: if  line(col)  is not  a character  with  the
        active attribute, false is returned for all three results.

        Otherwise, the procedure searches back along line for the  first
        character of the active segment of which col is a part, and then
        forward again  to  find  the  first  active  character  with  an
        embedded data  item.  If  no  data item  is  present,  false  is
        returned for data, but with retn_line set to line, and  retn_col
        set to the column of  the first non-whitespace character in  the
        segment (or false if it was all space).

        If data is present, and is not a nullstring continuation  marker
        (i.e. data /= nullstring), data is returned, with retn_line  set
        to line and  retn_col set  to the column  number containing  the
        data.

        On finding  a  continuation  marker,  the  procedure  will  skip
        backwards  over  whitespace  characters  until  another   active
        character is found. If non-active, non-whitespace characters are
        encountered (or  the  beginning  of  the  string  or  buffer  is
        reached), the search aborts, and the continuation marker  itself
        is returned (as if it had not been recognised).

        Otherwise,  the  whole  process   repeats,  starting  from   the
        newly-found active character.




---------------------------
20  Miscellaneous Utilities
---------------------------

is_ved_output_file(filename)                                 [procedure]
        Returns true if filename is  a Ved "output" file, as  determined
        by inspection of vedlmr_print_in_file. This procedure is used in
        the default value of vedfiletypes to set vedcompilable false for
        "output" files.


popvedcommand(comm_name)                                     [procedure]
        This procedure is  used to implement  Pop-11 syntax versions  of
        Ved commands. For example, the Pop-11 help command is defined as

            define vars syntax help =
                popvedcommand(% "ved_help" %)
            enddefine;

        The (word) argument  comm_name is  the name of  the Ved  command
        procedure to  run  (e.g. "ved_help"):  the  valof this  word  is
        executed after doing the assignment

            readstringline() -> vedargument;

        which will set vedargument to  the remainder of the line  coming
        from the current proglist (see REF * readstringline).

        (Note that before executing the command, vedputcommand is called
        to put the equivalent <ENTER> command on the Ved status line.)


vedissubitem(sub_string, n, string) -> m                     [procedure]
        Similar to  issubstring except  that  (a) it  does not  work  on
        words, and (b) the match succeeds only if the matching substring
        is a distinct item in  the string string. 'Distinct item'  means
        roughly that the substring sub_string  is not embedded in  other
        characters in string; for example

                vedissubitem('DEFINE', 1, 'ENDDEFINE')

        returns false. It uses Ved's rules for deciding item  beginnings
        and ends, not those of  the Pop-11 itemiser. The Ved  procedures
        * vedatitemstart  and  * vedatitemend  are  used  to  test  item
        boundaries.  The  behaviour  can  be  controlled  by  redefining
        * vedchartype.


vedwordcount_text(line_1, line_2)                            [procedure]
        Prints (on  the command  line) a  count of  the words  in  lines
        line_1 to  line_2  of the  current  file. Used  in  ved_wc.  See
        HELP * WC.


vedtrysetvalof(var_name, true_msg, false_msg)                [procedure]
        This procedure is  used to  invert the truthvalue  of a  boolean
        variable var_name (a word or string), and then print a  message,
        using vedputmessage, depending on whether the new value is  true
        or false. If  the new  value is  true, then  string true_msg  is
        used, otherwise string false_msg.

        If var_name is  not declared as  an identifier or  has an  undef
        value, an error message is put out with vederror.

        For examples  of  its use,  see  SHOWLIB * VED_SET,  * VED_TABS,
        * VED_STATIC.


vedusedsize(string_or_vector) -> int                         [procedure]
        A system procedure which returns an indication of the number  of
        characters (if  given  a  string), or  the  number  of  nonempty
        strings (if given a vector) that are strictly part of the  given
        structure.  i.e.  returns  this  size  of  the  structure  after
        trimming has occurred (by vedtrimline etc).


vedfilecomplete()                                            [procedure]
        This library procedure is typically mapped onto a function  key.
        When invoked  it completes  the file  name to  the left  of  the
        cursor, or displays  the possible completions  in the form  of a
        menu, either on the status line  or in a separate temporary  Ved
        buffer. For full information see HELP * VEDFILECOMPLETE.


emacs                                                          [library]
        Inferior pre-cursor to * vedemacs, described below.


vedemacs                                                       [library]
        LIB * VEDEMACS modifies  both  the  terminal  setting  (on  Unix
        systems) and  Ved's  key mapping  to  make Ved  respond  to  key
        presses in a way that is similar  to a subset of the UNIX  EMACS
        editor. Full details are given below. Some, but not all, of  the
        facilities, will also work on VMS.


20.1  Bracket Matching
----------------------

vedfindbracket(char_1, char_2, end_test_p, move_p)           [procedure]
        Searches for char_1 using procedure  move_p to move the  cursor.
        Signals an error  if end_test_p  ever returns  true. Skips  over
        intervening  matched  pairs  of   char_1  and  char_2.   Ignores
        instances of char_1  and char_2 that  are located between  quote
        characters  (see   vedfindbracket_quotes).  Used   by   ved_gbl,
        ved_gel, ved_mp.


vedfindbracket_quotes(ssname) -> string                      [procedure]
        Given a subsystem name ssname, returns a string containing those
        characters that are  considered to be  `quotes' by the  compiler
        for that subsystem. This user-assignable property is defined  in
        LIB * VEDFINDBRACKET and used  by the procedure  vedfindbracket,
        which  ignores  bracket  characters  that  occur  between  quote
        characters.


vedsetwiggle(closing_bracket_char, filetype)                 [procedure]
        Modifies the effect  of typing closing_bracket_char  (in a  file
        whose name ends with the  string filetype) such that the  cursor
        is wiggled over the opening  bracket character that matches  the
        closing_bracket_char just typed.

        If vedsetwiggle  is  called a  second  time with  the  same  two
        arguments, then wiggling is disabled for closing_bracket_char in
        files of type filetype.

        vedsetwiggle is used by * ved_wiggle (i.e. <ENTER> wiggle).


vedclosebrackets(closing_bracket_char);                      [procedure]
        Moves  the  cursor  to  the  end  of  the  current  line  (using
        vedtextright),  and   then  inserts   sufficient  instances   of
        closing_bracket_char to  balance  matching  outstanding  opening
        bracket characters. Uses ved_wmp.



-----------------------------
21  User-Definable Procedures
-----------------------------

These procedures are assessed at  various stages of Ved's execution,  so
it is  possible  for  individual  users  to  tailor  Ved  to  their  own
requirements.

vedcommandtrap()                                    [procedure variable]
        User-assignable  procedure-typed  variable.  The  procedure   is
        executed just  before every  command (i.e.  <ENTER> command)  is
        processed. The default value is identfn.


vedenterkey()                                       [procedure variable]
        User re-definable  procedure  invoked  by  <ENTER>.  Default  is
        vedenter.


vedhelpkey()                                        [procedure variable]
        User re-definable procedure  invoked by the  <HELP> key  (should
        the terminal possess one). The default value is ved_hkeys.


vedinterrupt()                                      [procedure variable]
        A  user-assignable  procedure-typed  variable  which  is  called
        whenever an  interrupt occurs  in Ved  (eg when  user types  the
        interrupt character). The default value is veddointerrupt.


vedpopready()                                       [procedure variable]
        User-assignable procedure, called by interrupt when compiling in
        Ved (e.g. ved_lmr, ved_c etc). Its default value is setpop.

        You can  trap  interrupts  in Ved  by  assigning  * popready  to
        vedpopready. This aids the debugging  of programs since you  can
        inspect the value local variables had when the error handler was
        called.

        Note that  vedpopready  is  not  called  when  compiling  in  an
        'immediate mode' file; to trap  interrupts in this case,  assign
        popready directly to interrupt.


vedprocesstrap()                                    [procedure variable]
        User-assignable   procedure-typed   variable   (default    value
        identfn), called once each time  around the Ved top level  loop,
        just before the call of vedprocesschar in vedprocess, i.e.  once
        per key  or escape  sequence. It  can be  used, for  example  to
        examine  ved_last_char   the   last   character   read   in   by
        vedprocesschar.


vedredokey()                                        [procedure variable]
        User assignable  procedure  variable  associated  with  the  Ved
        <REDO> key. Default value is vedredocommand.


vedvedquitfile()                                    [procedure variable]
        User assignable procedure run whenever a file is quit.  Defaults
        to identfn.


vededitortrap()                                     [procedure variable]
vededitorexit()                                     [procedure variable]
        These user-definable procedures are  called whenever vededit  is
        entered  or  re-entered  (vededitortrap),  or  when  Ved   exits
        normally or  abnormally (vededitorexit).  Both have  identfn  as
        their default value.

        However, these procedure are NOT  called in XVed, since in  that
        case the notion of 'being in Ved'  or 'being out of Ved' is  not
        applicable: vedprocess is  being suspended and  resumed all  the
        time.



--------------------
22  Other Facilities
--------------------

22.1  Procedures for Acting on Rectangular Blocks of Text
---------------------------------------------------------
The following procedures are used by LIB * VEDBLOCKS, fully described in
HELP * VEDBLOCKS.  They  underpin  the  procedures  ved_dtb,   ved_sdtb,
ved_mtb,  ved_smtb,  ved_ttb,  ved_stb,  ved_ytb,  ved_sytb,   ved_yotb,
ved_itb, ved_sitb.

vedblockrepeater(vector_of_strings) -> procedure             [procedure]
        Given a vector of strings all of the same length, such as  might
        be produced by * vedcutblock, this returns a procedure that is a
        character repeater for those strings. Compare * vedrangerepeater

        See HELP * VEDBLOCKREPEATER for an example of use.


vedblocks                                                      [library]
        LIB * VEDBLOCKS,  together  with  associated  libraries,   makes
        available  a   collection   of   procedures   for   manipulating
        rectangular blocks of text in Ved, several of them described  in
        the rest of this section of  REF VEDPROCS. For full details  see
        HELP * VEDBLOCKS


vedcutblock(line_1, col_1, line_2, col_2, delete) -> vec     [procedure]
        Copies rectangular block of text from Ved buffer between corners
        line_1,  col_1,  and  line_2,  col_2  (in  buffer  coordinates).
        Returns a VECTOR of strings.  If delete is non-false, then  also
        deletes the block from the Ved buffer.

        See            HELP * VEDCUTBLOCK,             HELP * VEDBLOCKS,
        HELP * VEDBLOCKREPEATER * VEDYANKBLOCK * VEDOVERLAYBLOCK


vedfillblock(line_1, col_1, line_2, col_2, char)             [procedure]
        Insert a rectangle filled with character char in the Ved buffer.
        Move everything to  the right if  VEDSTATIC is false,  otherwise
        overwrite text. Uses  * vedrefreshblock to  redisplay text.  See
        HELP * VEDFILLBLOCK, * VEDBLOCKS


vedoverlayblock(vector_of_strings)                           [procedure]
        "Yank" a vector of strings,  such as produced by  * vedcutblock,
        into the  Ved buffer  as  a rectangular  block starting  at  the
        current cursor location,  ignoring spaces in  the strings.  I.e.
        where there are spaces the  original contents of the Ved  buffer
        are left to 'show through'. Compare * vedyankblock.


vedrefreshblock(line_1, col_1, line_2, col_2, bool)          [procedure]
        Refresh  the  portion  of  the  screen  showing  the  text-block
        specified. If bool is true then  everything to the right of  the
        text-block  is  refreshed   also.  See   HELP * VEDREFRESHBLOCK,
        * VEDBLOCKS.


vedyankblock(vector_of_strings)                              [procedure]
        Inserts a vector of strings, VEC, into Ved, of the kind produced
        by vedcutblock. Compare * vedoverlayblock.

        See HELP * VEDYANKBLOCK, * VEDBLOCKS




22.2  Reading Output from a Shell Command into a Ved Buffer (Unix Only)
-----------------------------------------------------------------------
HELP * PIPEUTILS describes LIB * PIPEIN and LIB * PIPEOUT, which allow a
Poplog program to spawn  a sub program connected  via a pipe. There  are
several utilities that use * pipein to run a program and read any output
into a Ved buffer,  also described in the  help file, including  ved_sh,
ved_csh, ved_rsh,  ved_remsh,  ved_rved,  and  several  of  the  "dired"
utilities described in  HELP * DIRED. The "system"  procedures on  which
these libraries are built are described below.

diredpipein(string, file)                                    [procedure]
        Run  the  shell  command,   string,  with  file  replacing   any
        occurrence of  %  in the command and read any output into either
        the current  Ved buffer  or a  temporary Ved  file depending  on
        whether use_dired_current_file  is true  or false.  (Default  is
        true). This is used in * ved_dired. (UNIX only)


vedgenshell(string1_or_false, string2_or_false)              [procedure]
        (UNIX only) Run a shell command (using vedpipein) and store  the
        output in a Ved file. This can be used to define a collection of
        Ved commands that run shell commands and print their output into
        a new Ved buffer, e.g. ved_sh, ved_csh, ved_rsh, ved_rved.

        string1  is  the  pathname  of   a  shell,  e.g.  '/bin/sh'   or
        '/bin/csh'. If  the  first  argument is  false  then  the  shell
        defaults to the result of systranslate('SHELL').

        string2 is inserted  as a header  in the output  file (false  is
        ignored).

        vedargument is used to define the  arguments to be given to  the
        shell, e.g. a command to be run.

        If the output  fits on  one line,  then instead  of a  temporary
        file, vedgenshell and  its derivates  will print  the output  on
        Ved's status line, unless the variable show_output_on_status  is
        false.   (The   default   is   true.)   See    HELP * PIPEUTILS,
        LIB * VEDGENSHELL, * VED_CSH.


vedpipein(command, args, file, defaults_p, display, header)  [procedure]
        UNIX only. command is a Unix  command path name and args a  list
        of argument strings, as required for sysexecute and pipein.  The
        command is run and  any output received is  put into a Ved  file
        defined by file (which can be either  a file name or a Ved  file
        structure). defaults_p  is a  procedure to  be executed  in  the
        environment of file as soon as it is opened, to set defaults.

        If display is true the output from the command is displayed as a
        Ved window  on the  screen, or,  if there  is enough  space  and
        show_output_on_status is true, on the status line. If display is
        set to 1, the value of show_output_on_status is ignored.

        If header is  a string then  if an output  file is created,  the
        string is inserted as a header line.

        If file  is false  then instead  of going  into a  new file  the
        output  from  the  command  is   read  into  the  current   file
        immediately after the current line.

        This procedure is used by vedgenshell, and related utilities.


show_output_on_status                                         [variable]
        Variable used by vedpipein, q.v.



--- C.all/ref/vedprocs
--- Copyright University of Sussex 1995. All rights reserved.
