allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) (06/11/89)
Posting-number: Volume 7, Issue 25
Submitted-by: fox@marlow.UUCP (Paul Fox)
Archive-name: crisp1.9/part05
#!/bin/sh
# this is part 4 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file help/crisp/prim/C.cmd continued
#
CurArch=4
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/C.cmd"
sed 's/^X//' << 'SHAR_EOF' >> help/crisp/prim/C.cmd
X expression list_expr.
X
X Since lists may contain any data type, it is probably wise
X to assign the result of a car operation to a polymorphic
X variable, so that its type can be ascertained.
X
XEXAMPLES:
X
X The following example prints a message saying what type
X the variable at the head of a list is:
X
X (list llist)
X (message "Type is %s." (typeof (car llist)))
X.HU cd
XSYNOPSIS: (cd [path])
X
XRETURN VALUE:
X
X 0 if unsuccessful; non-zero if path changed.
X
XDESCRIPTION:
X
X This macro changes the current working directory. If path
X is omitted, then the current path is displayed on the
X status line.
X
XEXAMPLES:
X
X Display current path on screen:
X
X (cd)
X
X Change to users home directory:
X
X (cd (inq_environment "HOME"))
X.HU cdr
XSYNOPSIS: (cdr list_expr)
X
XRETURN VALUE:
X
X Returns the list formed by deleting the first element of
X the list, list_expr.
X
XDESCRIPTION:
X
X The (cdr) macro is used to create a new list out of an
X existing list by removing the first atom in the list.
X
X Using (car) and (cdr), macros can be written which
X manipulate all elements on a list. However, it is more
X efficient to use (nth) to extract individual elements,
X since internally it avoids having to copy sub-lists.
X.HU change_window
XSYNOPSIS: (change_window [direction])
X
XRETURN VALUE:
X
X Returns 0 if unsuccessful; 1 if successful.
X
XDESCRIPTION:
X
X This macro is used to move to another window. direction
X specifies in which direction to select the window. If it
X is omitted, then the user is prompted to select the
X window, by using the cursor keys.
X
X If direction is specified, it should have one of the
X following values:
X
X 0 Up
X 1 Right
X 2 Down
X 3 Left.
X.HU color
XSYNOPSIS: (color [background] [normal] [region] [messages]
X [errors] [hilite])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to control the colors that CRISP uses
X on a color display. (The values are ignored for monochrome
X displays).
X
X If any parameter is omitted, then the value is prompted for.
X
X background is the color for the background of normal text.
X normal is the color associated with text in the editing
X windows. region is the color of text when it is marked in
X a region. messages is the color for normal messages on the
X status line. errors is the colors for error messages on
X the status line. hilite is used to indicate the relationship
X between highlited text and its background.
X
X The colors are integers which are defined below.
X
X 0 Black
X 1 Blue
X 2 Green
X 3 Cyan
X 4 Red
X 5 Magenta
X 6 Brown (or dark yellow)
X 7 White
X 8 Dark Grey
X 9 Light Blue
X 10 Light Green
X 11 Light Cyan
X 12 Light Red
X 13 Light Magenta
X 14 Light Yellow
X 15 Light White.
X.HU command_list
XSYNOPSIS: (command_list)
X
XRETURN VALUE:
X
X Returns a list consisting of a sequence of strings which
X are the names of all the CRISP macro primitives and all
X currently defined macro names.
X
XDESCRIPTION:
X
X This macro is used to get a list of all the keywords in
X CRISP. Its primary purpose is to support the help macro
X package, and avoids hardcoding the macro primitives into a
X macro or text file.
X
X See all (macro_list).
X.HU compress
XSYNOPSIS: (compress string)
X
XRETURN VALUE:
X
X Returns a copy of string with all spaces, tabs and newlines
X mapped to single spaces.
X
XDESCRIPTION:
X
X This macro takes a string and removes all multiple white
X space characters (spaces, tabs and newlines).
X.HU connect
XSYNOPSIS: (connect [mode] [shell])
X
XRETURN VALUE:
X
X Returns 0 if buffer already connected; returns 1 if buffer
X has been successfully connected.
X
XDESCRIPTION:
X
X This macro is used to create a sub-process and associate
X it with the current buffer.
X
X mode specifies some flags which are defined below. By
X default, the process created is a shell process, and the
X shell is got from the SHELL environment variable. If shell
X is specified, then it is taken as the pathname of a shell
X to execute.
X
X Output from a sub-process is automatically inserted into
X the buffer, at a position known as the process position
X (see (inq_process_position), (set_process_position)). This
X position is analagous to the usual input cursor.
X
X Any text which would normally be inserted into the buffer
X via (self_insert), (insert) or (paste) is also forwarded
X to the sub-process.
X
X CRISP implements sub-processes out of pipes or pty's
X depending on the availability of the underlying Unix
X implementation. When using pipes, CRISP samples the output
X from the pipe on a 1 second interval. Ptys have better
X interaction since the select() system call is used.
X
X mode is a set of flags which have the following meaning:
X
X 0x01 If this bit is set, then the buffer operates in
X echo mode, ie the characters which are typed are
X inserted into the buffer. If this bit is not
X set, then the buffer operates in no-echo mode,
X and the characters the user types are not
X directly inserted into the buffer, but instead
X only the output from the sub-process.
X
X 0x8000 This is the wait mode of operation. Normally
X when a buffer is created, the output from the
X subprocess is inserted directly into the buffer.
X Setting this bit causes the output from the
X process to be held onto, until the calling macro
X issues a (wait) or (waitfor) macro call.
X
X (connect) may be called after a buffer has been connected
X to change the mode flag.
X.HU continue
XSYNOPSIS: (continue)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to finish the current iteration of a
X (while) loop, and go back to the top of the loop, causing
X the while condition to be re-evaluated.
X
X This works similar to the C continue statement.
X.HU copy
XSYNOPSIS: (copy [append])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (copy) copies the currently marked region to the scrap
X buffer, and un-highlites the currently marked region.
X
X If append is specified and is non-zero, then the text is
X appended to the current scrap without deleting it first.
X It is not currently implemented.
X.HU create_buffer
XSYNOPSIS: (create_buffer buffer-name [file-name] [system])
X
XRETURN VALUE:
X
X Returns the buffer identifier associated with the newly
X created buffer.
X
XDESCRIPTION:
X
X This macro is used to create a new buffer. The buffer is
X given the name "buffer-name" which may be any sequence of
X ASCII characters. This buffer name is used to label the
X top of any windows the buffer is attached to (see
X attach_buffer). Care should be chosen in selecting buffer
X names, since the top title on any displayed window may be
X truncated if the window is not wide enough to handle the
X title.
X
X "file-name" is the full or relative path name of a file
X which should be read into the buffer. If this parameter is
X omitted, then an initially empty buffer will be created.
X The "file-name" read into the buffer is saved for later
X use, if the buffer is saved (via write_buffer).
X
X [system] is an optional integer which indicates whether
X the buffer is to be a system buffer or user buffer. If it
X is 0 or omitted, then the buffer is a user buffer; a
X non-zero value indicates a system buffer. System buffers
X are like normal buffers, except for two side-effects - no
X (undo) information is saved for operations on system
X buffers, and most high-level macros tend to ignore system
X buffers, eg the (buffer_list) macro does not usually
X display system buffers.
X
X System buffers are for use by user macros or CRISP
X supplied macros and provide a way of storing information
X without getting in the way of the user. (undo) information
X is not saved for these buffers, and thus means that
X operations on system buffers are slightly faster than
X normal buffers. It is not important that (undo)
X information is not stored with these buffers, because
X these buffers tend to only be manipulated by the various
X macros - not directly by the user.
X
XEXAMPLES:
X
X The following example shows how to create a buffer and
X display it in the current window. (edit_file) may be more
X appropriate for this particular task, but the example is
X illustrative.
X
X (int newbuf)
X
X (= newbuf (create_buffer "My Buffer" "myfile.txt"))
X (attach_buffer newbuf)
X // Refresh screen with buffer contents.
X (refresh)
X.HU create_edge
XSYNOPSIS: (create_edge [direction])
X
XRETURN VALUE:
X
X Returns 0 if unsuccessful; 1 if successful.
X
XDESCRIPTION:
X
X This macro is used to split the current window. The window
X is split in the direction specified. If direction is not
X specified then the user is prompted, and can use the arrow
X keys to indicate the direction of the split.
X
X If direction is specified, it should have one of the
X following values:
X
X 0 Up
X 1 Right
X 2 Down
X 3 Left.
X.HU create_window
XSYNOPSIS: (create_window left_x bottom_y right_x top_y [message])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to create a new window. left_x,
X bottom_y, right_x and top_y specifies the co-ordinates of
X the window.
X
X message is an optional string expression, which if
X specified is a message to appear centered on the bottom
X line of the window.
X
X Be careful not to create windows which do not fit within
X the physical screen, otherwise CRISP may crash.
X
X The new window created becomes the current window - its id
X can be inquired via (inq_window).
X.HU cut
XSYNOPSIS: (cut [append])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X The currently highlited region is copied to the scrap
X buffer and the region deleted from the current buffer.
X
X If append is specified and is non-zero, then the highlited
X region is appended to the end of the scrap buffer, without
X first clearing it. This is not currently implemented.
SHAR_EOF
echo "File help/crisp/prim/C.cmd is complete"
chmod 0644 help/crisp/prim/C.cmd || echo "restore of help/crisp/prim/C.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/D.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/D.cmd &&
X.HU date
XSYNOPSIS: (date [year] [mon] [day] [month-name] [day-name])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro retrieves the current date. year, mon and day
X are optional integer variable names which receive the
X current year, month number, and day of month number. Year
X is of the form 1988; mon is in the range 1-12; day is in
X the range 1-31.
X
X month-name is an optional string variable, and contains
X the name of the month, in the format: January; day-name is
X an optional string variable containing the day of the
X week, in the form: Saturday.
X
XEXAMPLES:
X
X The following example can be used to print an american
X date string:
X
X (int day mon year)
X (date year mon day)
X (message "%02/%02/%02" mon day (- 1900 year))
X.HU debug
XSYNOPSIS: (debug [n])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X debug turns on or off the macro trace mode. When debug is
X on, CRISP traces the execution of every macro statement,
X and in addition traces assignments to the accumulators
X (integer, string and list).
X
X This is the primary means of debugging macros.
X
X If n is omitted, then debugging is toggled and a message
X is printed on the status line saying whether debug is on
X or off.
X
X By default, debug toggles between 0 and 1. By specifying a
X value for the debug macro, other events in CRISP can be
X traced. The other bits are mostly for debugging CRISP
X itself, and include the ability to trace the following:
X
X 0x01 Trace macro execution.
X 0x02 Trace regular expression parsing.
X 0x04 Trace buffer (undo) information.
X 0x08 Turns on tracing for the prompt history code.
X
X When debug is turned on, all debug output is put in the
X file 'crisp.log'. There is no way to change the name of
X this file at present. When the debug is turned on, any
X existing crisp.log file is truncated.
X
X If the user is trying to debug a macro which causes CRISP
X to core dump, then CRISP should be run with the -f flag.
X This causes all debug info to be flushed to the log file
X as it is produced, rather than using the stdio buffering.
X By default this is off, since it significantly slows CRISP
X down due to the high volume of output.
X
XEXAMPLES:
X
X The following is a small trace of debug output caused by
X reformatting this paragraph with the ^F key.
X
X KEY_EXEC: objects format_block
X (objects "format_block" )
X Execute macro: objects
X 02:.......(string ext function macro_name )
X (int arg1 )
X (get_parm 0 function )
X function := 'format_block'
X (get_parm 1 arg1 )
X ACC = 0
X (inq_names NULL ext NULL )
X (assign_to_key "^N" "objects next_error" )
X (assign_to_key "^P" "objects previous_error" )
X (= macro_name (..) )
X (+ ext (..) )
X lookup ext -> "cmd"
X (+ "-" function )
X lookup function -> "format_block"
X SACC = '-format_block'
X SACC = 'cmd-format_block'
X macro_name := 'cmd-format_block'
X SACC = 'cmd-format_block'
X (if (..) (..) )
X (! (..) )
X (inq_macro macro_name )
X lookup macro_name -> "cmd-format_block"
X ACC = 0
X ACC = 1
X (= macro_name (..) )
X (+ "default-" function )
X lookup function -> "format_block"
X SACC = 'default-format_block'
X macro_name := 'default-format_block'
X SACC = 'default-format_block'
X SACC = 'default-format_block'
X (execute_macro macro_name arg1 )
X lookup macro_name -> "default-format_block"
X.HU declare
XSYNOPSIS: (declare var1 var2 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to define one or more polymorphic
X variables. Polymorphic variables are variables that may
X take on any of the available CRISP data types (integer,
X string or list), depending on context.
X
X Polymorphic variables are most useful when dealing with
X lists which contain unknown data types.
X
X The variables declared are made into local variables,
X unless a (global) declaration follows.
X
X By default, polymorphic variables are typed as integers,
X and are given the value zero.
X.HU del
XSYNOPSIS: (del filename)
X
XRETURN VALUE:
X
X Zero or less if unsuccessful; greater than zero means the
X file was successfully deleted.
X
XDESCRIPTION:
X
X This macro is used to delete a file, as specified by the
X string expression 'filename'.
X
X Wild-cards, etc, are not valid in 'filename'.
X.HU delete_block
XSYNOPSIS: (delete_block)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X The currently highlited block is deleted.
X.HU delete_buffer
XSYNOPSIS: (delete_buffer bufnum)
X
XRETURN VALUE:
X
X No value is returned.
X
XDESCRIPTION:
X
X This command deletes the buffer specified by bufnum. The
X entire buffer contents are freed, and any other resources
X attached to that buffer are destroyed as well. In the case
X of a process buffer, the subprocess is killed.
X
X Any attempt to (set_buffer) to a buffer which has been
X deleted will fail.
X
X Care should be taken with (delete_buffer) since no tests
X are made to see if the buffer being deleted is currently
X displayed. If a currently displayed buffer is deleted,
X then CRISP may core-dump. Macros using (delete_buffer)
X should be carefully tested to ensure this does not happen,
X eg by calling (inq_views).
X
XEXAMPLES:
X
X The following example creates a temporary buffer and then
X deletes it after restoring the current buffer at the time
X of the macro is invoked.
X
X (int newbuf)
X (int curbuf)
X
X (= curbuf (inq_buffer))
X (= newbuf (create_buffer "Example" NULL 1))
X (set_buffer newbuf)
X .
X .
X
X (set_buffer curbuf)
X (delete_buffer newbuf)
X.HU delete_char
XSYNOPSIS: (delete_char [num])
X
XRETURNS:
X Nothing.
X
XDESCRIPTION:
X
X This macro deletes one or more characters from the current
X buffer. If num is not specified, then 1 character is
X deleted; if num is specified then that number of
X characters are deleted. The deleted characters are on and
X to the right of the current buffer position.
X
X This macro is the default assignment for the <Delete> key
X on the keyboard.
X.HU delete_edge
XSYNOPSIS: (delete_edge [direction])
X
XRETURN VALUE:
X
X Returns <= 0 if unsuccessful; >0 otherwise.
X
XDESCRIPTION:
X
X This macro can be used to delete a window on-screen. It is
X used by specifying an edge, and if there is another window
X which adjoins the edge, then the edge is deleted and the
X two windows combined into one.
X
X direction specifies the edge to delete and if not
X specified, is prompted for, and the user can use the arrow
X keys to specify the edge.
X
X When using this macro, the edge to be deleted must not be
X obscured by other edges, ie only tiled window support is
X allowed for this macro.
X
X If direction is specified, it should have one of the
X following values:
X
X 0 Up
X 1 Right
X 2 Down
X 3 Left.
X.HU delete_line
XSYNOPSIS: (delete_line)
X
XRETURNS:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro deletes the line the cursor is currently on.
X The cursor is placed at the same column position in the
X line below the one deleted.
X
XEXAMPLES:
X
X The following example assigns the (delete_line) macro to
X the <ALT-D> key (the usual case).
X
X (assign_to_key "<Alt-D>" "delete_line")
X.HU delete_macro
XSYNOPSIS: (delete_macro [file])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to delete all macros which were loaded
X from a particular macro file. file is a string expression
X and if omitted is prompted for, containing the name of the
X file.
X
X This is currently a no-op in CRISP - macros are not
X deleteable entities. The storage allocated for a macro is
X lost when a macro by the same name is loaded from
X another file.
X.HU delete_to_eol
XSYNOPSIS: (delete_to_eol)
X
XRETURNS:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro deletes all characters up to the end of the
X line in the current buffer.
X.HU delete_window
XSYNOPSIS: (delete_window)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro can be used to delete the current window. It
X can be used on overlapping or tiled windows (unlike BRIEF
X which limits (delete_window) to overlapped windows only).
X
X Another window should be selected (via (set_window))
X before trying to refresh the screen, otherwise CRISP may
X crash.
X.HU disconnect
XSYNOPSIS: (disconnect)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to kill a sub-process attached to a
X buffer. The subprocess is sent a SIGTERM followed by a
X SIGKILL signal.
X.HU display_mode
XSYNOPSIS: (display_mode [mode])
X
XRETURN VALUE:
X
X Returns previous value of display mode.
X
XDESCRIPTION:
X
X The display mode is a special mode for use on terminals
X which cannot display characters with the top bit set. The
X mode defines whether these characters should be displayed
X in octal or hexadecimal. Octal characters appear as a
X backslash followed by three octal digits. Hex characters
X appear as a backslash followed by an 'x' followed by two
X hex digits.
X
X The default is hexadecimal.
X
X If mode is 1, then the mode is set to hexadecimal. If 2,
X then octal.
X.HU distance_to_tab
XSYNOPSIS: (distance_to_tab)
X
XRETURNS:
X
X Number of characters between current cursor location and
X next tab stop.
X
XDESCRIPTION:
X
X This macro returns the number of characters between the
X current cursor location and the next tab stop, even if
X there are no more characters after the cursor. This number
X will always be > than zero.
X
X If the cursor is on a tab stop, then the number of
X characters to the next tab stop are returned.
X.HU dos
XSYNOPSIS: (dos [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 macro exists for compatability with BRIEF; please see
X the (shell) command for further information.
X.HU down
XSYNOPSIS: (down [lines])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor to the same column on the line below. If
X lines is specified then cursor is moved to the lines'th
X line after the current. lines may be negative in which
X case the cursor moves backwards.
X.HU drop_anchor
XSYNOPSIS: (drop_anchor [type])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to define a region within the current
X buffer. type specifies the type of region, and the values
X are given below. If omitted a normal marked region is
X selected.
X
X Regions are areas of a buffer upon which some macros have
X special effects, eg (cut) and (copy) are used to extract
X fragments of buffers and save them for later re-insertion.
X The (search_fwd) and (search_back) macros can be told to
X limit their searches to the highlited regions, etc.
X
X Regions are displayed on screen either in a different
X color, or in reverse video so that they stand out.
X
X The following are the different region types:
X
X 1 Normal
X 2 Column
X 3 Line
X 4 Non-inclusive.
X
X A normal mark is a region which encompasses from the place
X where the anchor was dropped upto and including the
X current cursor position. A non-inclusive mark is the same
X but does not include the current cursor position.
X
X A line mark selects entire lines, and allows for easy
X movement of text from one part of a buffer to another.
X
X A column mark is similar to a normal mark, except it
X displays differently on screen, and allows rectangular
X sections of the current buffer to be marked.
X
X The currently selected marked area can be found, via
X (inq_marked). Column operations are not directly supported
X by CRISP internally, but instead are supported by the
X macros supplied with CRISP.
X
X Regions are nestable, ie multiple (drop_anchor)'s can be
X issued without any intervening (raise_anchor).
X
X The marked region can be cleared by calling (raise_anchor)
X or performing a (copy) or (cut) operation on the buffer.
X.HU drop_bookmark
XSYNOPSIS: (drop_bookmark [book_num] [yes] [buf] [line] [col])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to set a bookmark. A bookmark is like a
X normal bookmark - it is a place holder in a buffer.
X book_num specifies the bookmark number 1-10; yes is a
X string which is ignored.
X
X If buf, line & col are non-NULL, then bookmark book_num is
X set to the specified buffer at the designated line and
X column position. If buf, line or col are NULL then the
X bookmark is set from the current buffer, line and column
X position.
SHAR_EOF
chmod 0644 help/crisp/prim/D.cmd || echo "restore of help/crisp/prim/D.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/E.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/E.cmd &&
X.HU echo_line
XSYNOPSIS: (echo_line [flags])
X
XRETURN VALUE:
X
X Previous value of flags.
X
XDESCRIPTION:
X
X The (echo_line) macro is used to control which fields are
X visible in the status line. If flags is omitted then the
X current setting is returned.
X
X flags is an integer expression, whose bit pattern is
X interpreted as follows:
X
X 0x01 Line: field enabled.
X 0x02 Col: field enabled.
X 0x04 Percentage through file enabled.
X 0x08 Current time enabled.
X 0x10 REmember/PAuse reminders enabled.
X 0x20 Cursor type displayed.
X
X The cursor type is only used if the screen cannot change
X the cursor type to indicate insert/overtype and
X normal/virtual space.
X
X.HU edit_file
XSYNOPSIS: (edit_file [file1] [file2] ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is the usual way of editing a file; if a buffer
X is already allocated for the file, then that is set as the
X current buffer. Otherwise a new buffer is created, the
X contents of the named file are read into that, and the
X filename is associated with that buffer (so that later on
X a (write_buffer) can be used to save any changes made to
X the buffer).
X
X This macro supports wild-cards and the ability to edit
X multiple files at once. If more than one argument is
X specified, then a separate (edit_file) is performed on
X each file, and the current buffer is set to the last file
X read in.
X
X The normal c-shell wildcards are supported:
X
X * wild-card -- matches any number of characters.
X ? wild-character -- matches any single character.
X [l-m] any character in range at this character.
X ~/ as first part of filename matches home directory
X ~user/ matches 'user's home directory.
X
X If no filenames are specified, the user is prompted for a
X filename.
X
XEXAMPLES:
X
X The following example can be used to read in all .c files
X in the current directory:
X
X (edit_file "*.c")
X.HU ega
XSYNOPSIS: (ega [mode])
X
XRETURN VALUE:
X
X Previous value of EGA mode.
X
XDESCRIPTION:
X
X This macro can be used to toggle between EGA 25 line mode
X and EGA 43 line mode -- only if CRISP is running under
X Unix V.3.2 or above on an EGA console.
X
X If mode is not specified, then only the current EGA state
X is returned.
X.HU enable_display
XSYNOPSIS: (enable_display [enable])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to enable the display. By default when
X CRISP starts up, the code for updating the screen is
X disabled. The startup macros initialise CRISPs internal
X character translation tables and then call this macro to
X allow CRISP to proceed.
X
X If enable is not specified, then the current value is
X toggled. If it is non-zero, then the display is enabled.
X
X If the display is not enabled, then CRISP can be used as a
X normal programming language, in the style of awk and sed,
X using the command line arguments to load and execute a file.
X.HU end_of_buffer
XSYNOPSIS: (end_of_buffer)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor to the end of the last line in the
X current buffer.
X.HU end_of_line
XSYNOPSIS: (end_of_line)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor to the end of the current line.
X.HU end_of_window
XSYNOPSIS: (end_of_window)
X
XRETURN VALUE:
X
X Returns 1 if cursor moved; 0 if cursor stayed in the same
X position.
X
XDESCRIPTION:
X
X Moves the cursor to the last line of the window. The
X cursor stays in the same column position.
X.HU error
XSYNOPSIS: (error fmt [arg1] [arg2] ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to print a message on the status
X (prompt) line. fmt is a string with possible embedded
X printf-like % options. arg1, arg2, .. are optional
X arguments (upto 4 parameters) which either evaluate to
X strings or integer values.
X
X The % options are the same as for the underlying printf()
X which the system supports. (Internally the string coding
X is handled by sprintf). Please see the description of the
X (message) macro for a list of the minimum supported set of
X % options.
X
X This macro is similar to (message) except that the message
X string is classified as an error. Error messages are
X printed in the error color (see (color)).
X
X In addition, if the pause_on_error flag has been set (see
X (pause_on_error)) then the error message is displayed
X suffixed with a '..' and CRISP waits for the user to type
X any key to continue. This is useful in debugging.
X
X Error messages are truncated if they are too long.
X
XEXAMPLES:
X
X (string mac)
X (= mac "fred")
X (error "Macro %s not loaded." mac)
X ; displays the message 'Macro fred not loaded.')
X
X (error "%02d/%02d/%02d" 2 25 88)
X ; displays '02/25/88'
X.HU execute_macro
XSYNOPSIS: (execute_macro [macro] [args])
X
XRETURN VALUE:
X
X Returns the value of (macro args).
X
XDESCRIPTION:
X
X This macro is used to execute another macro. It is needed
X because it is the only way to execute a macro which is
X defined by a string expression, rather than by virtue of
X the CRISP language syntax.
X
X macro should be a string expression and if omitted is
X prompted for; args are optional and are the arguments
X passed to the macro.
X.HU exist
XSYNOPSIS: (exist filename)
X
XRETURN VALUE:
X
X Non-zero if filename exists; zero if file does not exist.
X
XDESCRIPTION:
X
X Checks for existence of file. The existence of the file is
X performed by doing a stat() call on the named file.
X Therefore this can be used for all file types (including
X character/block devices, etc).
X.HU exit
XSYNOPSIS: (exit)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to exit from CRISP, or from a recursive
X (process) macro invocation.
X
X If called at the bottom level of CRISP, CRISP goes through
X its exit procedure and prompts the user if he/she is sure,
X if there are any buffers which have been modified.
X
X If called from within a nested invocation of (process), on
X the next attempt to read keyboard input the calling
X (process) macro will return.
X
X Note that CRISP currently does not support the
X [are_you_sure] option which BRIEF supports.
X.HU extern
XSYNOPSIS: (extern var1 var2 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X The extern macro is provided for compatability with BRIEF.
X In CRISP it does not do anything.
X
X In BRIEF it is used so that global variables defined in
X other macro source files can be referenced without
X resulting in undefined symbol reference errors.
X
X CRISP does not check for the availability of a symbol
X until it is actually referenced at run-time.
SHAR_EOF
chmod 0644 help/crisp/prim/E.cmd || echo "restore of help/crisp/prim/E.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/G.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/G.cmd &&
X.HU get_parm
XSYNOPSIS: (get_parm [arg] var [prompt] [length] [default])
X
XRETURN VALUE:
X
X Zero if user aborted prompt, or argument number does not
X exist. Greater than zero if successful.
X
XDESCRIPTION:
X
X (get_parm) is the mechanism for accessing parameters
X passed to macros. (get_parm) can also be used to prompt
X the user for input, and possibly specify a default value.
X
X Arguments passed to macros are numbered, zero upwards. If
X arg is specified, then it is evaluated to the value of the
X argument number to be retrieved. If it is NULL, then the
X user is prompted for the value, in which case prompt is
X the message to prompt the user, and default (if specified)
X is the default value which the user can then edit, using
X the command line editing. If length is specified, it is
X the maximum number of characters in the user's input
X (usually used only for string variables). The users input
X is terminated by hitting <Enter> or reaching the length.
X
X var is the name of an integer, string or list variable. If
X the user is being prompted, then only integer and string
X expressions may be input. List expressions are not
X supported.
X
X Arguments passed to macros are passed as call by name, ie
X every time a (get_parm) is issued on a particular
X parameter, that parameter is re-evaluated. This can be
X very useful sometimes, and at other times it can cause
X anomalous side-effects.
X
X.HU get_term_characters
XSYNOPSIS: (get_term_characters [top_left] [top_right]
X [bot_left] [bot_right]
X [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 can be used to find out the current settings
X for the various characters which make up the special
X characters needed to display the window borders on the
X screen.
X
X Each parameter is the name of a string variable to receive
X the string expression. Any of the parameters may be omitted.
X
X This macro is designed to allow macros to be written which
X make it easier for the user to tailor the display.
X
X Refer to (set_term_characters) for further detail on the
X meaning of each of these characters.
X.HU get_term_features
XSYNOPSIS: (get_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 retrieve the terminal options which
X the current display supports. All the parameters are the
X names of string variables, except for zerom and color
X which are the names of integer variables.
X
X Refer to (set_term_features) for a description of the
X meaning of each feature.
X
X This macro is designed to be used to allow macros to be
X written which allow the user to easily tailor his/her
X display environment.
X.HU get_term_keyboard
XSYNOPSIS: (get_term_keyboard ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is designed to allow the calling macro retrieve
X the assignments for each key, so that a user interface can
X be written to examine and display the key bindings.
X
X See (set_term_keyboard) for more details of how this macro
X is supposed to work.
X
X This macro has not been currently implemented.
X.HU getpid
XSYNOPSIS: (getpid)
X
XRETURN VALUE:
X
X Returns the current process ID (as returned via getpid()).
X
XDESCRIPTION:
X
X This function exists to allow macros to be written which
X need to generate unique filenames. The process ID can be
X embedded in temporary filenames to avoid clashes with any
X other users running CRISP.
X
XEXAMPLES:
X
X The following example generates a filename for a temp file
X in the /tmp directory.
X
X (string filename)
X (sprintf filename "/tmp/gr.xx%05d" (getpid))
X.HU global
XSYNOPSIS: (global var1 var2 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X The global macro is used to make local variables into
X global variables. Local variables are destroyed when the
X macro executing them terminates. Global variables maintain
X their value across macro invocation and occupy permanent
X static storage.
X
X A variable must have been specified in a previous (int),
X (string), (list) or (declare) statement before it can be
X made into a global.
X.HU goto_bookmark
XSYNOPSIS: (goto_bookmark [book_no] [bufnum] [line] [col])
X
XRETURNS:
X
X 1 if macro was successful; 0 if bookmark invalid or prompt
X was aborted.
X
XDESCRIPTION:
X
X book_no is an integer; bufnum, line & col are (optional)
X names of integer variables.
X
X This macro is used to move the cursor to a previously
X saved bookmark. If bufnum, line & col are all NULL or
X omitted, then the buffer and cursor information associated
X with book_no are selected.
X
X If any of bufnum, line or col are specified, then these
X variables are modified to have that information associated
X with the designated bookmark.
X
X If book_no is omitted, then the user will be prompted for
X the bookmark number to go to.
X
XEXAMPLES:
X
X The following example gets the buffer, line & col
X associated with bookmark 5.
X
X (int buf line col)
X (goto_bookmark 5 buf line col)
X
X The following example jumps to bookmark 5:
X
X (goto_bookmark 5)
X.HU getwd
XSYNOPSIS: (getwd ignored dir)
X
XRETURN VALUE:
X
X Returns 1.
X
XDESCRIPTION:
X
X This function returns the current directory in the string
X variable dir. The ignored parameter exists for
X compatability with BRIEF which allows the calling macro to
X specify the drive for the directory. Unix does not support
X the concept of multiple current directories, and so is
X ignored.
X.HU goto_line
XSYNOPSIS: (goto_line [line])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor to the beginning of the specified line.
X If line is omitted it is prompted for.
X.HU goto_old_line
XSYNOPSIS: (goto_old_line [line])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X When a file is read into a buffer, each line is internally
X numbered. These internal line numbers are maintained even
X if lines are inserted and deleted from the buffer.
X (goto_old_line) moves the cursor to the line whose
X original line number was line, or as near as possible if
X the original lines have been deleted.
X
X This macro gets over the problem of editing a source file
X to correct compilation errors, and the lines with errors
X moving as text is inserted or deleted.
X
X If line is omitted, it is prompted for.
X
SHAR_EOF
chmod 0644 help/crisp/prim/G.cmd || echo "restore of help/crisp/prim/G.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/I.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/I.cmd &&
X.HU if
XSYNOPSIS: (if expr [true-list] [false-list])
X
XRETURN VALUE:
X
X Returns value of true-list if expr is true, otherwise
X value of false-list.
X
XDESCRIPTION:
X
X The expression 'expr' is evaluated, and if it is non-zero
X (true), the list expression 'true-list' is evaluated; if
X expr is false, then 'false-list' is evaluated. true-list
X and false-list are optional, in which case the result of
X the (if) expression is undefined if they are omitted.
X.HU index
XSYNOPSIS: (index search-string pattern)
X
XRETURN VALUE:
X
X Returns 0 if pattern cannot be found in search-string;
X otherwise returns the position pattern starts at in
X search-string.
X
XDESCRIPTION:
X
X This function is used to see whether search-string
X contains the substring pattern. A literal substring match
X is performed. This function returns the place in
X search-string where pattern has been located or 0 if it
X does not occur in the search-string.
X
X If the user needs to search for regular expressions, then
X the function search_string should be used instead.
X
XEXAMPLES:
X
X The following example checks to see if a string is a lower
X case alphabetic character:
X
X (string letter)
X .
X .
X (if (== (index "abcdefghijklmnopqrstuvwxyz" letter) 0)
X (message "%c is upper case." letter)
X ;else
X (message "%c is lower case." letter)
X.HU inq_assignment
XSYNOPSIS: (inq_assignment key [convert])
X
XRETURN VALUE:
X
X Returns the name of a macro assigned to a keystroke or the
X name of a keystroke assigned to a macro.
X
XDESCRIPTION:
X
X This macro can be used to find out what macro a particular
X keyboard character is assigned to, or to which key or keys
X a particular macro is assigned to.
X
X key maybe a string denoting the key sequence to be decoded
X or an integer representing the internal key code. If key
X is a string then it should be of the form described under
X (assign_to_key).
X
X convert is an integer expression; if omitted or zero, then
X key is treated as a keyboard character (as defined for
X (assign_to_key)), and the name of the macro assigned to
X that keystroke is returned. If the character is not
X assigned to a macro, and the character is inserted into
X the buffer when the user hits it, then the string
X "self_insert" is returned. If there is no key assignment
X for that key, then "nothing" is returned.
X
X If convert is specified and is non-zero, then 'key' is
X taken as the name of a macro and the keys assigned to
X invoke this macro are returned. The key assignment
X returned is returned using the portable key definitions
X defined for "assign_to_key".
X
X If more than one key stroke is assigned the same macro
X invocation, then the returned string will contain the
X string "<-also>" separating the key sequences.
X
XEXAMPLES:
X
X (message "%s" (inq_assignment "help"))
X generates the message "<Alt-H>".
X.HU inq_borders
XSYNOPSIS: (inq_borders)
X
XRETURN VALUE:
X
X Returns zero if borders are off; non-zero if borders are on.
X
XDESCRIPTION:
X
X Not currently implemented.
X.HU inq_brief_level
XSYNOPSIS: (inq_brief_level)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This function exists for compatability with BRIEF. This
X macro is supposed to return the level of nesting of
X sub-shells running BRIEF/CRISP. It is not implemented in
X CRISP, since the functionality can be gained by examining
X the BLEVEL environment variable.
X.HU inq_buffer
XSYNOPSIS: (inq_buffer)
X
XRETURN VALUE:
X
X Returns the identifier associated with the current buffer.
X
XDESCRIPTION:
X
X Every buffer has an identifier (an integer value)
X associated with it. These identifiers are allocated when
X the buffer is created. (inq_buffer) can be used to get the
X identifier for the current buffer, e.g. when saving the
X current buffer in a macro, so that after the macro has
X finished the buffer selected on entry to the macro can be
X re-instated.
X
XEXAMPLES:
X
X The following example is typical of the code sequence used
X in the CRISP macros on entry and exit to each macro.
X
X (int curbuf)
X (= curbuf (inq_buffer))
X .
X .
X (set_buffer curbuf)
X.HU inq_buffer_flags
XSYNOPSIS: (inq_buffer_flags [bufnum])
X
XRETURN VALUE:
X
X Flags associated with designated buffer, or -1 if the
X designated buffer does not exist.
X
XDESCRIPTION:
X
X This macro returns the flags associated with the status of
X the current buffer (if bufnum is omitted) or the buffer
X whose identifier is bufnum.
X
X The flags returned are a set of bits with the following
X bits being defined:
X
X 0x01 Buffer has been modified.
X 0x02 Buffer will be backed up when written.
X 0x04 Buffer is read-only.
X 0x08 Reserved.
X 0x10 File permissions in underlying file has
X the 'x' (execute bit) set.
X 0x20 Buffer has a process associated with it.
X 0x40 Buffer contains a binary file.
X 0x80 Buffer in ANSI mode.
X
X.HU inq_called
XSYNOPSIS: (inq_called)
X
XRETURN VALUE:
X
X A string containing the name of the macro which called the
X current macro, or "" if the macro was called from the
X keyboard.
X
XDESCRIPTION:
X
X This macro exists so that macros can be written which need
X to differentiate between being called directly from the
X keyboard, or being called from another macro.
X
X This is especially useful when writing a (replacement)
X macro.
X.HU inq_cmd_line
XSYNOPSIS: (inq_cmd_line)
X
XRETURN VALUE:
X
X Returns the field currently being typed in by user on the
X prompt line.
X
XDESCRIPTION:
X
X This macro returns the partially typed in text which the
X user is typing on the prompt line. It is used by various
X macros to perform command completion.
X.HU inq_command
XSYNOPSIS: (inq_command)
X
XRETURN VALUE:
X
X A string containing the name of the last macro called by
X the user.
X
XDESCRIPTION:
X
X This macro can be used to find the name of the last macro
X which was invoked by virtue of it being bound to a
X keyboard key.
X.HU inq_environment
XSYNOPSIS: (inq_environment name)
X
XRETURN VALUE:
X
X Returns a string which is the contents of the named
X environment variable, or the null string if the variable
X does not exist.
X
XDESCRIPTION:
X
X This function looks up 'name' in the environment and
X returns the value of name. It is similar to the C function
X getenv().
X.HU inq_file_buffer
XSYNOPSIS: (inq_file_buffer filename)
X
XRETURN VALUE:
X
X Returns the buffer identifier of the buffer which
X currently has filename loaded; it returns 0 if the file
X filename is not loaded into buffer.
X
XDESCRIPTION:
X
X Given the filename, this macro examines all buffers to see
X if any buffer has the designated filename loaded into it,
X and if so returns the buffer identifier.
X
X This is much faster than doing an (inq_names) on each
X buffer to see which buffer contains filename.
X
X This macro is used by the (buffer_list) macro when the
X user writes or deletes a selected entry.
X
XEXAMPLES:
X
X The following example checks to see if "fox.m" is
X currently being edited and if not edit's it:
X
X (if (== (inq_file_buffer "fox.m") 0)
X (edit_file "fox.m"))
X.HU inq_idle_default
XSYNOPSIS: (inq_idle_default)
X
XRETURN VALUE:
X
X Returns the value of the idle keyboard interval timer (in
X seconds).
X
XDESCRIPTION:
X
X This function returns the interval for the idle keyboard
X interval timer. The idle keyboard interval timer is a
X timer which is started after the last keystroke. If no
X keys are hit for (inq_idle_default) seconds then the type
X 4 registered macros are called.
X
X The default idle timer is set by the '-i' command line
X switch. If it is not set on the command line explicitly,
X then CRISP uses a default value of 60 seconds.
X.HU inq_idle_time
XSYNOPSIS: (inq_idle_time)
X
XRETURN VALUE:
X
X Returns the number of seconds since the last key was pressed.
X
XDESCRIPTION:
X
X This function returns the number of seconds since the last
X key was pressed. This macro is used by the autosave macros
X to see if it is time to save the editing buffers.
X.HU inq_kbd_char
XSYNOPSIS: (inq_kbd_char)
X
XRETURN VALUE:
X
X Returns non-zero if there is a character to be read from
X the keyboard; 0 if no character is available.
X
XDESCRIPTION:
X
X This macro provides a simple way of determining whether a
X character is available to be read from the keyboard
X without actually reading it. (See (read_char)).
X.HU inq_keyboard
XSYNOPSIS: (inq_keyboard)
X
XRETURN VALUE:
X
X Returns the identifier associated with the current keyboard.
X
XDESCRIPTION:
X
X This macro may be used to find out what the current
X keyboard identifier is so that it may be restored later.
X
X See keyboard_push, keyboard_pop for further details on
X keyboard identifiers.
X.HU inq_line_length
XSYNOPSIS: (inq_line_length [bufnum])
X
XRETURN VALUE:
X
X (inq_line_length) returns the length of the longest line,
X or -1 if the specified buffer does not exist.
X
XDESCRIPTION:
X
X This command is used returns the length of the longest
X line in the specified buffer (or the current buffer if
X bufnum is omitted). The length corresponds to the column
X position the cursor would be in if the cursor were to be
X placed at the end of the longest line, ie it takes into
X account any embedded tabs and control characters, etc.
X
X If the designated buffer has a marked region, then only
X those lines within the marked region are looked at to find
X the longest line.
X
X
XEXAMPLES:
X
X The following example returns the length of the longest
X line in the current buffer in between the current line and
X the end of the buffer.
X
X # include "crisp.h"
X .
X .
X (int length)
X
X (drop_anchor MK_LINE)
X (save_position)
X (= length (inq_line_length))
X (restore_position)
X (raise_anchor)
X (message "Longest line = %d cols" length)
X.HU inq_lines
XSYNOPSIS: (inq_lines)
X
XRETURN VALUE:
X
X Number of lines in current buffer.
X
XDESCRIPTION:
X
X This macro returns the number of lines in the current
X buffer. It is faster than going to the end of the buffer
X and doing an (inq_position).
X
XEXAMPLES:
X
X Following example prints number of lines in buffer:
X
X (message "Lines = %d" (inq_lines))
X.HU inq_local_keyboard
XSYNOPSIS: (inq_local_keyboard)
X
XRETURN VALUE:
X
X The keyboard identifier associated with the current local
X keyboard, or 0 if there is no local keyboard.
X
XDESCRIPTION:
X
X This function returns the identifier of the current local
SHAR_EOF
echo "End of part 4"
echo "File help/crisp/prim/I.cmd is continued in part 5"
echo "5" > 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