allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) (06/11/89)
Posting-number: Volume 7, Issue 27
Submitted-by: fox@marlow.UUCP (Paul Fox)
Archive-name: crisp1.9/part07
#!/bin/sh
# this is part 6 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file help/crisp/prim/R.cmd continued
#
CurArch=6
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
exit 1; fi
( read Scheck
if test "$Scheck" != $CurArch
then echo "Please unpack part $Scheck next!"
exit 1;
else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file help/crisp/prim/R.cmd"
sed 's/^X//' << 'SHAR_EOF' >> help/crisp/prim/R.cmd
X
X (See also (index)).
X
XEXAMPLES:
X
X The following example splits a string into a directory and
X filename part.
X
X (string dir file)
X (string filename)
X (int i)
X
X (= i (rindex filename "/"))
X (if i
X (
X (= dir (substr filename (- i 1)))
X (= file (substr filename (+ i 1)))
X )
X ;else
X (
X (= dir ".")
X (= file filename)
X ))
SHAR_EOF
echo "File help/crisp/prim/R.cmd is complete"
chmod 0644 help/crisp/prim/R.cmd || echo "restore of help/crisp/prim/R.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/S.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/S.cmd &&
X.HU save_position
XSYNOPSIS: (save_position)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to save the current buffer and cursor
X position. It makes use of an internal position stack;
X (restore_position) can be used later to restore the cursor
X position.
X
X Note that the position stack is an independent stack of
X any buffer. This means that (restore_position) may be
X called to pop off the top entry of the stack even when the
X current buffer is not the same as buffer referenced by the
X top of the saved position stack.
X.HU screen_dump
XSYNOPSIS: (screen_dump [file])
X
XRETURN VALUE:
X
X -1 if cannot write file; 0 if successful.
X
XDESCRIPTION:
X
X This macro is used to get a snapshot of the current screen
X image. It will write the current screen to the named file
X or to the file /tmp/crisp.screen if file isn't specified.
X
X It does not make use of the screen's character attributes
X and makes an approximation for the screen drawing
X characters.
X.HU search_back
XSYNOPSIS: (search_back [pattern] [re] [case] [block] [length])
X
XRETURN VALUE:
X
X Returns 0 if pattern not found. -1 if an error is
X detected. Otherwise it returns the length of the matched
X text + 1.
X
XDESCRIPTION:
X
X This function searches from the current cursor position
X backwards towards the top of the buffer looking for pattern.
X
X If pattern is omitted, it is prompted for.
X
X If re is specified and it is zero, then pattern is treated
X as a pure string; if it is omitted or is non-zero, then
X pattern is treated as a regular expression. (See section
X on Regular Expressions for details of the syntax of
X regular expressions).
X
X If case is specified and is zero, then the pattern is
X treated non-case sensitively, i.e. A matches a. Otherwise
X the search is performed with case being sensitive.
X
X If block is specified and is non zero, then the search is
X confined to the currently marked region.
X
X If length is specified and is non-zero, then it indicates
X that on a successful return the length of the matched
X string should be returned + 1. If it is not specified,
X then the return length will take into account any \c
X parameters in the regular expression.
X.HU search_case
XSYNOPSIS: (search_case [case])
X
XRETURN VALUE:
X
X Returns the previous value of the case flag.
X
XDESCRIPTION:
X
X This macro is used to set the value of the search case
X flag. By default all searches are case sensitive, i.e. "A"
X does not match "a". By setting case to non-zero, case
X sensitivity will be ignored when performing matches.
X
X If case is omitted, the current value is toggled.
X.HU search_fwd
XSYNOPSIS: (search_fwd [pattern] [re] [case] [block] [length])
X
XRETURN VALUE:
X
X Returns 0 if pattern not found. -1 if an error is
X detected. Otherwise it returns the length of the matched
X text + 1.
X
XDESCRIPTION:
X
X This function searches from the current cursor position
X towards the end of the buffer looking for pattern.
X
X If pattern is omitted, it is prompted for.
X
X If re is specified and it is zero, then pattern is treated
X as a pure string; if it is omitted or is non-zero, then
X pattern is treated as a regular expression. (See section
X on Regular Expressions for details of the syntax of
X regular expressions).
X
X If case is specified and is zero, then the pattern is
X treated non-case sensitively, ie A matches a. Otherwise
X the search is performed with case being sensitive.
X
X If block is specified and is non zero, then the search is
X confined to the currently marked region.
X
X If length is specified and is non-zero, then it indicates
X that on a successful return the length of the matched
X string should be returned + 1. If it is not specified,
X then the return length will take into account any \c
X parameters in the regular expression.
X.HU search_list
XSYNOPSIS: (search_list [start] pattern list_expr [regexp] [case])
X
XRETURN VALUE:
X
X The index of the atom in list_expr where the pattern was
X found; -1 otherwise.
X
XDESCRIPTION:
X
X This macro is used to search a linked list for a string
X pattern.
X
X If start is not specified, the search is started from the
X beginning of the list; otherwise the search starts from
X the atom numbered start.
X
X pattern is the string to search for, and may or may not be
X a regular expression, depending on the value of regexp.
X list_expr is the list to search.
X
X If regexp is not specified or is zero, then pattern is not
X treated as a regular expression. If it is specified and
X non-zero then pattern is considered to be a regular
X expression.
X
X If case is specified and is non-zero, then the case
X sensitivity is taken into account.
X.HU search_string
XSYNOPSIS: (search_string pattern string [length] [re] [case])
X
XRETURN VALUE:
X
X Returns the starting character in string where the match
X was found, or zero if the match failed.
X
XDESCRIPTION:
X
X This macro is used to search string for the pattern,
X pattern. If re is specified and is zero, then pattern is
X treated as a literal string - not a regular expression (in
X which case this function is similar to (index)). If case
X is specified and is zero, then the search is done with
X case insensitive.
X
X If length is specified (name of an integer variable), then
X it will receive the length of the matched pattern, if the
X search is successful.
X.HU self_insert
XSYNOPSIS: (self_insert [n])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is the means for the user to type data into the
X current buffer. It causes the last character to be typed
X to be inserted into the buffer (or overtyped if overtype
X mode is on).
X
X If n is specified, then the character whose ASCII value is
X n is inserted into the file instead of the last character
X typed.
X.HU set_backups
XSYNOPSIS: (set_backups [mode])
X
XRETURN VALUE:
X
X Returns the previous value of the backup flag.
X
XDESCRIPTION:
X
X This macro can be used to inquire or turn on/off the
X setting of the backups flag. The backups flag is tested
X every time a buffer is written away (via write_buffer). If
X the flag is on, then a backup file is made.
X
X If mode is not specified, then the backup flag is toggled.
X A non-zero value for mode turns backup creation on. Zero
X turns it off.
X
X If called from the keyboard, then one of the following
X messages are printed:
X
X Backups will be created.
X Backups will not be created.
X
X.HU set_buffer
XSYNOPSIS: (set_buffer bufnum)
X
XRETURN VALUE:
X
X Returns the ID of the previous buffer or less than zero if
X bufnum is an invalid buffer.
X
XDESCRIPTION:
X
X This macro is used for changing the current buffer; bufnum
X is a buffer identifier, as returned via a (create_buffer)
X or (inq_buffer) call.
X
X (set_buffer) does not cause any registered macros to be
X called (unlike edit_file).
X.HU set_buffer_flags
XSYNOPSIS: (set_buffer_flags [and_mask] [or_mask])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This primitive is used to modify the internal flags
X associated with a buffer. If and_mask is set, then the
X internal mask is AND'ed with the mask; if or_mask is set
X then the internal mask is OR'ed with the mask. The
X and_mask is performed before the or_mask. If the and_mask
X turns off the buffer changed flag, then the internal
X 'number of modifications' flag associated with the buffer
X is also cleared.
X
X This allows a calling macro to make a set of changes to a
X buffer, but not have the buffer marked as being modified
X for the buffer_list macro or the exit code.
X
X The flags are listed below:
X
X 0x01 If set, buffer has been modified.
X
X 0x02 If set, buffer will be backed up when written away.
X
X 0x04 Buffer is marked as read-only.
X
X 0x08 Reserved.
X
X 0x10 Underlying file has execute permission.
X
X 0x20 Process attached.
X
X 0x40 Buffer is in binary mode.
X
X 0x80 ANSI mode -- color escape sequences will be processed.
X
X.HU set_calling_name
XSYNOPSIS: (set_calling_name name)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to set the calling name of the current
X macro. The calling name can be retrieved via the
X (inq_called) macro.
X
X This primitive is not currently implemented.
X.HU set_display_chars
XSYNOPSIS: (set_display_chars str0 str1 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to modify the internal control
X characters table. This table is used when a control
X character is to be displayed on the screen. By default,
X all control characters (except tab and newlines) are
X displayed as ^x, on those terminals which dont support
X alternate graphics sets. str0, str1, etc specify a string
X which is to be used to display ASCII value 0x00, 0x01, and
X so on upto 0x1f.
X
X Upto 32 arguments may be given, representing all the
X control characters. Extras may be omitted. See the macro
X source file edt.m for an example of how to use this macro.
X
X It is not possible to query the current settings.
X.HU set_msg_level
XSYNOPSIS: (set_msg_level msg_level)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to set the message level. The message
X level is used to control what sort of messages are to be
X displayed on the status line. It is needed by some macros
X which dont want CRISP internal messages to be displayed.
X
X msg_level is a number in the range 0-3 with the following
X effects:
X
X 0 This is the default - all message on.
X 1 normal messages (those printed via (message) are
X not displayed). Error messages still display.
X 2 error messages are disabled.
X 3 normal messages and error messages are disabled.
X
X Message level 3 can be used to ensure a macro is 'quiet'.
X.HU set_process_position
XSYNOPSIS: (set_process_position [line] [col])
X
XRETURN VALUE:
X
X Returns -1 if current buffer is not attached to a process;
X returns 0 otherwise.
X
XDESCRIPTION:
X
X This macro sets the line and/or column associated with the
X input from a sub-process. line & col are optional, and if
X specified are integer values specifying the line and
X column where input should carry on from.
X
X Processes maintain their own independent input in the
X buffer so that it is easier to write macros which
X manipulate sub-processes.
X.HU set_scrap_info
XSYNOPSIS: (set_scrap_info [insert_newline] [mark_type])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to set the newline at the end of the
X scrap buffer flag and possibly change the type of the
X scrap buffer.
X
X It is not currently implemented.
X.HU set_term_characters
XSYNOPSIS: (set_term_characters [top_left] [top_right] [bot_left]
X [bot_right] [vertical] [horizontal]
X [top_join] [bot_join] [cross]
X [left_join] [right_join])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to set the escape sequences needed to
X support the CRISP window drawing characters. These escape
X sequences are non-standard in the sense that termcap does
X not support them (although some of these are supported by
X terminfo, but CRISP does not currently support terminfo).
X
X This macro should be called before the display is enabled
X (see (enable_display)).
X
X Each parameter is either NULL indicating that no value is
X being provided, or an integer or string expression. If an
X integer expression is specified, then CRISP treats this as
X meaning that the escape sequence as such consists of a
X single ASCII character, whose value is given by the
X integer expression. If a string expression is given, then
X this string is printed when the specific character is
X needed on the display.
X
X The following parameters have the following meanings:
X
X top_left Printed at top left of window.
X top_right Printed at top right of window.
X bot_left Printed at bottom right of window.
X bot_left Printed at bottom left of window.
X vertical Printed at vertical line at side of
X window.
X horizontal Printed on horizontal line at top
X and bottom of window.
X top_join Character used at the top right and
X top left of windows where they abut
X each other. (Not currently implemented).
X bot_join Character used at the bottom right and
X bottom left of windows where they abut
X cross Character used to print where four
X windows intersect at a common corner.
X left_join Character used at intersection of
X three windows on the left side of main
X window.
X right_join Character used at intersection of
X three windows on the right hand side
X of main window.
X
XEXAMPLES:
X
X For examples of how this macro is used, refer to the
X tty/*.m macros, which have examples for a number of common
X environments.
X.HU set_term_features
XSYNOPSIS: (set_term_features [space] [char] [icursor]
X [ocursor] [vicursor] [vocursor]
X [escape] [repeat] [zerom]
X [color])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to specify certain attributes about the
X current display - features which are not adequately
X handled by termcap of terminfo.
X
X Each parameter is either NULL indicating that the feature
X is not available, or an integer or string expression.
X zerom and color are boolean expressions and only integer
X expressions (zero or non-zero) should be specified for
X these two. The others are escape sequences, along the
X lines of (set_term_characters).
X
X If these escape sequences are not specified, CRISP will
X still function but will not perform very well.
X
X If any of the escape sequences can be described as single
X ASCII characters then that particular parameter can be
X specified as an integer expression whose value is that
X ASCII character.
X
X The parameters describe the following features of the
X display:
X
X space This is an escape sequence used to
X blank out the next N character
X positions. This is usually defined as
X "\x1B[%dX" for those displays that
X understand the ANSI ESC [ X escape
X sequence. The escape sequence must
X have an embedded '%d' to specify where
X the numeric qualifier goes.
X
X If this escape sequence is not
X defined, then CRISP makes do with
X printing the correct amount of spaces
X and then moving the cursor back to the
X start of the cleared region. This is
X not as efficient as the ESC[X escape
X sequence when N is larger than about 8
X or 9 characters.
X
X char This is an escape sequence used to
X allow access to characters with the
X top bit set. Some displays, especially
X those based on the IBM/PC require a
X special escape sequence to access the
X characters with the top bit set.
X
X It is valid for a '%c' or '%d' to be
X embedded in the character definition.
X
X If this escape sequence is not
X defined, CRISP will avoid printing
X characters with the top bit set and
X will use the (display_mode) option
X instead.
X
X icursor, vicursor, ocursor, and vocursor
X These escape sequences are used to
X change what the cursor looks like.
X These sequences represent the insert
X cursor, virtual-insert cursor,
X overtype cursor, and virtual-overtype
X cursor respectively.
X
X If these escape sequences are not
X defined CRISP will display a two
X character mnemonic on the status line
X indicating what mode the cursor is in.
X
X repeat This defines an escape sequence for
X repeating the previous character
X printed. It is not currently used.
X
X escape This defines an escape sequence used
X for printing out the ESC character
X itself. This is available because some
X systems have a feature whereby there
X is a short cut to printing the ESC
X character.
X
X zerom If this is non-zero, then whenever an
X ESC[0m is printed, it is assumed that
X the background and foreground colours
X get reset. This is true of Interactive
X V.3 (although not Microport).
X
X color If non-zero, then terminal supports
X color. The escape sequences for color
X are built into CRISP. CRISP assumes
X that if this is set, that the ANSI X
X 3.64 escape sequences are valid.
X
XEXAMPLES:
X
X Refer to the tty/*.m files for examples of this macro.
X.HU set_term_keyboard
XSYNOPSIS: (set_term_keyboard range1 key-list1 range2 key-list2 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to define the keyboard bindings. The
X keyboard bindings is an internal table to CRISP describing
X which physical keys on the keyboard generate which
X internal key code. All the keys CRISP knows about have an
X internal key code (usually in the range 128-255); PC-type
X keyboards can usually generate these key codes directly.
X On non-PC keyboards, eg SUN-3 keyboard, the function keys
X and LEFT/RIGHT keys can be used as a 'META' key prefix
X (much the way ALT is used on a PC keyboard).
X
X By default, each internal key is mapped to its own value;
X this requires a keyboard which can generate characters
X with the top bit set. By using this macro, it is possible
X to define the various function keys which exist on the
X keyboard to map to these internal key codes.
X
X The arguments to (set_term_keyboard) consists of a
X sequence of ranges and key-lists. The ranges exist to make
X it easy to allocate the keys and read the macro
X afterwards. This avoids having to call this macro with
X upwards of 100 key definitions, and the resultant
X inability to decipher mistakes made on the 51st argument,
X for example.
X
X The include file tty.h defines the ranges. A range is
X simply a number. The first function keys (<F1>..<F12>
X start at 128). By specifying a range of 128, this means
X that consecutive key definitions will start at this range,
X and be allocated consecutive slots from thereon. (See the
X tty-*.m files for an example of how this works).
X
X The key-list is simply a list of strings describing each
X consecutive key. If the keys are to be hard-wired, then
X the (quote_list) function will be very useful. Otherwise
X the list can be constructed with the other list primitives.
X
X Ambiguous key prefixes are allowed. This allows keys to be
X defined with the usual ESC-type prefixes. If the start of
X an ambiguous key sequence is typed, then CRISP will wait
X upto .5 second for more keystrokes to resolve the
X ambiguity. After this time, CRISP treats the original
X ambiguous characters as standalone. On some keyboards,
X viz. Suns, RTPCs, Microport and Interactive, this means
X that hitting the ESCape character will delay progress for
X 0.5 second, until CRISP realises that no more keys are
X coming.
X
X Because of this ambiguity problem, problems can arise when
X using CRISP across a network, for example. When using
X applications like telnet, keeping your finger on the <Up>
X or <Down> keys, etc, can cause CRISP to misread the
X keyboard, with the effect that instead of treating
X something like ESC[A as <Up>, it treats it as the single
X characters, ESC, [, A causing them to be inserted into the
X buffer. I do not know of any cure for this, except to
X increase the default .5 second timer. Increasing the .5
X second timer inside CRISP causes the side effect that
X hitting the ESC key at the buffer_list prompt, for
X example, causes an annoying delay.
X
XEXAMPLES:
X
X The following example is the first section of the
X (set_term_keyboard) macro from the tty/at386.m macro file.
X
X (set_term_keyboard
X F1-F12
X (quote_list "\x1BOP" "\x1BOQ" "\x1BOR" "\x1BOS" "\x1BOT"
X "\x1BOU" "\x1BOV" "\x1BOW" "\x1BOX" "\x1BOY"
X "\x1BOZ" "\x1BO[" )
X
X.HU set_top_left
XSYNOPSIS: (set_top_left [line] [col])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro sets the position of the current buffer
X attached to the current window for display purposes. It
X allows the calling macro to reframe the buffer.
X
X line and col are optional integer expressions which
X specify the line in the buffer which is to appear as the
X top line in the screen, and col specifies the column
X number which should appear in the top left hand position
X in the screen.
X
XEXAMPLES:
X
X The following example puts the current line in the center
X of the window (this is the macro normally mapped to
X <Ctrl-C>).
X
X (macro set_center_of_window
X (
X (int cur_line)
X
X (inq_position cur_line)
X (set_top_left (- cur_line
X (/ (inq_window_size) 2)))
X )
X )
X.HU set_window
XSYNOPSIS: (set_window win_id)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Changes the current window to the window specified by
X win_id. win_id is a window identifier, as previously
X returned via (inq_window).
X.HU shell
XSYNOPSIS: (shell [command] [use_shell] [completion])
X
XRETURN VALUE:
X
X Returns the shell exit status (under Unix, 0 means command
X exited successfully, non-zero means command failed for
X some reason).
X
XDESCRIPTION:
X
X This command is used to execute a command in a shell.
X command is a string expression which evaluates to a
X command (with or without its arguments) which is exec()ed
X by CRISP.
X
X The use_shell parameter is an integer expression which
X controls whether the display should be left intact or not.
X If it is omitted or zero, then CRISP puts the terminal back
X into normal (cooked) mode and executes the command string.
X When the sub-process exits, CRISP repaints the screen. If
X use_shell is non-zero, then CRISP does not repaint the
X screen. Setting use_shell to non-zero is useful for things
X like the make and directory manipulation macros which know
X the sub-process cannot destroy the screen.
X
X The command string is passed to the shell so it can
X execute and interpret the command string (e.g. wildcard
X expansion, semicolons etc). The shell used is gotten from
X the SHELL environment variable. If this is not set, then
X CRISP tries the 'shell' environment variable. If this
X fails, it defaults to /bin/csh.
X
X The return from this macro is the shell exit status.
X
X If completion is specified, then it should be the name of
X a macro (in quotes - with optional arguments) which will
X be called when the sub-process terminates. When using this
X facility, you should set the use_shell parameter to 1 to
X avoid CRISP from waiting for the sub-shell to complete.
X
X The completion routine is called with the first parameter
X set to the return status from the underlying process. Any
X other positional parameters are shifted up one.
X
XEXAMPLES:
X
X The following macro can be used to get a subshell to type
X commands into. The user terminates the sub-shell by typing
X the usual ^D or exit. (This is the same as what <Alt-Z> is
X usually mapped to).
X
X (shell)
X
X The following example performs a 'who' command and saves
X the output in a temporary file so the calling macro can
X maybe display it prettily afterwards:
X
X (shell "who >& /tmp/who.tmp" 1)
X
X The '1' tells CRISP not to bother repainting the screen.
X
X The following example causes a macro to be called when the
X sub-process terminates. The sub-process then prints a
X message saying that the process has terminated.
X
X (shell "make" 1 "completion")
X .
X .
X (macro completion
X (
X (int status)
X (get_parm 0 status)
X (message "Job done status %d" status)
X )
X )
X.HU sleep
XSYNOPSIS: (sleep [sec])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro causes the calling macro to sleep for sec
X seconds (or 1 if omitted).
X.HU sort_buffer
XSYNOPSIS: (sort_buffer [bufnum])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro can be used to sort the lines in the current
X buffer or the buffer specified by bufnum. If the buffer
X specified has a region marked, then only those lines
X within the region are sorted.
X
X The lines are sorted alphabetically - there is no
X mechanism to perform sorting based on keys within each
X line, or based on other criteria, eg sorting numerically,
X etc.
X
X Be wary of this macro -- if it is used on a non-system
X buffer, it is not possible to 'undo' the sort.
X
X This macro is an experimental macro, and its functionality
X may change in the future or be deleted.
X
XEXAMPLES:
X
X The following example sorts all the lines in the current
X buffer into order:
X
X (sort_buffer)
X.HU sprintf
XSYNOPSIS: (sprintf buf fmt [arg1] [arg2] ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro acts like the C sprintf() function. It copies
X the string 'fmt' to the string variable 'buf' and applies
X the printf style formatting commands as specified in fmt,
X and using the argument list.
X
X Refer to the (message) macro for details on the formatting
X options available.
X.HU string
XSYNOPSIS: (string var1 var2 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to define local variables which are to
X contain only string values. The variables defined are
X local variables, and are destroyed when the macro
X executing this declaration terminates.
X
X String variables can contain variable length strings (upto
X 2^32 bytes long on machines with 32-bit int's, and 2^16
X bytes on machines with 16-bit int's).
X.HU string_count
XSYNOPSIS: (string_count string char-list)
X
XRETURN VALUE:
X
X Returns the number of times the characters in char-list
X occur in the string parameter.
X
XDESCRIPTION:
X
X This macro is used to count the occurences of characters
X in the string argument. char-list can be a string with one
X or more characters in it. The string argument is parsed
X looking at each character to see if any of the characters
X from char-list match it.
X
XEXAMPLES:
X
X The following example counts how many spaces occur in the
X input string:
X
X (string s)
X (int num)
X (= num (string_count s " "))
X
X The following example counts how many upper case letters
X appear in the input string:
X
X (= num (string_count s "ABCDEFGHIJKLMNOPQRSTUVWXYZ"))
X.HU strip_cr
XSYNOPSIS: (strip_cr [strip])
X
XRETURN VALUE:
X
X Returns previous value of strip flag.
X
XDESCRIPTION:
X
X This macro controls the strip <CR> flag. By default, when
X CRISP reads a file into a buffer, it strips any
X carriage-returns at the end of the line. This makes it
X easy to edit DOS files for example which insist on
X <CR>/<LF> pairs at the end of each line; Unix only uses
X the <LF> as a line terminator.
X
X If the user wants the <CR>'s to remain intact, then this
X macro can be used to toggle or set the flag. If strip is
X omitted, then the strip flag is toggled; otherwise the
X strip flag is set to the value of strip. Non-zero causes
X <CR>'s to be stripped; zero causes <CR>'s to be left as is.
X
X If called from the keyboard, then one of the following
X messages are displayed on the status line.
X
X <CR> stripped from input files.
X <CR> not stripped from input files.
X.HU strlen
XSYNOPSIS: (strlen expr)
X
XRETURN VALUE:
X
X Returns the number of characters in the string expression,
X expr.
X.HU substr
XSYNOPSIS: (substr string start [length])
X
XRETURN VALUE:
X
X Returns the sub-string of string which starts at start,
X and goes on for length characters, or the end of the
X string if length is omitted.
X.HU swap_anchor
XSYNOPSIS: (swap_anchor)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro swaps the current cursor position with the
X start of the currently marked region, ie if the cursor is
X at the end of the marked region, the cursor is moved to
X the start of the marked block, keeping the marked block
X intact.
X.HU switch
XSYNOPSIS: (switch expr case-1 list-1 case-2 list-2 ..)
X
XRETURN VALUE:
X
X Returns the value of the last statement executed in list-n.
X
XDESCRIPTION:
X
X This macro implements the CRISP switch statement. expr is
X an integer or string expression which is evaluated and
X then compared with each of case-1, case-2, etc. case-1,
X etc should be expressions of the same type as expr. If a
X match is found, then the statements in list-n are executed.
X
X If CRISP encounters a case-n value of NULL, then this is
X taken to be the default and the list is unconditionally
X executed.
X
XEXAMPLES:
X
X The following example illustrates an example of integer
X switches. If the value of i, is 1, 2, or 3 then word is
X assigned the strings "one", "two" or "three" respectively.
X If i is not one of these three values, then word is
X assigned the ascii representation of i.
X
X (string word buf)
X (int i)
X
X (= word (switch i
X 1 "one"
X 2 "two"
X 3 "three"
X NULL (
X (sprintf buf "%d" i)
X buf
X )))
X
X The following shows the reverse:
X
X (string word)
X (int i)
X
X (= i (switch word
X "one" 1
X "two" 2
X "three" 3
X NULL (atoi word)))
X
SHAR_EOF
chmod 0644 help/crisp/prim/S.cmd || echo "restore of help/crisp/prim/S.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/T.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/T.cmd &&
X.HU tabs
XSYNOPSIS: (tabs [tab1] [tab2] .. [tabn] )
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to set the tab stops for the current
X buffer. tab1, tab2, set the first tab stops. Tab stops are
X set every (tabn - tabn-1) stops after the last tab stop.
X The first column in the line is column 1.
X
X Upto 5 unique tab stops can be specified, thereafter all
X tab stops default to the difference of the last two tab
X stops.
X
X In soft tab mode (see (use_tab_char)), whenever a tab is
X inserted into the text, enough spaces are inserted
X automatically to take the cursor to the next tab stop.
X When in hard tab mode, physical tab characters are inserted.
X
X When in hard tab mode, the tab stops only affect the way
X the text buffer is displayed; if tab stops other than the
X default 8 are used, then the user may have problems
X printing files or using other utilities to examine the
X file due to column misalignment.
X
XEXAMPLES:
X
X The following sets tab stops to every 4 columns:
X
X (tabs 1 5)
X
X The following sets tab stops to every 8 columns:
X
X (tabs 1 9)
X.HU time
XSYNOPSIS: (time [hours] [mins] [sec])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X hours, mins and secs are optional integer
X variables which receive the current time.
X
X hours is a number in the range 0-23; mins is a
X number 0-59; secs is a number 0-59.
X
XEXAMPLES:
X
X The current time can be printed as such:
X
X (int hours mins secs)
X (time hours mins secs)
X (message "Time now: %02:%02:%02" hours mins secs)
X
X.HU top_of_buffer
XSYNOPSIS: (top_of_buffer)
X
XRETURN VALUE:
X
X Returns non-zero if the cursor changed position; zero
X otherwise.
X
XDESCRIPTION:
X
X Moves the cursor to the start of line 1 in the current
X buffer.
X.HU top_of_window
XSYNOPSIS: (top_of_window)
X
XRETURN VALUE:
X
X Returns non-zero if the cursor changed position; zero
X otherwise.
X
XDESCRIPTION:
X
X Moves the cursor to the start of the line displayed at the
X top of the window.
X.HU transfer
XSYNOPSIS: (transfer buf_id start_line start_col end_line end_col)
X
XRETURN VALUE:
X
X Returns zero or less if unsuccessful; zero if successful.
X
XDESCRIPTION:
X
X This function is used to copy a block of text from one
X buffer to another. buf_id is the buffer identifier of the
X source buffer. start_line, start_col, end_line, and
X end_col specify the bounds of the text to be copied.
X
X The copied text is copied to the current buffer at the
X current cursor position.
X
X It is provided for compatability with BRIEF. It is usually
X far easier to use the region macros.
X.HU translate
XSYNOPSIS: (translate [pattern] [replacement] [global]
X [re] [case] [block])
X
XRETURN VALUE:
X
X Returns the number of translations.
X
XDESCRIPTION:
X
X This macro is used to perform string translations within
X the current buffer. pattern is the string to translate. If
X re is not specified or is non-zero, then pattern is
X treated as a regular expression, otherwise it is treated
X as a normal string. If case is not specified or is
X non-zero, then the search is performed case insensitively.
X If block is specified and is non-zero, then the search is
X limited to the currently hilited region.
X
X replacement is a string containing the string to replace
X pattern with.
X
X If global is specified and is non-zero, then every
X occurence in the current buffer from the cursor to the end
X of the buffer is translated. If global is zero, then only
X the first occurence is translated. If global is not
X specified, then the user is prompted for each change.
X
X If pattern or replacement is not specified, then the user
X is prompted for the change.
X.HU trim
XSYNOPSIS: (trim string)
X
XRETURN VALUE:
X
X Returns a copy of string with all trailing white space
X characters removed. (spaces, tabs and newlines).
X.HU typeof
XSYNOPSIS: (typeof expr)
X
XRETURN VALUE:
X
X Returns one of the string constants, "NULL", "integer",
X "string", or "list" depending on the type of expr.
X
XDESCRIPTION:
X
X This macro is an alternative way to determine the current
X type of a polymorphic variable.
X
SHAR_EOF
chmod 0644 help/crisp/prim/T.cmd || echo "restore of help/crisp/prim/T.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/U.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/U.cmd &&
X.HU undo
XSYNOPSIS: (undo [move] [write_mark] [redo])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This is the macro used to undo buffer modifications. When
X called with no arguments it undoes the last operation
X performed on the buffer, eg move the cursor, insert
X deleted text, unmark area, etc. If the previous operation
X on the buffer was a macro, or a complex operation, eg
X global translate, then all the buffer modifications
X performed are undone in one step.
X
X If move is specified and is non-zero, then the undo
X command undoes all buffer operations back upto the last
X buffer modification. If the last command was a buffer
X modification, then setting move to non-zero is equivalent
X to not specifying it. If the last few operations were
X simply cursor movements, then move goes back to the last
X point in the buffer where the buffer was actually modified.
X
X There is a separate undo stack for each buffer. Normally
X when a buffer is written away the undo stack is discarded
X so that it is not possible to undo any operations
X performed on the buffer before the last (write_buffer)
X operation. If write_mark is specified and is non-zero,
X then this allows the undo to go back past the last
X (write_buffer) mark.
X
X Unlike BRIEF, it is possible to call (undo) from within a
X macro, but its use their is highly dubious. It is normally
X called by the user directly from one of the key assignments.
X
X The redo parameter indicates whether a redo operation
X should be performed. If it is specified then a redo is
X performed, otherwise an undo is performed. A redo
X operation allows an undo to be undone.
X.HU unregister_macro
XSYNOPSIS: (unregister_macro n macro [local])
X
XRETURN VALUE:
X
X Zero if macro was not registered; 1 if macro was
X registered and has now been unregistered.
X
XDESCRIPTION:
X
X This macro is used to remove a macro which has been
X registered for a particular trigger. (See (register_macro)
X for a description of the triggers).
X
X If a particular macro has been registered more than once
X then (unregister_macro) should be called for each register
X of the macro. (The return from (unregister_macro) can be
X used in a loop).
X
X If local is set to 1, then the macro will be unregistered
X only if it was registered as a local macro. If it is
X omitted or not equal to 1 then both the local and global
X registered macro will be unregistered.
X
XEXAMPLES:
X
X The following unregisters all occurences of a macro:
X
X (while (> (unregister_macro trigger "macro_name") 0)
X (nothing))
X.HU up
XSYNOPSIS: (up [n])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro moves the cursor to the previous line in the
X buffer, maintaining the same column position. If n is
X specified then the cursor is moved to the n'th previous or
X n'th following (if n < 0) line.
X.HU upper
XSYNOPSIS: (upper string)
X
XRETURN VALUE:
X
X Returns a copy of string with all lower case letters
X mapped to their upper case equivalents.
X.HU use_local_keyboard
XSYNOPSIS: (use_local_keyboard kbd_id)
X
XRETURN VALUE:
X
X Returns 0 if operation successful; -1 if kbd_id is not a
X valid keyboard id.
X
XDESCRIPTION:
X
X This macro is used to associate a keyboard map with the
X current buffer. The local keyboard map takes precedence
X over the global keyboard map. Whenever this buffer is
X selected, the local keyboard map is searched for key
X bindings first; if there is no key binding for the key
X typed by the user, then the global keyboard map is
X searched as usual.
X
X kbd_id is the identifier of the keyboard as returned via
X (inq_keyboard).
X
X Local keyboards are usually used to effect things like
X language sensitive editing modes, eg in C mode, the braces
X '{' and '}' may be associated with a macro to perform C
X style indenting; obviously it is not a good thing to
X perform C style indenting on an nroff text buffer. Using
X local keyboards avoids macros being complicated by having
X to check the buffer type each time, and also make CRISP
X run faster.
X.HU use_tab_char
XSYNOPSIS: (use_tab_char yes)
X
XRETURN VALUE:
X
X Returns the previous value of the use tab char toggle.
X
XDESCRIPTION:
X
X This macro allows the user to specify whether hard or soft
X tabs should be used. yes is a string expression which
X should be set to "y" if tabs are to be physically inserted
X into the buffer; otherwise spaces are used instead to fill
X up to the next tab stop.
X
SHAR_EOF
chmod 0644 help/crisp/prim/U.cmd || echo "restore of help/crisp/prim/U.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/W.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/W.cmd &&
X.HU wait
XSYNOPSIS: (wait [status])
X
XRETURN VALUE:
X
X Returns -1 if there is no process attached to the current
X buffer.
X
XDESCRIPTION:
X
X This macro waits for the process attached to the current
X buffer to die. When the process dies, if status has been
X specified (the name of an integer variable), then the exit
X status of the process is placed in it.
X
X In order to avoid a situation where CRISP might hang
X waiting for the process to die, wait's can be interrupted
X by pressing any key on the keyboard. This can be
X classified as a bug, as pressing the interrupt character
X (default ^Y) would be a better solution.
X.HU wait_for
XSYNOPSIS: (wait_for [timeout] expr)
X
XRETURN VALUE:
X
X Returns -1 if there is no process currently attached to
X the current buffer, or user interrupted wait. Returns 1 if
X expr is a string expression and the expression matched;
X returns n if expr is a list and atom n matched.
X
XDESCRIPTION:
X
X This macro is used to wait for a sequence of characters to
X be output by the sub-process attached to the current
X buffer. timeout specifies how long to wait (in seconds)
X and if omitted or zero, the wait occurs indefinitely.
X
X expr is either a string expression, representing a regular
X expression of what is to be waited for, or a list of
X regular expressions. If it is a list, then a parallel
X match is performed as each character is read from the
X buffer. If any of the atoms in the list (all string
X constants) match the characters from the stream then
X (wait_for) terminates.
X
X This macro is used by the various process control macros
X to wait for magic strings, eg shell prompts.
X
XEXAMPLES:
X
X See dial.m and shell.m for examples of how to use (wait_for).
X.HU watch
XSYNOPSIS: (watch ...)
X
XRETURN VALUE:
X
XDESCRIPTION:
X
X This macro currently is a no-op. It is intended to allow
X macros to be written which allow other macros to be
X debugged. The idea is that a macro can monitor any
X variable to see if it gets changed. The code does not
X exist, and the ideas have not been thoroughly thought out
X yet.
X
X This may be supported in a later version of CRISP if there
X is sufficient demand.
X.HU while
XSYNOPSIS: (while expr [list])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to implement a while-loop. The
X expression expr is evaluated and if non-zero, the
X statements in list are evaluated. Afterwards, expr is
X tested again. This continues until either a (break)
X statement is encountered in list, or the expression
X evaluates to false.
X.HU window_color
XSYNOPSIS: (window_color [color])
X
XRETURN VALUE:
X
X Returns previous background color of window.
X
XDESCRIPTION:
X
X This macro is used to set the color of the background
X associated with a window, and is used only when borders
X are turned off.
X
X This macro is currently not implemented.
X.HU write_block
XSYNOPSIS: (write_block [filename] [append])
X
XRETURN VALUE:
X
X Zero or less if the macro was unsuccessful. Greater than
X zero if the write was successful.
X
XDESCRIPTION:
X
X This macro is used to write out the currently marked
X region to a file. If filename is not specified, then it is
X prompted for.
X
X Writing out a marked region does not affect the backup
X flag or the undo information flag. (See (undo),
X (set_backup)).
X
X The currently marked region is raised.
X
X If append is specified and is non-zero, then the marked area
X is appended to the file.
X.HU write_buffer
XSYNOPSIS: (write_buffer [filename] [append])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to write out the contents of the
X current buffer to a file. If filename is omitted then the
X file is written to the filename associated with the
X current buffer (ie, as specified via create_buffer).
X Otherwise filename is used.
X
X If this is the first time that write_buffer has been
X called for this buffer, then a backup copy of the file
X will be made. (See the section on making backups for a
X discussion of the algorithm used). Subsequent calls to
X write_buffer do not create backups.
X
X If append is specified and is non-zero, then the output file
X is appended to.
X
SHAR_EOF
chmod 0644 help/crisp/prim/W.cmd || echo "restore of help/crisp/prim/W.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/F.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/F.cmd &&
X.HU file_pattern
XSYNOPSIS: (file_pattern filespec)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used in conjunction with the (find_file)
X macro to implement a directory lookup mechanism.
X
X filespec is a string expression which should evaluate to a
X file name or a wild-card filename. (find_file) can then be
X used to read the filenames of files which match the
X file-spec.
X
XEXAMPLES:
X
X See example in (find_file) for an example of how to
X iterate through all files in the current directory.
X.HU find_file
XSYNOPSIS: (find_file [name] [size] [mtime] [ctime] [mode])
X
XRETURN VALUE:
X
X Returns zero if there are no more files; returns 1 if next
X directory entry successfully received.
X
XDESCRIPTION:
X
X (find_file) is used in conjunction to evaluate filenames
X in a particular directory. The base directory and
X wild-card filename pattern are set via (file_pattern).
X Thereafter (find_file) can be called repeatedly, until it
X fails, receiving the next file name which matches the
X pattern set in (file_pattern).
X
X name is an optional name of a string variable, which
X receives the filename which matched the pattern if the
X (find_file) was successful. size is the size of the file
X (in bytes), and is an integer variable. mtime and ctime
X are the names of integer variables and receive the last
X modification and creation times, as returned by the Unix
X stat() system call. mode is the file mode as returned by
X stat(), and should be the name of an integer variable.
X
X There are two hash-defines in crisp.h which define two of
X the bit definitions for the mode field. These definitions
X are taken from the /usr/include/sys/stat.h file. If you
X use these #define's be careful to ensure they are
X compatible with your Unix system.
X
X For a more thorough example of the use of these
X primitives, see the abbrev.m macro file.
X
XEXAMPLES:
X
X The following example evaluates the names of all files in
X the current directory and inserts the names and mode
X information into the current buffer.
X
X (string name)
X (int mode size)
X
X (file_pattern "*")
X (while (> (find_file name size NULL NULL mode) 0) (
X (sprintf buf "file=%s, size=%d, mode=%x\n"
X name size mode)
X (insert (+ buf "\n"))
X ))
X.HU first_time
XSYNOPSIS: (first_time)
X
XRETURN VALUE:
X
X 1 if this is the first time a macro has been called; 0
X otherwise.
X
XDESCRIPTION:
X
X CRISP maintains an internal 'first_time' flag for every
X macro; after the first call to the macro, the flag is set
X to FALSE. This makes it easier for macros to perform a
X once-only initialisation.
X
SHAR_EOF
chmod 0644 help/crisp/prim/F.cmd || echo "restore of help/crisp/prim/F.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/O.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/O.cmd &&
X.HU output_file
XSYNOPSIS: (output_file [filename])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to change the filename associated with
X the current buffer. By default the filename associated
X with the current buffer is the filename specified on an
X (edit_file) or (create_buffer) call. (output_file) allows
X this to be changed to the value of the string expression,
X filename.
X
X If filename is omitted, then the user is prompted for the
X new file name.
X
SHAR_EOF
chmod 0644 help/crisp/prim/O.cmd || echo "restore of help/crisp/prim/O.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/K.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/K.cmd &&
X.HU key_to_int
XSYNOPSIS: (key_to_int key)
X
XRETURN VALUE:
X
X Returns an integer representing the internal key code
X assigned to the ascii key code, key.
X
XDESCRIPTION:
X
X This function is the inverse of int_to_key. It takes a
X keycode description in canonical form (ie compatible with
X (assign_to_key)) and returns the internal keycode.
SHAR_EOF
echo "End of part 6"
echo "File help/crisp/prim/K.cmd is continued in part 7"
echo "7" > s2_seq_.tmp
exit 0
--
===================== Reuters Ltd PLC,
Tel: +44 628 891313 x. 212 Westthorpe House,
UUCP: fox%marlow.uucp@idec.stc.co.uk Little Marlow,
Bucks, England SL7 3RQ