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 cha