SED Extensions - Standard variables and functions

SED  -  Standard Variables and Functions

Top  Previous  Next

 

Variables are type variant in the same way as for QMBasic programs and they follow the same rules.  In most cases, attempts to use a non-numeric value where a number is required result in use of a default.

 

Buffer Information

%buffer.noReturns the current buffer number.
%buffer.typeReturns a type code for the current buffer:

1 : data buffer

2 : explore buffer

3 : file list buffer

%changedReturns a logical value indicating whether the current buffer is marked as having been changed since it was last saved.
%colReturns current column number.
%current.charReturns character under cursor.
%current.lineReturns text of current line.
%fileReturns file name for current buffer.  This is prefixed by “DICT “ if the buffer is from the dictionary part of the file.
%heightReturns the number of lines on the screen display excluding the two editor status lines.
%idReturns the record id for the current buffer.  For an explore buffer or a file list buffer it returns a pseudo id value.
%kill.bufferReturns the content of the kill buffer.
%lineReturns current line number.
%line.lenReturns length of current line.
%linesReturns number of lines in current record.
%mark.colReturns the column number of the mark position, zero if no mark set.
%mark.lineReturns the line number of the mark position, zero if no mark set.
%overlayReturns a logical value indicating whether the current buffer is operating in overlay mode.
%panReturns the current pan position.  This is the column number (from one) of the leftmost displayed column of the current buffer.
%read.onlyReturns a logical value indicating whether the current buffer is read only.
%scrollReturns current scroll position.  This is the line number of the data displayed on the first line of the screen.
%tab.intervalReturns the current setting of the tab interval.
%widthReturns the width of the screen display.
(delete.buffer)Deletes the current buffer.  Unlike the SED delete.buffer keyboard function, this operation allows deletion of modified buffers without any confirmation checks.
(find.buffer file rec)Returns the internal number of the buffer holding data from the given file and record.  Use of a null string as file allows location of a scratch buffer. This function returns zero if no such buffer exists.
(find.record file rec)Reads record rec from file into a newly created buffer.  If the record is already loaded, it simply switches to that buffer. This function returns True if successful, False if not.
(goto.buffer n)Select buffer number n.
(make.buffer name)Makes a new scratch buffer named name. Scratch buffers may be used for internal purposes of the extension program or as the place to create data which will later be written to disk.  Use of %file with a scratch buffer returns a null string.  %id returns name. This function returns True if successful, False if not. If a scratch buffer of the given name already exists, it makes that buffer current and returns True.
(next.buffer n)Select the buffer with buffer number n greater than the current one.  This operation cycles to the lowest numbered buffer if necessary.
(prev.buffer n)Select the buffer with buffer number n less than the current one.  This operation cycles to the highest numbered buffer if necessary.
(save.record)Saves the current buffer.  It has no effect on a scratch buffer or if the current buffer is read only. The normal source control actions are performed if this editor feature is in use.
(set.changed n)Sets the status of the buffer changed flag.  If n is zero, the buffer is marked as unchanged, otherwise it is marked as changed.  Use this operation with care as it can result in data not being saved on leaving the editor.  It is of particular use with scratch buffers.
(set.overlay n)Sets the overlay status of the current buffer.  If n is zero, overlay is turned off, otherwise it is turned on.
(set.pan n)Set the current pan position to n.  The value of n must be greater than zero. The next screen update (paint or implicit from some other function) will move the pan position if the current cursor position is not in the displayed region of the buffer.
(set.read.only n)Sets the read only status of the current buffer.  If n is non-zero, the buffer is marked as read only, otherwise modifications are allowed. This function is of particular use with scratch buffers.  It is ignored for buffers containing explore record lists or file lists.
(set.scroll n)Sets the current scroll position to n.  The value of n must be greater than zero and must not be greater than the number of lines in the current buffer. The next screen update (paint or implicit from some other function) will move the scroll position if the current line is not in the displayed region of the buffer.
(set.tab.interval n)Sets the tab interval to n.  The value of n must be in the range 1 to 99.
(write.record file rec)Writes the current buffer to record rec in file.  This operation may result in the current buffer being renamed. The normal source control actions are performed if this editor feature is in use. The write.record operation is ignored if the target record is locked by another user.

 

 

