allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) (06/11/89)
Posting-number: Volume 7, Issue 26
Submitted-by: fox@marlow.UUCP (Paul Fox)
Archive-name: crisp1.9/part06
#!/bin/sh
# this is part 5 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file help/crisp/prim/I.cmd continued
#
CurArch=5
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/I.cmd"
sed 's/^X//' << 'SHAR_EOF' >> help/crisp/prim/I.cmd
X keyboard; this may be needed for example if the keyboard
X is to be changed or deleted.
X
X Refer to (use_local_keyboard) and the help section "Local
X Keyboards" for more information on what a local keyboard is.
X.HU inq_macro
XSYNOPSIS: (inq_macro macro)
X
XRETURN VALUE:
X
X Non-zero if macro is a macro; zero otherwise.
X
XDESCRIPTION:
X
X This macro allows the calling macro to see if the named
X macro is defined. macro is a string expression.
X
X Passing the name of a CRISP builtin will return 0 unless
X the built-in has been redefined by a (replacement) macro.
X.HU inq_mark_size
XSYNOPSIS: (inq_mark_size)
X
XRETURN VALUE:
X
X The number of characters in the currently marked region.
X
XDESCRIPTION:
X
X This macro can be used to find out how many characters are
X in the currently marked region. This number is the string
X length of a string which would be necessary to hold the
X characters.
X.HU inq_marked
XSYNOPSIS: (inq_marked [start_line] [start_col] [end_line] [end_col])
X
XRETURN VALUE:
X
X Returns 0 if buffer does not have a region set; otherwise
X returns current region type.
X
XDESCRIPTION:
X
X start_line, start_col, end_line, and end_col are optional
X integer variables which receive the start and end
X positions of the current region.
X.HU inq_message
XSYNOPSIS: (inq_message)
X
XRETURN VALUE:
X
X Returns the message currently on the status line plus any
X type in from the user.
X
XDESCRIPTION:
X
X This macro returns any message or prompt which is
X currently displayed on the status line. It is used by the
X various command completion and abbreviation macros to see
X what command is currently executing.
X
X See also (inq_cmd_line).
X.HU inq_mode
XSYNOPSIS: (inq_mode)
X
XRETURN VALUE:
X
X Returns 1 if in insert mode; 0 if in overtype mode.
X
XDESCRIPTION:
X
X This macro returns the current state of the
X insert/overtype modes.
X.HU inq_modified
XSYNOPSIS: (inq_modified [bufnum])
X
XRETURN VALUE:
X
X Returns non-zero if current buffer has been modified; 0 if
X buffer has not been modified (or has been written away).
X
XDESCRIPTION:
X
X This macro returns a value indicating whether the current
X buffer (bufnum omitted) or the buffer specified by bufnum
X has been modified.
X
X This macro exists as a shorthand form of the
X (inq_buffer_flags) macro. It exists for compatability with
X BRIEF.
X
XEXAMPLES:
X
X The following example prints a message saying whether the
X buffer has been modified or not.
X
X (message "Buffer has %sbeen modified."
X (if (inq_modified) "" "not ")
X.HU inq_msg_level
XSYNOPSIS: (inq_msg_level)
X
XRETURN VALUE:
X
X The current value of the message level flag (0-3).
X
XDESCRIPTION:
X
X The message level flag is used to specify what level of
X error and informational messages are to be printed. This
X allows things like replacement macros to operate in a
X silent manner.
X
X To see the meanings of the different levels, refer to
X set_msg_level.
X.HU inq_names
XSYNOPSIS: (inq_names [full_name] [ext] [buf_name])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used for determining the names of the file
X and buffer associated with the current buffer. Any of the
X parameters may be omitted. All the parameters are the
X names of string variables.
X
X full_name is the full path name of the file associated
X with the buffer, and is the file which is written to when
X (write_buffer) is called; ext receives the extension (if
X any) of full_name; buf_name is the title of the buffer -
X as displayed at the top of the window when the buffer is
X attached (see attach_buffer) to a window.
X
XEXAMPLES:
X
X The following macro executes a file-dependent macro for
X setting up initialisations, etc.
X
X (string ext)
X (inq_names NULL ext)
X (execute_macro (+ ext "-init"))
X.HU inq_position
XSYNOPSIS: (inq_position [line] [col])
X
XRETURN VALUE:
X
X Returns 0 if cursor is not past end of buffer; otherwise
X it returns the number of lines past the end of the buffer.
X
XDESCRIPTION:
X
X This macro is used to find where the cursor is within the
X current buffer. line and col are the names of string
X variables which receive the current line and column number
X (both start at 1).
X
X This function returns an indication of whether the cursor
X is past the end of the buffer. In BRIEF, the cursor is
X allowed to wander beyond the last line of physical text in
X the buffer, upto one full screens worth (usually 24 or 42
X lines). CRISP doesnt support this capability at present,
X although the cursor can be moved to one line beyond the
X last line of input. Be wary of this when porting macros
X from BRIEF to CRISP.
X.HU inq_process_position
XSYNOPSIS: (inq_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 function is similar to (inq_position) but it returns
X the current cursor position for the underlying process.
X line & col are optional integer variables to receive the
X line & column, respectively.
X
X The process position is used for output from the process;
X rather than inserting the output from the process where
X the users cursor is, a separate cursor is maintained
X instead. This is done because it allows the user to move
X around the buffer whilst the process is generating output
X without the process output being sprinkled through the
X buffer.
X
X For more details of operation, look at the shell.m macro
X file.
X.HU inq_scrap
XSYNOPSIS: (inq_scrap [last_newline] [type])
X
XRETURN VALUE:
X
X Returns the buffer identifier associated with the scrap.
X
XDESCRIPTION:
X
X This macro returns various internal info about the scrap
X buffer.
X
X last_newline is an optional integer variable which is used
X to indicate whether the scrap has a newline at the end of
X the last line of the buffer (used when inserting text via
X (paste)). This is currently not implemented.
X
X type is an integer variable which receives the type of the
X marked area which was most recently copied to the scrap.
X.HU inq_screen_size
XSYNOPSIS: (inq_screen_size [lines] [cols])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X lines and cols are optional integer variables. If
X specified they receive the current dimensions of the
X physical screen.
X.HU inq_system
XSYNOPSIS: (inq_system)
X
XRETURN VALUE:
X
X Returns non-zero if the current buffer is a system buffer;
X returns 0 if the current buffer is a normal buffer.
X
XDESCRIPTION:
X
X This macro can be used by other macros which need to look
X at arbritrary buffers, eg (buffer_list).
X.HU inq_views
XSYNOPSIS: (inq_views)
X
XRETURN VALUE:
X
X Returns the number of windows which have the current
X buffer on display. Returns 0 if current buffer is not on
X display.
X
XDESCRIPTION:
X
X This macro can be used to determine if it is safe to
X delete a buffer (via (delete_buffer)).
X.HU inq_window
XSYNOPSIS: (inq_window)
X
XRETURN VALUE:
X
X An integer representing the identifier of the current window.
X
XDESCRIPTION:
X
X This macro returns the id of the current window. This is
X useful for macros which wish to move the cursor to another
X window but when they have completed wish to restore the
X cursor to the original window.
X.HU inq_window_color
XSYNOPSIS: (inq_window_color)
X
XRETURN VALUE:
X
X The color associated with the background of the current
X window.
X
XDESCRIPTION:
X
X This macro is used when borders are turned off. It is not
X currently supported.
X.HU inq_window_size
XSYNOPSIS: (inq_window_size [lines] [cols] [right])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to determine the dimensions of the
X current window. lines, cols & right are optional integer
X variables. lines and cols receive the number of lines and
X columns in the current window.
X
X right receives the amount the current buffer is shifted
X within the window for sideways scrolling. If the current
X buffer hasn't been sideways scrolled, then right will
X receive 0.
X.HU insert
XSYNOPSIS: (insert expr [num])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (insert) is another means for inserting text into a
X buffer. (The others are (self_insert) and (paste)). expr
X is a string expression which is to be inserted into the
X current buffer, as if typed by the user. Backslash-n
X characters are treated as new-lines.
X
X If num is specified, then the string, expr, is inserted
X num times. If omitted, it defaults to 1.
X.HU insert_mode
XSYNOPSIS: (insert_mode [mode])
X
XRETURN VALUE:
X
X Returns non-zero if the previous value was insert mode;
X returns zero if the previous value was overtype mode.
X
XDESCRIPTION:
X
X This macro allows the user to set and/or get the current
X value of the insert mode. The insert mode is applied when
X the user types in text. By default CRISP comes in insert
X mode, ie characters typed in cause characters to the right
X of the cursor to be shifted over. Overtype mode causes the
X character under the cursor to be deleted and replaced by
X the inserted characters.
X
X ins_mode is zero if overtype mode should be turned on, and
X non-zero if insert mode should be turned on.
X
X If ins_mode is omitted, then the current value is toggled.
X
X Note that the insert/overtype mode only affects
X (self_insert) not (insert) or (paste), etc.
X
X If the display terminal is not able to change cursor
X shape, then the echo status line will display the current
X status of the insert/overtype mode. (Note that it has to
X compete with other values on the display line so it may
X disappear, for example, if percentage through file is
X turned on. (See (echo_line)).
X
XEXAMPLES:
X
X The following example prints the state of the
X insert/overtype mode without changing the mode.
X
X (int mode)
X (= mode (insert_mode))
X (insert_mode) ; Toggles value back to previous state
X (message (if mode "Insert mode." "Overtype mode."))
X.HU insert_process
XSYNOPSIS: (insert_process expr [num])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (insert_process) is similar to (insert) except the
X inserted text is sent to an attached process instead of
X being inserted into the text buffer. No auto echo is
X performed - it is the calling macros responsibility to
X echo any input sent to the process.
X
X If num is specified, then the string, expr, is inserted
X num times. If omitted, it defaults to 1.
X.HU int
XSYNOPSIS: (int 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 integer values. The variables defined are
X local variables, and are destroyed when the macro
X executing this declaration terminates.
X
X Integers are two's complement integers, 32-bits in length
X on all machines.
X.HU int_to_key
XSYNOPSIS: (int_to_key key)
X
XRETURN VALUE:
X
X Returns a string in the format of (assign_to_key).
X
XDESCRIPTION:
X
X This function takes an integer argument, which is a
X key-code, eg as returned by (read_char). The integer
X key-code is converted to a string in the canonical form
X understood by assign_to_key. This allows macros to be
X written portably, rather than returning the raw key-code.
X
X (int_to_key) and (key_to_int) are inverses of each other.
X.HU is_integer
XSYNOPSIS: (is_integer expr)
X
XRETURN VALUE:
X
X Returns 1 if 'expr' is an integer expression; zero otherwise.
X
XDESCRIPTION:
X
X This macro can be used to test the data type of a
X polymorphic variable, for example when walking down a list.
X.HU is_list
XSYNOPSIS: (is_list expr)
X
XRETURN VALUE:
X
X Returns 1 if 'expr' is a list expression; zero otherwise.
X
XDESCRIPTION:
X
X This macro can be used to test the data type of a
X polymorphic variable.
X.HU is_null
XSYNOPSIS: (is_null expr)
X
XRETURN VALUE:
X
X Returns 1 if 'expr' contains the NULL value; 0 otherwise.
X
XDESCRIPTION:
X
X This macro can be used to test if a particular element of
X a list actually exists (ie to avoid walking off of the end
X of a list).
X.HU is_string
XSYNOPSIS: (is_string expr)
X
XRETURN VALUE:
X
X Returns 1 if 'expr' is a string expression; zero otherwise.
X
XDESCRIPTION:
X
X This macro can be used to test the data type of a
X polymorphic variable.
X
SHAR_EOF
echo "File help/crisp/prim/I.cmd is complete"
chmod 0644 help/crisp/prim/I.cmd || echo "restore of help/crisp/prim/I.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/M.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/M.cmd &&
X.HU macro
XSYNOPSIS: (macro name list)
X
XRETURN VALUE:
X
X Result of last statement executed in the macro.
X
XDESCRIPTION:
X
X (macro) defines a new macro. It is normally only processed
X when loading a .m or .cm file. The macro is given the name
X 'name' and consists of the executable statements in the
X list, list.
X
X If a macro is given the special name _init, then it is
X automatically executed when the macro file is loaded.
X.HU macro_list
XSYNOPSIS: (macro_list)
X
XRETURN VALUE:
X
X A list of strings containing the names of all currently
X defined macros (not CRISP keywords), in alphabetic order.
X
XDESCRIPTION:
X
X This macro is similar to (command_list) but simply returns
X a list of all the currently defined macros.
X.HU make_local_variable
XSYNOPSIS: (make_local_variable var1 var2 ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to make existing local variables into
X 'buffer' local variables. CRISP supports the concepts of
X three storage classes for variables - local, which go out
X of scope when the current macro terminates; global, which
X never go out of scope; and buffer-local, which go out of
X scope when the current buffer is changed.
X
X Buffer-local variables are useful for saving state
X information on a per buffer basis.
X
X When searching for a variable, CRISP searches the symbol
X tables in the following order:
X
X 1. Local variables.
X 2. Global variables.
X 3. Buffer variables.
X
X Therefore be careful when overloading symbol names. CRISP
X allows local variables, global variables and buffer
X variables to all be in scope at once, in which case the
X variable at the highest level in the above list is only
X accessible.
X.HU mark
XSYNOPSIS: (mark [type])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (mark) is similar to (raise_anchor)/(drop_anchor). If a
X marked region is currently displayed, then (mark) raises
X the anchor; if no anchor is displayed, then (mark) drops
X an anchor.
X
X type is an optional integer variable which is used to
X define the mark type if one is to be dropped. If it is
X omitted, it defaults to a normal marked region.
X
X See (drop_anchor) for a description of the marked region
X types.
X.HU message
XSYNOPSIS: (message fmt [arg1] [arg2] ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to display a message on the status
X (prompt) line at the bottom of the screen. fmt is a string
X and may contain printf-like % formatting characters. arg1,
X arg2, .. are integer or string expressions used to satisfy
X the % formatting options. Upto 6 arguments are allowed.
X
X This macro can be used to display informational messages
X on the bottom of the screen; if error messages are to be
X displayed then the (error) macro should be used instead.
X
X The following is a very brief summary of the % options
X available. For more information, please refer to the
X underlying C library function sprintf(), which is used to
X implement this function.
X
X %d Print an integer expression. Options such as %03d
X can be used to perform zero insertion and supply
X a field width.
X
X %x Print integer expression in hex.
X
X %o Print integer expression in octal.
X
X %s Print a string. Field width and alignments are
X allowed.
X
X %c Print a character.
X
X %l prefixes are allowed but are effectively stripped off.
X Internally all 'int' variables are stored as long's and
X the printf format string is parsed to insert an 'l' in the
X middle of all %d's, thus avoiding portability problems
X with macros.
X
XEXAMPLES:
X
X (message "The %s %s %s %s %s." "cat" "sat" "on" "the" "mat")
X (message "%d == 0x%04x" 32767 32767)
X.HU move_abs
XSYNOPSIS: (move_abs [line] [col])
X
XRETURN VALUE:
X
X Returns non-zero if cursor moved; 0 if cursor didn't move.
X
XDESCRIPTION:
X
X This macro moves the cursor to the specified line and
X column position. If either line or col are unspecified or
X zero, then the line or column position is left unchanged.
X.HU move_edge
XSYNOPSIS: (move_edge [direction])
X
XRETURN VALUE:
X
X Returns <= 0 if unsuccessful; > 0 otherwise.
X
XDESCRIPTION:
X
X This macro is used to expand or contract a window.
X direction specifies the edge which is to be moved. The
X expansion is performed interactively. This macro is
X designed to support tiled windows.
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 move_rel
XSYNOPSIS: (move_rel [line] [col])
X
XRETURN VALUE:
X
X Returns non-zero if cursor moved; 0 if cursor didn't move.
X
XDESCRIPTION:
X
X This macro moves the current line or column plus or minus
X the number of lines specified, ie the move is relative to
X the current cursor position.
X
SHAR_EOF
chmod 0644 help/crisp/prim/M.cmd || echo "restore of help/crisp/prim/M.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/Misc.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/Misc.cmd &&
X.HU !
XSYNOPSIS: (! iexpr)
X
XRETURN VALUE:
X
X Returns 1 if expr evaluates to zero; returns 0 if expr is
X non-zero.
X
XDESCRIPTION:
X
X Returns the logical not of the expression expr. expr must
X evaluate to an integer expression.
X.HU !=
XSYNOPSIS: (!= expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 is not equal to expr2; 0 if expr1 is
X equal to expr2.
X
XDESCRIPTION:
X
X expr1 and expr2 must either both be integer expressions or
X string expressions.
X.HU %
XSYNOPSIS: (% iexpr1 iexpr2)
X
XRETURN VALUE:
X
X Returns the integral remainder of the expression
X (iexpr1)/(iexpr2).
X
XDESCRIPTION:
X
X This is the modulus function. The example below shows the
X results of using negative numbers.
X
XEXAMPLES:
X
X The following example show the various pathological cases
X of the (%) function:
X
X (macro x
X (
X (message "%d %d %d %d %d"
X (% 4 -3)
X (% 4 -3)
X (% -4 3)
X (% -4 -3)
X (% -4 0))
X )
X )
X
X The output is:
X
X 1 1 -1 -1 0
X.HU %=
XSYNOPSIS: (%= ivar iexpr)
X
XRETURN VALUE:
X
X Returns the value assigned to ivar.
X
XDESCRIPTION:
X
X This macro is the same as:
X
X (= ivar (% ivar iexpr))
X
X ivar is the name of an integer variable; iexpr is an
X expression which evaluate to an integer.
X
X See (%) for details on the pathological use of negative
X numbers.
X.HU &
XSYNOPSIS: (& iexpr1 iexp2)
X
XRETURN VALUE:
X
X Returns the bit-wise AND of iexpr1 and iexpr2. A 32-bit
X integer result is returned.
X.HU &=
XSYNOPSIS: (&= ivar iexpr1)
X
XRETURN VALUE:
X
X The value of ivar logically ANDed with iexpr.
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= ivar (& ivar iexpr))
X.HU &&
XSYNOPSIS: (&& expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 evaluates to non-zero and expr2
X evaluates to non-zero; 0 otherwise.
X
XDESCRIPTION:
X
X This is the conditional AND macro. If expr1 evaluates to
X non-zero, then expr2 is evaluated. If expr1 evaluates to
X zero, then expr2 is not evaluated. Thus, it is safe for
X expr1 and expr2 to have side-effects.
X
XEXAMPLES:
X
X The following example tests var1 and if it is non-zero,
X increments var2 and tests to see if it is greater than 10.
X
X (if (&& var1 (> (++ var2) 10))
X (message "var2 > 10"))
X.HU *
XSYNOPSIS: (* iexpr1 iexpr2)
X
XRETURN VALUE:
X
X The value of iexpr1 multiplied by iexpr2.
X
X.HU *=
XSYNOPSIS: (*= ivar iexpr1)
X
XRETURN VALUE:
X
X The value of ivar multiplied by iexpr.
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= ivar (* ivar iexpr))
X.HU +
XSYNOPSIS: (+ expr1 expr2)
X
XRETURN VALUE:
X
X Either the integer value (expr1+expr2) or the string
X formed by concatenating expr1 and expr2.
X
XDESCRIPTION:
X
X iexpr1 and iexpr2 must either be both integer expressions
X or string expressions.
X.HU ++
XSYNOPSIS: (++ ivar)
X
XRETURN VALUE:
X
X Returns the value (ivar+1).
X
XDESCRIPTION:
X
X This macro forms the pre-increment instruction. (There is
X no post-increment equivalent, due to limitations in the
X syntax of the language).
X
X The variable ivar is incremented and the value may then be
X used in an expression.
X
XEXAMPLES:
X
X The following example can be used for controlling loops:
X
X (int i)
X (= i 0)
X (while (< (++ i) 10) (
X .
X .
X ))
X.HU +=
XSYNOPSIS: (+= var expr)
X
XRETURN VALUE:
X
X Returns either the integer value (var+expr) or the string
X formed by the concatenation of the string in variable var
X and the string returned by the expression expr.
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= var (+ var expr))
X.HU -
XSYNOPSIS: (- iexpr1 iexpr2)
X
XRETURN VALUE:
X
X Returns the integer value iexpr1 minus iexpr2.
X
XDESCRIPTION:
X
X iexpr1 and iexpr2 must both evaluate to integer expressions.
X.HU --
XSYNOPSIS: (-- ivar)
X
XRETURN VALUE:
X
X Returns the value (ivar-1).
X
XDESCRIPTION:
X
X This macro forms the pre-decrement instruction. (There is
X no post-increment equivalent, due to limitations in the
X syntax of the language).
X
X The variable ivar is decremented and the value may then be
X used in an expression.
X.HU -=
XSYNOPSIS: (-= ivar iexpr)
X
XRETURN VALUE:
X
X Returns the value (ivar-iexpr).
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= ivar (- ivar iexpr))
X.HU /
XSYNOPSIS: (/ iexpr1 iexpr2)
X
XRETURN VALUE:
X
X Returns the value of iexpr1 divided by iexpr2.
X
XDESCRIPTION:
X
X If iexpr2 is zero, then iexpr1 is returned.
X.HU /=
XSYNOPSIS: (/= ivar iexpr)
X
XRETURN VALUE:
X
X Returns the value ivar divided by iexpr.
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= ivar (/ ivar iexpr))
X.HU <
XSYNOPSIS: (< expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is less than expr2; returns 1 if expr1 & expr2 are string
X expressions and expr1 lexicographically preceeds expr2.
X Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X.HU <=
XSYNOPSIS: (<= expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is less than or equal to expr2; returns 1 if expr1 & expr2
X are string expressions and expr1 lexicographically
X preceeds expr2 or is equal to expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X.HU =
XSYNOPSIS: (= var expr)
X
XRETURN VALUE:
X
X Returns the value of expr.
X
XDESCRIPTION:
X
X This is the assignment operator. var is the name of a
X symbol, and expr must be an expression which evaluates to
X the same type as 'var', unless 'var' has been declared as
X a polymorphic variable. (See (declare)).
X
X var and expr must agree in type. They can have integer,
X string or list type. For list variables, it is acceptable
X for expr to be NULL or omitted, in which case the storage
X allocated to the variable var is freed.
X
XEXAMPLES:
X
X (int i)
X (= i (+ 1 2))
X (string s)
X (= s (+ "fred" " bloggs"))
X (list l)
X (= l (quote_list 1 2 3))
X (= l NULL)
X (= l) ; same as previous example.
X.HU ==
XSYNOPSIS: (== expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 is equal to expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X.HU >
XSYNOPSIS: (> expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is greater than expr2; returns 1 if expr1 & expr2 are
X string expressions and expr1 lexicographically follows
X expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X.HU >=
XSYNOPSIS: (>= expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is greater than or equal to expr2; returns 1 if expr1 &
X expr2 are string expressions and expr1 lexicographically
X preceeds expr2 or is equal to expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X.HU |
XSYNOPSIS: (| iexpr1 iexpr2)
X
XRETURN VALUE:
X
X Returns the logical OR of integer expression iexpr1 and
X iexpr2.
X
X.HU |=
XSYNOPSIS: (|= ivar iexpr1)
X
XRETURN VALUE:
X
X The value of ivar logically ORed with iexpr.
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= ivar (| ivar iexpr))
X.HU ||
XSYNOPSIS: (|| expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 OR expr2 evaluate to non-zero.
X
XDESCRIPTION:
X
X This is the conditional OR function. If expr1 evaluates to
X non-zero then expr2 is not evaluated. If expr1 evaluates
X to zero, then the result of expr2 is returned.
X.HU ^
XSYNOPSIS: (^ iexpr1 iexpr2)
X
XRETURN VALUE:
X
X Returns the logical XOR of integer expression iexpr1 and
X iexpr2.
X
X.HU ^=
XSYNOPSIS: (^= ivar iexpr1)
X
XRETURN VALUE:
X
X The value of ivar logically XORed with iexpr.
X
XDESCRIPTION:
X
X This is equivalent to:
X
X (= ivar (^ ivar iexpr))
X.HU ~
XSYNOPSIS: (~ iexpr)
X
XRETURN VALUE:
X
X Returns the 1's complement of the integer expression iexpr.
X.HU _bad_key
XSYNOPSIS: (_bad_key)
X
XRETURN VALUE:
X
X A string.
X
XDESCRIPTION:
X
X (_bad_key) is not actually a built-in primitive, but is
X used by CRISP to implement the command history and
X abbreviation features.
X
X The macro _bad_key is called from within CRISP when a bad
X key is pressed during a prompt. This macro can use the
X (inq_message) and (inq_cmd_line) macros to see what the
X state of the status line is. It can also call (read_char)
X to retrieve the key which caused the problem -- this
X allows the _bad_key macro to distinguish between context
X sensitive help, or abbreviations etc.
X
X The macro should return a string value, in which case this
X is taken as the current input for the response field (it
X will be highlited as the default value). The (push_back)
X macro can be used to force acceptance of a default response.
X
X See the history.m macro file for an example of how to use
X the (_bad_key) macro.
X
SHAR_EOF
chmod 0644 help/crisp/prim/Misc.cmd || echo "restore of help/crisp/prim/Misc.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/N.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/N.cmd &&
X.HU next_buffer
XSYNOPSIS: (next_buffer [system])
X
XRETURN VALUE:
X
X Returns the buffer id of the next buffer in the buffer list.
X
XDESCRIPTION:
X
X (next_buffer) is the mechanism for enumerating all
X buffers. It returns the buffer id of the next buffer in
X the list.
X
X system is an optional integer which if present and
X non-zero allows the calling macro to walk through each
X system buffer as well (see create_buffer). If it is
X omitted, then system buffers are stepped over. This
X facility is used by the (buffer_list) macro if the systems
X option is turned on.
X
XEXAMPLES:
X
X The following example shows how to walk down each buffer,
X including system buffers:
X
X (int curbuf)
X (int buf)
X
X (= curbuf (inq_buffer))
X (= buf (+ curbuf 1))
X (while (!= curbuf buf) (
X .
X .
X (= buf (next_buffer 1))
X ))
X.HU next_char
XSYNOPSIS: (next_char [num])
X
XRETURN VALUE:
X
X Returns non-zero if the cursor changed position; zero if
X it didn't.
X
XDESCRIPTION:
X
X This function is similar to (right) except it moves the
X cursor over physical characters, eg tabs are treated as
X single characters, rather than virtual spaces.
X
X If num is specified then that number of character
X positions are skipped over.
X
X If the cursor is moved past the end of the line, then the
X cursor wraps around to the start of the next line.
X.HU nothing
XSYNOPSIS: (nothing)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is a no-op. It exists simply as a place holder
X for the language and is valid anywhere any other macro is
X valid.
X.HU nth
XSYNOPSIS: (nth expr list_expr)
X
XRETURN VALUE:
X
X Returns the n'th atom in list_expr, where n is the value
X of the integer expression expr.
X
XDESCRIPTION:
X
X This macro allows the caller to extract individual atoms
X from a list. The first element of a list is element 0; the
X (nth) macro allows lists to be treated like arrays. The
X last element of a list is (length_of_list)-1.
X
X nth is a more efficient way of accessing random elements
X in a list, than for example, using (car) and (cdr), since
X the list expression doesn't need to be copied so much.
X
SHAR_EOF
chmod 0644 help/crisp/prim/N.cmd || echo "restore of help/crisp/prim/N.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/P.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/P.cmd &&
X.HU page_down
XSYNOPSIS: (page_down)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor one window-full towards the end of the
X buffer.
X.HU page_up
XSYNOPSIS: (page_up)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor one window-full towards the beginning of
X the buffer.
X.HU paste
XSYNOPSIS: (paste)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro copies the contents of the scrap buffer and
X inserts it into the current buffer where the cursor is
X located.
X.HU pause
XSYNOPSIS: (pause)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (pause) is used to pause a keyboard macro definition.
X Usually all keyboard input typed during a (remember)
X sequence is saved in the keyboard macro buffer. Pressing a
X key assigned to (pause) causes the (remember) sequence to
X suspend saving the characters.
X.HU pause_on_error
XSYNOPSIS: (pause_on_error [pause])
X
XRETURN VALUE:
X
X Non-zero if previous setting was paused messages on; 0 is
X previous setting was no pausing of error messages.
X
XDESCRIPTION:
X
X This macro is used to set or toggle the pause on error
X flag. This flag is tested after every (error) message is
X displayed. If this flag is on then the error message is
X displayed with a '..' suffix added to the end of the error
X message and CRISP waits for the user to type any key on
X the keyboard to continue. This allows the user to see
X error messages before they get overwritten by other
X messages.
X
X By default this is off. If (pause_on_error) is called with
X no argument, then the current state is toggled and CRISP
X prints the message 'Pausing errors on.' or 'Pausing errors
X off.' If pause is specified then the current setting is
X set to the value of the integer expression pause.
X
XEXAMPLES:
X
X The following example shows how (pause_on_error) can be
X used around a call to a macro so that the user can see the
X errors being displayed by the macro without resorting to
X sight-reading.
X
X (pause_on_error) ;Toggle state to on.
X (fred) ;Call macro.
X (pause_on_error) ;Toggle state to off.
X.HU playback
XSYNOPSIS: (playback [macro])
X
XRETURN VALUE:
X
X Returns greater than or equal to zero if playback was
X successful. Less than zero otherwise.
X
XDESCRIPTION:
X
X (playback) causes the saved keyboard macro to be replayed.
X If macro is not specified, then the last macro defined is
X played back.
X
X (playback) is not usually called from within a macro, but
X instead is usually bound to the <F8> key.
X.HU prev_char
XSYNOPSIS: (prev_char [num])
X
XRETURN VALUE:
X
X Nothing
X
XDESCRIPTION:
X
X Moves the cursor backwards by num characters. The movement
X is by physical characters, and treats tabs, etc as single
X characters.
X
X If the cursor is moved beyond the beginning of the current
X line then the cursor wraps around to the end of the
X previous line.
X.HU print
XSYNOPSIS: (print)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to send the currently marked region to
X the printer. It exists for compatability with BRIEF but is
X an unimplemented function. This is because most Unix users
X will not have their own personal printer, and will tend to
X use the Unix line printer spooler instead. Thus little is
X gained by supporting this.
X
X If there is enough demand, this will be implemented by
X sending the marked area to the print spooler. Please let
X me know if it causes a problem.
X.HU printf
XSYNOPSIS: (printf fmt [arg1] [arg2] ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro can be used for debugging macros, although its
X use is questionable. It exists for compatability reasons
X with BRIEF. It causes the formatted string to be sent
X directly to stdout, bypassing all of CRISPs internal
X screen manipulations.
X
X Its use is questionable since it is presumably provided
X for use with BRIEF and MS-DOS for debugging BRIEF itself
X and BRIEF macros. Under MS-DOS, BRIEF writes directly to
X the video memory and it may be useful to have a separate
X error logging channel which can be redirected to a file.
X
X Under Unix, stdout is used for all display purposes, so
X the printf output stream would be intermingled with the
X display stream.
X
X If you need to track the progress of a macro, use (debug)
X since it gives you a much finer granularity of output.
X.HU process
XSYNOPSIS: (process)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X The (process) macro is the mechanism for causing CRISP to
X nest keyboard invocations. CRISP maintains a process level
X counter which is normally set to 1. When in the process
X mode, CRISP accepts keystrokes and executes the macros
X bound to those keystrokes.
X
X A call to (process) is usually made after creating buffers
X and windows for display on screen, and having set up a
X temporary keyboard map. Return from a call to (process)
X only occurs as a result of a macro calling the (exit) macro.
X
X The current process level is terminated via a call to
X (exit). When the process level goes to zero, CRISP exits
X (possibly after prompting the user to save buffers).
X
X Process nesting may occur to any depth, within the bounds
X of CRISPs maximum nesting level.
X
X The term 'process' is a misnomer and in this context
X should not be confused with process buffers, which are a
X completely different concept.
X.HU profile
XSYNOPSIS: (profile [expr])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (profile) exists solely to help profile CRISPs own
X execution so that it may be optimised. By default a
X mon.out file is created whenever a program exits which was
X compiled with the 'cc -p' flag. When CRISP exits, it
X usually avoids calling exit() so that the mon.out file
X does not get written. This allows CRISP to be compiled
X with the -p flag and installed without causing every user
X to inadvertently create mon.out files all over the file
X system.
X
X In order to get a mon.out file on exit from CRISP, either
X run CRISP with the -p flag, or call this macro.
X
X If expr is omitted, the profile option is toggled. If expr
X is non-zero then a mon.out file will be created; if it is
X zero, then mon.out will not be created.
X
X Note that this option only works if CRISP was compiled
X with the profiling code included.
X.HU push_back
XSYNOPSIS: (push_back key)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to push a character back into the
X typeahead buffer. The character pushed back sits at the
X front of the input buffer and is read before any user
X typeahead.
X
X key is an integer internal key code, usually derived from
X a (read_char) or (key_to_int) macro call.
X.HU put_nth
XSYNOPSIS: (put_nth expr list_var value)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (put_nth) is used to modify or insert a new atom into a
X list. list_var is the list; expr is the atom number to be
X inserted (0 is the first atom). value is an integer,
X string or list expression which is to be inserted.
X
X If the atom to be inserted already exists, then that atom
X is deleted, and replaced by the new value.
X
X If the expr'th atom does not exist, then value is inserted
X onto the end of the list. It is not possible to create
X sparse lists, only new entries may be tacked on to the end
X of a list.
X
XEXAMPLES:
X
X The following example creates a list of the ten integers,
X 1..10:
X
X (int i)
X (list l)
X
X (= i 1)
X (while (<= i 10) (
X (put_nth i l i)
X (++ i)
X ))
X.HU put_parm
XSYNOPSIS: (put_parm num value)
X
XRETURN VALUE:
X
X Returns 0 if successful; greater than zero if argument num
X does not exist.
X
XDESCRIPTION:
X
X This macro is used to modify a calling parameter. num
X specifies the argument number, and value is the value to
X place in that argument. value may be a string or an
X integer expression. (Lists are not currently supported).
X
X This macro allows the calling macro to pass multiple
X values to its calling macro. The calling macro should call
X this macro with the name of an integer or string macro in
X the num'th position.
X
SHAR_EOF
chmod 0644 help/crisp/prim/P.cmd || echo "restore of help/crisp/prim/P.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/R.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/R.cmd &&
X.HU raise_anchor
XSYNOPSIS: (raise_anchor)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X (raise_anchor) is used to raise the current marked region,
X ie remove it. The currently highlited region is unhighlited.
X.HU re_syntax
XSYNOPSIS: (re_syntax [mode])
X
XRETURN VALUE:
X
X Returns the current regular expression syntax mode - 0 for
X BRIEF/CRISP syntax, 1 for Unix-like syntax.
X
XDESCRIPTION:
X
X This macro allows the user to select the regular
X expression syntax mode. By default, the mode is set for
X BRIEF/CRISP regular expression syntax. If mode is set to
X 1, then Unix like syntax is selected. The differences are
X as follows:
X
X In Unix mode, the '*' and '.' characters have their normal
X meanings. The BRIEF/CRISP characters '@' and '?' act as
X non regular expression characters. Also the { and }
X characters are replaced by their backslash-( and
X backslash-) equivalents.
X
X.HU read
XSYNOPSIS: (read [num])
X
XRETURN VALUE:
X
X Returns a string containing the next num characters from
X the input buffer, or the rest of the line after the cursor
X if num is not specified.
X
XDESCRIPTION:
X
X If num is not specified, then all characters to the right
X of the cursor are returned, together with the newline
X character which terminates all lines.
X
X If num is specified, then that number of characters are
X read from the buffer. If num is longer than the remaining
X characters on the current line, then only the rest of the
X current line is returned.
X.HU read_char
XSYNOPSIS: (read_char)
X
XRETURN VALUE:
X
X Internal key code of character typed or -1 if no character
X available.
X
XDESCRIPTION:
X
X This macro can be used to see if a character is available
X from the typeahead buffer. If a character is available, it
X is returned (in internal key code form), and the character
X removed from the typeahead buffer.
X
X If a non-destructive peek into the typeahead buffer is
X required, use (inq_kbd_char).
X
X Under DOS (and BRIEF), (read_char) can be used to poll the
X keyboard. Some BRIEF macros do this with a while loop:
X
X (while (== (read_char) -1)
X (nothing))
X
X This is not a very nice thing to do on a Unix system, so
X by default (read_char) is a suspensive operation, ie
X calling (read_char) will actually pause the macro until a
X character is typed. If CRISP is run with the '-w' flag
X then (read_char) will act as it does under DOS, and return
X -1 if no character is available from the input buffer. Use
X of the -w flag should be avoided since otherwise CRISP
X will hog the CPU.
X
X Internal key codes should not be manipulated as is (unless
X the keys are being inserted into the current buffer), but
X rather should be converted to the canonical key-code
X format, via int_to_key.
X.HU read_file
XSYNOPSIS: (read_file [filename])
X
XRETURN VALUE:
X
X Zero if unsuccessful; non-zero otherwise.
X
XDESCRIPTION:
X
X This macro is used to read a file into the current buffer
X at the current cursor position. If filename is omitted,
X then the user is prompted for the file-name.
X.HU redraw
XSYNOPSIS: (redraw)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to physically redraw every character on
X the screen, after first clearing the screen. It is
X sometimes required on serial lines, etc, where the screen
X has garbage on it, and CRISP has lost control.
X.HU refresh
XSYNOPSIS: (refresh)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to update the screen after making
X various changes to buffers and/or windows. It optimises
X the amount of output to the screen.
X.HU register_macro
XSYNOPSIS: (register_macro num macro [local])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Registered macros are hooks into the execution of CRISP.
X CRISP defines triggers which allow the user's macro's to
X be activated when certain conditions arise in CRISP.
X
X The conditions are described by the 'num' parameter, which
X is an integer expression. The conditions are listed below.
X
X macro is the name of a macro to call when the trigger is
X pulled. If local is specified and is non-zero, then the
X macro is only registered for this buffer, otherwise the
X event may be triggered even when the current buffer is not
X selected.
X
X Multiple macros may be associated with a particular
X registered macro. When the registered macro is called, the
X macros are called in FIFO order.
X
X Registered macros may be removed by using the
X (unregister_macro) macro call; a particular registered
X macro can be triggered via (call_registered_macro).
X
X 0 A character has been inserted into the
X current buffer via (self_insert).
X
X 1 This is called every time the current
X buffer is changed via (edit_file).
X
X 2 This is triggered every time the
X <Alt-H> key is pressed, and is used
X for the context sensitive help feature.
X
X 3 This is triggered whenever an
X unassigned key is pressed.
X
X 4 This is triggered when the keyboard
X idle timer expires. It allows the
X autosave feature to be implemented.
X
X 5 This is called just before CRISP
X exits. It allows macros to tidy up
X after themselves, eg delete temporary
X files, save editing state.
X
X 6 This is called every time a new file
X is read in to a buffer (via edit_file).
X
X 7 This is called whenever the user types
X the interrupt character (by default
X ^Y). This allows macros to set a flag
X which can cause them to abort.
X
X 8 This is called whenever the user types
X in an invalid key during input on the
X status/prompt line. This allows the
X abbreviation and help facilities to be
X implemented.
X
X.HU remember
XSYNOPSIS: (remember [overwrite] [macro])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X remember is used to record a keyboard macro (a sequence of
X keystrokes) that can later be played back via (playback).
X
X The argument overwrite is an optional string whose first
X character is examined to see whether an existing keyboard
X macro should be overwritten. If a keyboard macro already
X exists, and overwrite is not specified, then the user is
X prompted to overwrite the macro. If overwrite is specified
X and the first character of overwrite is a 'y' or 'Y' then
X the keyboard macro will be overwritten.
X
X macro specifies which keyboard macro to store the
X keystrokes in. CRISP has by default 20 keyboard macros
X 0..19. If macro is unspecified then the next free keyboard
X macro is chosen. The internal counter wraps around when
X all the keyboard macros have been used up.
X
X If remember is called whilst recording a keyboard macro,
X then the recording is terminated.
X
X remember is not usually called as part of a macro but is
X usually bound to a keyboard key (<F7>).
X
X remember will also create a buffer called KBD-MACRO-xx
X where xx is the keyboard macro number. This buffer
X contains the top level macros executed by the user typing
X in the keys. This facility allows the user to save and
X edit a keyboard macro. Note that not all the macros
X executed by the user are saved in the buffer - only the
X top level ones. What this means is that keyboard input to
X things like dialog boxes (eg, the buffer list) will not be
X listed. The buffer so created is a normal buffer but will
X not be automatically saved when you exit. It is the user's
X responsibility to save the buffer is you want to keep the
X macro.
X.HU restore_position
XSYNOPSIS: (restore_position [move])
X
XRETURN VALUE:
X
X Returns 0 if there is no saved position on the stack; 1 if
X position was successfully restored.
X
XDESCRIPTION:
X
X This macro restores a saved position from the position
X stack. move is an optional integer expression. If move is
X specified and is zero, then the saved position is not
X restored, but simply discarded.
X
X The saved position stack is independent of the current
X buffer.
X.HU return
XSYNOPSIS: (return [expr])
X
XRETURN VALUE:
X
X Value of expr.
X
XDESCRIPTION:
X
X This macro is used to return from a macro, and optionally
X return a value. If expr is specified, it may be an
X integer, string or list expression.
X
X The current macro is terminated and control passes to the
X calling macro.
X.HU returns
XSYNOPSIS: (returns [expr])
X
XRETURN VALUE:
X
X Value of expr.
X
XDESCRIPTION:
X
X This macro is similar to (return), except it doesn't cause
X the current macro to terminate. It simply sets CRISPs
X internal accumulator with the value of expr. If any other
X statements follow the execution of (returns), then the
X accumulator will be overwritten.
X
X Use of this macro is not recommended.
X
X This macro is not strictly compatible with the (returns)
X macro of BRIEF.
X.HU right
XSYNOPSIS: (right [n])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor 'n' positions to the right. This is
X equivalent to adding 'n' to the current column position.
X Note that when the cursor moves it doesnt move over
X characters atomically but one column at a time. This
X allows the cursor to move beyond the end of the line and
X into the middle of a tab stop, for example.
X
X If you want to move over physical characters, use the
X (next_char) and (prev_char) macros instead.
X
X n may be positive or negative. negative amounts move
X leftward.
X
X.HU rindex
XSYNOPSIS: (rindex search-string pattern)
X
XRETURN VALUE:
X
X Returns 0 if pattern cannot be found in search-string;
X otherwise returns the last occurence of pattern in
X search-string.
X
XDESCRIPTION:
X
X This function returns the index in search-string of the
X last occurence of pattern. This function is useful for
X splitting a filename into its filename and directory
X components.
X
X If the user needs to search for regular expressions, then
X the function search_string should be used instead.
SHAR_EOF
echo "End of part 5"
echo "File help/crisp/prim/R.cmd is continued in part 6"
echo "6" > 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