Moving the Cursor, Insertion and Deletion

(backspace n)Backspace n characters.
(back.char n)Move cursor left n columns.
(back.word n)Moves the cursor backward by n words.
(bottom)Move to after the final line of the buffer.
(copy.region)Copies the region between the mark and the cursor, which may be in either order, to the kill buffer.
(delete.region)Copies the region between the mark and the cursor, which may be in either order, to the kill buffer and deletes the text from the buffer.
(del.back.word n)Deletes n words backwards from the current cursor position.
(del.char n)Delete n characters.
(del.word n)Deletes n words from the current cursor position.
(down n)Synonym for down.line.
(down.line n)Move cursor down n lines.
(end)Synonym for end.line.
(end.line)Move to the end of the current line.
(fsearch mode str)Search forwards for string str.  The mode indicates the style of search:

0  :  Use the current search mode setting

1  :  Case sensitive

2  :  Case insensitive

3  :  Word search, case insensitive

This function returns a logical value indicating whether the search was successful.  An unsuccessful search does not move the current position.

(fwd.char n)Move cursor right n columns.
(fwd.word n)Moves the cursor forward by n words.
(left n)Synonym for back.char.
(goto.col a)Go to column a of current line.  The line is extended if necessary by adding trailing spaces.
(goto.line a)Go to column 1 of line a.
(home)Synonym for start.line.
(insert s)Insert string s at current cursor position.  Any field marks in the text are treated as newlines.  The insert function can take more than one argument, each of which is inserted in turn.
(newline rpt)Insert rpt newlines at the current cursor position.
(page.down n)Move cursor down by n display pages.
(page.up n)Move cursor up by n display pages.
(retype s)Replace the current line by string s.
(right n)Synonym for fwd.char.
(rsearch mode str)Search backwards for string str.  The mode indicates the style of search:

0  :  Use the current search mode setting

1  :  Case sensitive

2  :  Case insensitive

3  :  Word search, case insensitive

This function returns a logical value indicating whether the search was successful.  An unsuccessful search does not move the current position.

(set.case mode rpt)Changes the case of the next rpt words in the current buffer.  The mode argument is:

0  :  Set lower case

1  :  Set upper case

2  :  Set capital initial casing

(set.mark)Set the mark at the current cursor position.
(start.line)Move to the start of the current line.
(swap.mark)Interchange the cursor and mark positions.  Has no effect if there is no mark position defined.
(tab rpt)Advances the cursor to the next tab position as determined by the current setting of the tab interval.  Additional spaces are appended to the current line if necessary.  The rpt argument specifies how by many tab positions the cursor is to be advanced.
(toggle.chars)Interchanges the character at the cursor position with that in the preceding column.
(top)Move to the start of line 1.
(up n)Synonym for up.line.
(up.line n)Move cursor up n lines.

 

 

Arithmetic, String and Logical Functions

(add a b)Returns a + b.
(and a b)Forms logical relationship a and b. The and function can take more than two arguments, each of which is and'ed in turn.
(cat a b)Returns concatenation of strings a and b.  The cat function can take more than two arguments, each of which is concatenated in turn.
(char n)Returns the character with ASCII character value n.
(del str f v s)Returns a string formed from str with field f, value v, subvalue s deleted.  Specify v and s as zero to delete field f, s as zero to delete field f, value v.
(div a b)Returns a / b.
(downcase s)Returns string s converted to lower case.
(eq a b)Test a equal to b.
(extract str f v s)Returns field f, value v, subvalue s of string str.  Specify v and s as zero to extract field f, s as zero to extract field f, value v.
(field str d n count)Returns a portion of str starting at the n’th substring delimited by d and extending for count such substrings.
(ge a b)Test a greater than or equal to b.
(gt a b)Test a greater than b.
(ins str f v s new)Returns a string formed from str with new inserted before field f, value v, subvalue s.  Specify v and s as zero to insert before field f, s as zero to insert before field f, value v.
(int a)Returns the integer portion of value a by truncating any fractional part.
(le a b)Test a less than or equal to b.
(len s)Returns the length of string s.
(lt a b)Test a less than b.
(max a b)Returns the maximum of a and b.  If either value is not numeric, this function returns the item that appears last in collating sequence order.
(min a b)Returns the minimum of a and b.  If either value is not numeric, this function returns the item that appears first in collating sequence order.
(mul a b)Returns a * b.
(ne a b)Test a not equal to b.
(not a)Returns logical inverse of a.
(or a b)Forms logical relationship a or b. The or function can take more than two arguments, each of which is or'ed in turn.
(pad s n)Pad string s with spaces to be n characters long.  If string s is already at least n characters long, this function returns the original string.
(rem a b)Returns the remainder of dividing a by b.
(rep str f v s new)Returns a string formed from str with field f, value v, subvalue s replaced by new. Specify v and s as zero to replace field f, s as zero to replace field f, value v.
(seq c)Returns the ASCII character sequence number of the first character of c.
(sub a b)Returns ab.
(substr s a b)Returns a substring from s starting at character a, b characters long.
(trim s)Returns string s with all leading and trailing spaces removed and all multiple embedded spaces replaced by a single space.
(trimb s)Returns string s with all trailing spaces removed.
(trimf s)Returns string s with all leading spaces removed.
(upcase s)Returns string s converted to upper case.

 

User Input and Screen Display

%key.charReturns the character from the last get.key if it was an insert action.  For other actions, it returns a null string.
%key.readyReturns a logical value indicating whether there is data waiting from a user key depression.
%prefix.countReturns the prefix count for the last use of get.key.  Returns 1 if no prefix count was entered.

(get.char)        Waits for and returns the character sent by the next key pressed by the user.  This function does not position the cursor.  Precede it with paint if the cursor should be refreshed at the current position.

%prefix.setReturns a logical value indicating whether a prefix count was entered for the last use of get.key.
(beep)Sounds the terminal bell.
(get.key)Waits for user input of a bound key and returns the internal code for this key.  These codes are shown under the heading key tokens above. If the key is a data character, the key type code is .insert and the associated data character can be retrieved using %key.char. See also %prefix.count and %prefix.set.
(paint mode)Refreshes the screen display and positions the cursor.  The mode argument is:

0  :  Updates screen for any changes

1  :  Clears the screen and repaints all displayed data

Repainting of the screen terminates on detection of type-ahead.

(prompt prmpt dflt)Displays prmpt prompt text on the upper status line and invites input. Dflt is the default input if the return key is pressed without entering any response.

On Initial entry to a procedure started from the keyboard, this function returns any prefix count associated with the keyboard action.

(status.msg str)Displays message str on the upper status line.  The displayed text may be cleared by using the status.msg operation with a null str.
(wait.input)Wait for the user to press a key.  The actual key pressed remains available for subsequent processing.

 

Miscellaneous File Handling

(delete rec)Deletes rec from file.  If the file cannot be opened, this function has no effect
(exists file rec)Returns a logical value indicating whether record rec exists in file.
(read file rec)Returns record rec from file.  If the record cannot be read, this function returns a null string.
(write file rec str)Writes str to record rec of file.  If the file cannot be opened, this function has no effect

 

 

Conditional Execution and Loops

(exit)Exits from the innermost active loop.
(if a proc1 else proc2)Executes procedure proc1 if logical item a is True, proc2 if it is False.  The else component is optional.  Both proc1 and proc2 may be one or more procedures.

(loop proc

)Executes proc repeatedly. proc may be one or more procedures.  A loop is terminated by use of exit.
(quit n)Terminates current edit.  If n is zero, SED continues processing a select list (equivalent to the quit editor function).  For non-zero values of n, SED terminates the entire sequence (equivalent to the QUIT command).
(return)Returns from the current PROC.
(return n)Returns n as the value of the current FUNC.
(stop)Terminates extension program and returns to SED edit mode.

(switch val

  case a proc1

  case b proc2

  ...

  else proc)Executes one of several procedures depending on the value of val.  Items a, b and c (etc.) are values which are compared with val.  The else component is optional and is executed only if none of the preceding conditions is met.

 

Setting Variables

(set var val)Set local or global variable var to val.

 

 

Extension Control

%key.bindingsReturns a dynamic array, each field of which corresponds to a bindable internal function and consists of one or more values which hold the actual character sequence.  Note that this character sequence is the actual characters, not the encoded form used in the key bindings records to avoid use of control characters.  The field number of any particular key can be identified using the key tokens described earlier.
%macro.stateReturns state of editor macro system:

0  :  Not collecting or executing

1  :  Collecting macro

2  :  Executing macro

(bind.command ext name)Binds extension procedure ext as command name.  The extension name is automatically converted to upper case.
(bind.key ext keyseq)Binds extension procedure ext as key sequence keyseq.  The extension name is automatically converted to upper case.

This function returns a logical value indicating whether it was successful.

(unload)Unloads all extensions on exit from outermost extension program.
(xeq cmnd)Executes cmnd as though it were entered using the editor command function.  Commands which are themselves bound to extensions cannot be executed in this way.

SED checks for extensions bound as command names before internal commands.  It is therefore possible to replace a built-in command.  Furthermore, since extensions cannot execute extension commands, the extension can be used to provide a prelude to a built-in command.

 

 

Basic Functions  (Operations that mimic QMBasic programming functions)

(alpha str)Equivalent to ALPHA(str)

Returns a logical value indicating whether str is an entirely alphabetic string.

(change str old new)Equivalent to CHANGE(str, old, new)

Replace each occurrence of old with new in str.

(convert old new str)Equivalent to CONVERT(old, new, str)

For each character in old, this function replaces all occurrences of that character in str by the character in the corresponding position in new.  If new is shorter than old, characters in old for which there is no replacement in new are deleted from the returned version of str.

(count str substr)Equivalent to COUNT(str, substr)

Returns a count of the number of occurrences of substr in str.

(dcount str delim)Equivalent to DCOUNT(str, delim)

Returns a count of the number of substrings in str delimited by delim.  The delimiter must be a single character.

(iconv str conv)Equivalent to ICONV(str, conv)

Returns the result of applying input conversion conv to str.

(index str substr occ)Equivalent to INDEX(str, substr, occ)

Returns the character position (from one) of the occ’th occurrence of susbtr in str.  This function returns zero if the specified occurrence is not found.

(matches str pattern)Equivalent to str MATCHES pattern

Tests whether str matches the given pattern.

(matchfield str pattern n)Equivalent to MATCHFIELD(str, pattern, n)

Returns the n'th component of str when matched against pattern.

(num str)Equivalent to NUM(str)

Returns a logical value indicating whether str can be interpreted as a number.

(oconv str conv)Equivalent to OCONV(str, conv)

Returns the result of applying output conversion conv to str.

(subr func arg1 arg2...)Equivalent to SUBR(func, arg1, arg2...)

Call QMBasic function.

 

 

Keyboard Functions Not Available as Extension Functions

 

The following editor keyboard functions are not available directly as extension operations.  They can all be achieved by use of other operations.

 

Editor FunctionEquivalent Extension Coding
export(write file rec %kill.buffer)
import(insert (read file rec))
insert killed(insert %kill.buffer)