                           ! iexpr 
    
DESCRIPTION      
    Returns the logical not of  the  expression  expr.  expr
    must evaluate to an integer expression. 
    
EXAMPLES      
    
    	int	i = 23; 
    
    	i = !i; 
    	/* i now has the value of 0. */ 
    
    	if (!i) 
    		message("i is zero"); 
    	else 
    		message("i is not zero"); 
    
    
RETURN VALUE     
    Returns  1  if expr evaluates to zero; returns 0 if expr
    is non-zero. 
                        expr1 != expr2 
    
RETURN VALUE     
    Returns 1 if expr1 is not equal to expr2; 0 if expr1  is
    equal to expr2. 
                       iexpr1 % iexpr2 
    
DESCRIPTION      
    This  is  the  modulus function. The example below shows
    the results of using negative numbers. 
    
    
EXAMPLES      
    The following  example  show  the  various  pathological
    cases of the (%) function: 
    
    	mod_test() 
    	{ 
    		message("%d %d %d %d %d", 
    			4 % -3, 
    			4 % -3, 
    			-4 % 3, 
    			-4 % -4, 
    			-4 % 0); 
    	} 
    
    
    The output is: 
    
        	1 1 -1 -1 0 
    
    
RETURN VALUE     
    Returns  the  integral  remainder  of   the   expression
    (iexpr1)/(iexpr2). 
    
    
                        ivar %= iexpr 
    
DESCRIPTION      
    This macro is the same as: 
    
        		ivar = ivar % iexpr; 
    
    
    ivar  is  the  name  of an integer variable; iexpr is an
    expression which evaluate to an integer. 
    
    See (%) for details on the pathological use of  negative
    numbers. 
    
RETURN VALUE     
    Returns the value assigned to ivar. 
                        iexpr1 & iexp2 
    
RETURN VALUE     
    Returns  the bit-wise AND of iexpr1 and iexpr2. A 32-bit
    integer result is returned. 
                       ivar &= iexpr1; 
    
    
RETURN VALUE     
    The value of ivar logically ANDed with iexpr. 
    
DESCRIPTION      
    This is equivalent to: 
    
    	ivar = ivar & iexpr; 
    
    
                        expr1 && expr2 
    
DESCRIPTION      
    This is the conditional AND macro. If expr1 evaluates to
    non-zero, then expr2 is evaluated. If expr1 evaluates to
    zero, then expr2 is not evaluated. Thus, it is safe  for
    expr1 and expr2 to have side-effects. 
    
EXAMPLES      
    The  following example tests var1 and if it is non-zero,
    increments var2 and tests to see if it is  greater  than
    10. 
    
    	if (var1 && ++var2 > 10) 
    		message("var2 > 10 and var1 is non-zero"); 
    
    
RETURN VALUE     
    Returns  1  if  expr1  evaluates  to  non-zero and expr2
    evaluates to non-zero; 0 otherwise. 
                        expr1 * expr2 
    
DESCRIPTION      
    The  '*'  operator  is  used  to  multiply  two  numbers
    together (either floating point or  integer).  Automatic
    co-oercion  between  float  and integer is performed. If
    either argument is a float, then the result  will  be  a
    float. 
    
    If  either  expr1  or  expr2  is  a  string, then string
    duplication will be performed. For example,  4*"x"  will
    return  the  string "xxxx". The number and string may be
    in either order. 
    
    All other combinations of types are invalid. 
    
RETURN VALUE     
    The  value   of  iexpr1  multiplied  by  iexpr2  or  the
    specified string replicated the number of times. 
                       ivar *= iexpr1; 
    
DESCRIPTION      
    This is equivalent to: 
    
    	ivar = ivar * iexpr; 
    
    
RETURN VALUE     
    The value of ivar multiplied by iexpr. 
                        expr1 + expr2 
    
DESCRIPTION      
    The plus operator is used to  add,  or  concatenate  two
    expressions.  The  operation is dependent on the type of
    the  two   specified   expressions.  The  processing  is
    performed in the following order. 
    
    If expr1 or expr2 is a list, then a new list is returned
    which is the concatenation of expr1 and expr2. 
    
    If expr1 or expr2 is a string, then the other operand is
    converted to a string, and a string is returned. 
    
    If either operand is a floating point  number  then  the
    other the result is the sum of the two expressions. 
    
    Otherwise  the  integer  value  of  the  sum  of the two
    expressions is returned. 
    
RETURN VALUE     
    A list value if either operand is a list;  a  string  if
    either operand is a string; a float if either operand is
    a float; otherwise an integer value. 
    
EXAMPLES      
    The  following  example  illustrates  how  to  convert a
    number to a string: 
    
    	string s = "" + 2.3; 
    
    
                            ++ivar 
    
DESCRIPTION      
    This macro forms the pre-increment  instruction.  (There
    is  no  post-increment equivalent, due to limitations in
    the syntax of the language). 
    
    The variable ivar is incremented and the value may  then
    be used in an expression. 
    
EXAMPLES      
    The following example can be used for controlling loops:
    
        	int	i = 0; 
    	while (++i < 10) { 
    		.. 
    		.. 
    		} 
    
    
RETURN VALUE     
    Returns the value (ivar+1). 
                         var += expr; 
    
DESCRIPTION      
    This is equivalent to: 
    
    	var = var + expr; 
    
    
RETURN VALUE     
    Adds  the  expression  expr  to  the  variable 'var' and
    returns the value. Addition is performed the same as the
    '+' operator,  i.e.  float's  and  int's  will  be  cast
    appropriately. 
                       iexpr1 - iexpr2 
    
DESCRIPTION      
    iexpr1  and  iexpr2  must  both  evaluate   to   integer
    expressions. 
    
RETURN VALUE     
    Returns the integer value iexpr1 minus iexpr2. 
                            --ivar 
    
DESCRIPTION      
    This  macro  forms the pre-decrement instruction. (There
    is no post-increment equivalent, due to  limitations  in
    the syntax of the language). 
    
    The  variable ivar is decremented and the value may then
    be used in an expression. 
    
RETURN VALUE     
    Returns the value (ivar-1). 
                        ivar -= iexpr 
    
DESCRIPTION      
    This is equivalent to: 
    
    	ivar = ivar - iexpr; 
    
    
RETURN VALUE     
    Returns the value (ivar-iexpr). 
                        expr1 / iexpr2 
    
DESCRIPTION      
    If iexpr2 is zero, then iexpr1 is returned. 
    
RETURN VALUE     
    Returns the value of iexpr1 divided by iexpr2. 
                        ivar /= iexpr 
    
RETURN VALUE     
    Returns the value ivar divided by iexpr. 
    
DESCRIPTION      
    This is equivalent to: 
    
    	ivar = ivar / iexpr; 
    
    
                        expr1 < expr2 
    
DESCRIPTION      
    expr1 & expr2 must either be both integer expressions or
    string expressions. 
    
RETURN VALUE     
    Returns 1 if expr1 and  expr2  are  integer  values  and
    expr1 is less than expr2; returns 1 if expr1 & expr2 are
    string  expressions and expr1 lexicographically preceeds
    expr2. Returns 0 otherwise. 
                        expr1 << expr2 
    
RETURN VALUE     
    Returns expr1 shifted left by expr2 bit positions. expr1
    and expr2 must be integer expressions. 
                        expr1 <= expr2 
    
DESCRIPTION      
    expr1 & expr2 must either be both integer expressions or
    string expressions. 
    
RETURN VALUE     
    Returns 1 if expr1 and  expr2  are  integer  values  and
    expr1 is less than or equal to expr2; returns 1 if expr1
    &   expr2    are    string    expressions    and   expr1
    lexicographically preceeds expr2 or is equal  to  expr2.
    Returns 0 otherwise. 
                          var = expr 
    
DESCRIPTION      
    This  is  the  assignment operator. var is the name of a
    symbol, and expr must be an expression  which  evaluates
    to  the  same  type  as  'var',  unless  'var'  has been
    declared as a polymorphic variable. (See (declare)). 
    
    var and expr must agree in type. They can have  integer,
    string  or  list  type.  For  list  variables,   it   is
    acceptable for expr to be NULL or omitted, in which case
    the storage allocated to the variable var is freed. 
    
RETURN VALUE     
    Returns the value of expr. 
    
EXAMPLES      
    
    	int	i; 
    	string	s; 
    	list	l; 
    	 
    	i = 1 + 2; 
    	s = "fred" + " bloggs"; 
    	l = quote_list(1, 2, 3); 
    	l = NULL; 
    
    
                         var <<= expr 
    
RETURN VALUE     
    Returns value of var shifted left by expr bit positions.
    var  must  be  an  integer  variable and expr must be an
    integer expression. 
                        expr1 == expr2 
    
DESCRIPTION      
    Lists cannot be compared. 
    
RETURN VALUE     
    Returns  1  if  expr1  is  equal  to  expr2.  Returns  0
    otherwise. 
                        expr1 > expr2 
    
DESCRIPTION      
    expr1  &   expr2   must   either   be    both    numeric
    expressions or string expressions. 
    
RETURN VALUE     
    Returns  1  if  expr1  and  expr2 are integer values and
    expr1 is greater than expr2; returns 1 if expr1 &  expr2
    are  string  expressions  and  expr1   lexicographically
    follows expr2. Returns 0 otherwise. 
                        expr1 >= expr2 
    
DESCRIPTION      
    expr1 & expr2 must either be both numeric expressions or
    string expressions. 
    
RETURN VALUE     
    Returns  1  if  expr1  and  expr2 are integer values and
    expr1 is greater than or equal to expr2;  returns  1  if
    expr1  &  expr2  are  string   expressions   and   expr1
    lexicographically  preceeds  expr2 or is equal to expr2.
    Returns 0 otherwise. 
                        expr1 >> expr2 
    
RETURN VALUE     
    Returns expr1 shifted  right  by  expr2  bit  positions.
    expr1 and expr2 must be integer expressions. 
                         var >>= expr 
    
RETURN VALUE     
    Returns  value  of  var  shifted  right  by   expr   bit
    positions. var must be an integer variable and expr must
    be an integer expression. 
                       iexpr1 | iexpr2 
    
RETURN VALUE     
    Returns  the logical OR of integer expression iexpr1 and
    iexpr2. 
                        ivar |= iexpr1 
    
DESCRIPTION      
    This is equivalent to: 
    
    	ivar = ivar | iexpr; 
    
    
RETURN VALUE     
    The value of ivar logically ORed with iexpr. 
                        expr1 || expr2 
    
RETURN VALUE     
    Returns 1 if expr1 OR expr2 evaluate to non-zero. 
    
DESCRIPTION      
    This is the conditional OR function. If expr1  evaluates
    to  non-zero  then  expr2  is  not  evaluated.  If expr1
    evaluates to zero, then the result of expr2 is returned.
    
                       iexpr1 ^ iexpr2 
    
RETURN VALUE     
    Returns the logical XOR of integer expression iexpr1 and
    iexpr2. 
                        ivar ^= iexpr1 
    
RETURN VALUE     
    The value of ivar logically XORed with iexpr. 
    
DESCRIPTION      
    This is equivalent to: 
    
    	ivar = ivar ^ iexpr; 
    
    
                            ~iexpr 
    
RETURN VALUE     
    Returns the 1's complement  of  the  integer  expression
    iexpr. 
                          _bad_key() 
    
DESCRIPTION      
    _bad_key()  is not actually a built-in primitive, but is
    used by CRISP  to  implement  the  command  history  and
    abbreviation features. 
    
    The  macro  _bad_key  is called from within CRISP when a
    bad key is pressed during a prompt. This macro  can  use
    the  inq_message() and inq_cmd_line() macros to see what
    the state of the  status  line  is.  It  can  also  call
    read_char() to retrieve the key which caused the problem
    -- this allows the _bad_key macro to distinguish between
    context sensitive help, or abbreviations etc. 
    
    The  macro  should  return a string value, in which case
    this is taken as the  current  input  for  the  response
    field  (it  will be highlited as the default value). The
    push_back() macro can be used to force acceptance  of  a
    default response. 
    
    See  the  history.m  macro file for an example of how to
    use the _bad_key() macro. 
    
RETURN VALUE     
    A string. 
                           abort() 
    
DESCRIPTION      
    This macro is  used  to  abort  CRISP  -  it  causes  an
    unconditional  exit  from  CRISP  after  resetting   the
    keyboard state. 
    
    It  should be used with extreme care since no checks are
    made to see if buffers need to be saved, etc. 
    
    Its primary use will be in debugging macros. 
    
RETURN VALUE     
    Nothing. 
                     above(expr1, expr2) 
    
DESCRIPTION      
    This function provides a  functional  form  of  the  '>'
    operator.  expr1  &  expr2  must  either be both integer
    expressions or string expressions. 
    
RETURN VALUE     
    Returns 1 if expr1 and  expr2  are  integer  values  and
    expr1  is greater than expr2; returns 1 if expr1 & expr2
    are  string   expressions  and  expr1  lexicographically
    follows expr2. Returns 0 otherwise. 
                    above_eq(expr1, expr2) 
    
DESCRIPTION      
    This function is a functional form of the '>=' operator.
    expr1 & expr2 must either be both integer expressions or
    string expressions.  
    
RETURN VALUE     
    Returns 1 if expr1 and  expr2  are  integer  values  and
    expr1  is  greater  than or equal to expr2; returns 1 if
    expr1  &   expr2   are   string  expressions  and  expr1
    lexicographically follows expr2 or is  equal  to  expr2.
    Returns 0 otherwise. 
                access(string file, int mode) 
    
DESCRIPTION      
    This  function  is  used to check the accessability of a
    file. The file parameter is the name of a  directory  or
    file  which is to be tested and mode are a set of access
    bits which are used to check the effective access. 
    
    The meaning of mode is operating system dependent (refer
    to <unistd.h>  or  access(2)).  Most  operating  systems
    support the following bit definitions: 
    
    	0	Check if file exists 
    	1	Check to see if file is executable 
    	2	Check if file is writable 
    	3	Check if file is readable 
    
    
RETURN VALUE     
    On  successful  return this function returns >= 0; -1 is
    returned on an error, and the global variable  errno  is
    set to the reason for the failure. 
                       acos(float_expr) 
    
DESCRIPTION      
    Returns  the  inverse cosine value of the expression, in
    the range [-pi/2, pi/2]. float_expr must be in the range
    [-1, 1]. 
    
RETURN VALUE     
    Arc-cosine of the passed argument (in radians). 
                       asin(float_expr) 
    
DESCRIPTION      
    Returns the inverse sine value of the expression, in the
    range [-pi/2, pi/2]. float_expr must  be  in  the  range
    [-1, 1]. 
    
RETURN VALUE     
    Arc-sine of the passed argument (in radians). 
                       atan(float_expr) 
    
DESCRIPTION      
    Returns  the inverse tangent value of the expression, in
    the range [-pi/2, pi/2]. 
    
RETURN VALUE     
    Arc-tangent of the passed argument (in radians). 
                         atan2(x, y) 
    
DESCRIPTION      
    Returns the inverse tangent of y/x in  the  range  [-pi,
    pi]. 
    
RETURN VALUE     
    Arc-tangent of (y/x) (in radians). 
                assign_to_key([key], [macro]) 
    
DESCRIPTION      
    This  macro  is  used to bind a macro to a function key.
    The key is given by the string parameter,  key,  and  if
    omitted  is prompted for. key may be specified as either
    an internal key code, or may be specified by a  portable
    abbreviation.  The  portable  abbreviations  are   given
    below. 
    
    macro  is  a  string  containing  the name of a macro to
    execute when that key is pressed. 
    
    If key evaluates to more than one keystroke,  then  this
    is  defined  as a multi-key sequence, i.e. more than one
    key must be pressed to execut the macro. In  this  case,
    an  internal key code is assigned for this key, as if it
    were a builtin key. This internal key code  is  returned
    as  the value of this macro. Muilti-key sequences do not
    time out between key presses unlike the  other  internal
    keys when there is an ambiguity. 
    
    (The  backslash  character  can  be used to turn off the
    effect of the special characters). key is a string which
    may take one of the following forms: 
    
    |==========|=============================================|
    |Key       |Description                                  |
    |==========|=============================================|
    |x         |The actual key 'x'.                          |
    |__________|_____________________________________________|
    |^x        |The key control-x.                           |
    |__________|_____________________________________________|
    |#123      |The key whose internal key  code  is  123.   |
    |          |This  method  of  defining  keys  is   not   |
    |          |recommended.   It    is    provided    for   |
    |          |compatability with BRIEF, but  is  useless   |
    |          |since  BRIEF  allows PC keyboard scancodes   |
    |          |to be entered in  this  way.  PC  keyboard   |
    |          |scancodes  have  very   little   relevance   |
    |          |outside of DOS.                              |
    |__________|_____________________________________________|
    |xyz       |The  sequence  of  keys  x, followed by y,   |
    |          |followed by z. This allows  multiple  keys   |
    |          |to  be bound to a macro. Note that this is   |
    |          |not the same as using  set_term_keyboard()   |
    |          |to define a key.                             |
    |__________|_____________________________________________|
    |<Fn>      |when  n  is in the range 1..255. This is a   |
    |          |synonym for Function Key n.                  |
    |__________|_____________________________________________|
    |<Ctrl-Fn  |Ctrl, Shift and Alt versions  of  function   |
    |>         |keys. (Alt-Fn and Meta-Fn are synonymous).   |
    |<Shift-F  |                                             |
    |n>        |                                             |
    |<Alt-Fn>  |                                             |
    |          |                                             |
    |<Meta-Fn  |                                             |
    |>         |                                             |
    |__________|_____________________________________________|
    |<Alt-x>   |where  n is an upper or lower case letter.   |
    |<Meta-x>  |The case of the letter is ignored. On  the   |
    |          |Sun  keyboard,  LEFT/RIGHT  act as the ALT   |
    |          |key for the main keyboard only.              |
    |__________|_____________________________________________|
    |<Alt-n>   |where n is in the  range  0..9.  On  a  PC   |
    |<Meta-n>  |keyboard  this  means the top numeric keys   |
    |          |with the  ALT  key  pressed.  On  a  Sun-3   |
    |          |keyboard,  this  is the same as LEFT/RIGHT   |
    |          |pressed whilst hitting a digit key.          |
    |__________|_____________________________________________|
    |<Ins>     |The keypad Insert key.                       |
    |__________|_____________________________________________|
    |<Del>     |The DELETE key.                              |
    |__________|_____________________________________________|
    |<Backspa  |The backspace key.                           |
    |ce>       |                                             |
    |__________|_____________________________________________|
    |<Keypad-  |The '-' key on the keypad.                   |
    |minus>    |                                             |
    |__________|_____________________________________________|
    |<Keypad-  |The '+' key on the keypad.                   |
    |plus>     |                                             |
    |__________|_____________________________________________|
    |<Enter>   |The ENTER or RETURN key.                     |
    |__________|_____________________________________________|
    |<Esc>,    |Same as keys labelled as such on keyboard.   |
    |<Tab>,    |On keyboards which dont have markings  for   |
    |<PgDn>,   |these  keys,  various  approximations  are   |
    |<PgUp>,   |possible. Refer to the tty/*.cr files  for   |
    |          |further details.                             |
    |<Left>,   |                                             |
    |<Right>,  |                                             |
    |          |                                             |
    |<Up>,     |                                             |
    |<Down>,   |                                             |
    |<Home>,   |                                             |
    |<End>     |                                             |
    |==========|=============================================|
    
RETURN VALUE     
    Key  value  assigned  to   sequence   or   -1   if   key
    sequence invalid or operation aborted. 
                     atoi(string, [char]) 
    
DESCRIPTION      
    This  macro  converts  string,   which   is   a   string
    representation of a decimal number to binary. If char is
    specified and is zero, then the ascii value of the first
    character in string is returned. 
    
RETURN VALUE     
    Returns  integer  value of argument string treated as an
    ascii number or the ascii value of the  first  character
    in string if char is zero. 
                    attach_buffer(bufnum) 
    
DESCRIPTION      
    This  command  attaches  the  specified  buffer  to  the
    currently selected window. This means that the next time
    the window is refreshed the  specified  buffer  will  be
    displayed in the current window. 
    
    When  the  specified  buffer  is attached to the current
    window, the top  title  of  the  window  is  changed  to
    reflect  the  buffer  or  filename  associated  with the
    buffer. 
    
    This call is necessary  after  changing  a  window  with
    set_window().  Take care to ensure that when a window is
    refreshed on the screen that  it  always  has  a  buffer
    attached to it, otherwise CRISP may core dump. 
    
    This  command  is  only  intended  for  use   by   macro
    programmers,  and macros using attach_buffer() should be
    frequently saved during development to avoid  unexpected
    crashes. 
    
RETURN VALUE     
    No value is returned. 
    
EXAMPLES      
    The following example shows the outline of a macro which
    attaches a new buffer to the current window. 
    
    	int	newbuf = user_func(); 
    	attach_buffer(newbuf); 
    	 
    	/* Refresh screen with new buffer contents. */ 
    	refresh(); 
    
    
SEE ALSO     
    create_buffer(),  create_window(), inq_buffer(), inq_win
    inq_window() 
             autoload(file, macro1, [macro2], ..) 
    
DESCRIPTION      
    This macro is used to define the whereabouts of  macros.
    Whenever  CRISP  encounters a reference to a macro which
    is not currently defined, it searches an  internal  list
    to  see  if an autoload() macro has mentioned it. If so,
    the file parameter says in which file it  can  find  the
    macro. 
    
    file  should  be  specified as the basename of the macro
    file (i.e. without a .m or .cm suffix). This lets  CRISP
    search  the BPATH variable to see if it can find a .m or
    .cm file. 
    
    If it finds the file, it then  performs  a  load_macro()
    operation. If the macro definition is still not resolved
    after  auto-loading the macro file, then CRISP prints an
    error message. 
    
    An arbritrary number of macro names may appear after the
    file parameter. 
    
    autoloading is a useful feature since it speeds CRISP up
    in that it doesn't need  to  load  macros  which  aren't
    referenced. 
    
RETURN VALUE     
    Nothing. 
                         backspace() 
    
DESCRIPTION      
    This  deletes the character to the left of the cursor in
    the current buffer. If the cursor is at the beginning of
    the line then the current line is appended to the end of
    the previous line. 
    
RETURN VALUE     
    Nothing. 
                            beep() 
    
DESCRIPTION      
    This macro sends a bell or beep to the screen causing an
    audible sound. This macro can be used by error macros. 
    
RETURN VALUE     
    Nothing. 
                     beginning_of_line() 
    
DESCRIPTION      
    Moves cursor to column 1 of the current buffer. 
    
RETURN VALUE     
    Nothing. 
                     below(expr1, expr2) 
    
DESCRIPTION      
    This primitive  is  a  functional  version  of  the  '<'
    operator.  expr1  &  expr2  must  either be both integer
    expressions or string expressions. 
    
RETURN VALUE     
    Returns 1 if expr1 and  expr2  are  integer  values  and
    expr1 is less than expr2; returns 1 if expr1 & expr2 are
    string  expressions and expr1 lexicographically preceeds
    expr2. Returns 0 otherwise. 
                    below_eq(expr1, expr2) 
    
DESCRIPTION      
    This primitive is  a  functional  version  of  the  '<='
    operator.  expr1  &  expr2  must  either be both integer
    expressions or string expressions.  
    
RETURN VALUE     
    Returns 1 if expr1 and  expr2  are  integer  values  and
    expr1  is less than or equal expr2; returns 1 if expr1 &
    expr2 are string expressions and expr1 lexicographically
    follows expr2 or is equal to expr2. Returns 0 otherwise.
    
                       bookmark_list() 
    
DESCRIPTION      
    This macro can be used to return a list  containing  all
    currently defined bookmarks, or NULL if no bookmarks are
    defined. The list is a list of 4-tuples in the following
    format: 
    
    	{id, buf_id, line_no, col} 
    
    
RETURN VALUE     
    List containing all currently defined bookmarks. 
    
SEE ALSO     
    delete_bookmark(), drop_bookmark(), goto_bookmark() 
                       borders([expr]) 
    
DESCRIPTION      
    This  macro can be used to turn off borders for windows.
    By default they are on. 
    
    If expr is omitted, then the current value  is  toggled.
    Otherwise  the  internal  toggle  is set to the value of
    expr. Non-zero means borders are on. 
    
    On some terminals, having  borderless  windows  is  less
    expensive  on screen updating than on others, because of
    the overhead involved in drawing the borders around  the
    windows. 
    
RETURN VALUE     
    Returns  zero  if  borders  are  turned off; non-zero if
    borders are enabled for windows. 
                            break; 
    
DESCRIPTION      
    The break statement is used to terminate switch,  while,
    do and for loops. 
    
RETURN VALUE     
    Nothing. 
                          (breaksw) 
    
DESCRIPTION      
    The breaksw primitive is internal to the lisp-like macro
    language  only.  It  is generated by the crunch compiler
    when a 'break' keyword is encountered  inside  a  switch
    statement. 
    
RETURN VALUE     
    Nothing. 
                   call_registered_macro(n) 
    
DESCRIPTION      
    This  macro  is used to trigger a registered macro. n is
    an integer expression specifying the registered macro to
    trigger. 
    
    See  register_macro()   for   further   details  on  the
    different registered macro types. 
    
RETURN VALUE     
    Nothing. 
                        car(list_expr) 
    
DESCRIPTION      
    This macro is used to make a copy of the first  atom  in
    the expression list_expr. 
    
    Since  lists  may  contain any data type, it is probably
    wise to assign the  result  of  a  car  operation  to  a
    polymorphic  variable,  so  that   its   type   can   be
    ascertained. 
    
EXAMPLES      
    The  following example prints a message saying what type
    the variable at the head of a list is: 
    
    	list	llist; 
    	message("Type is %s.", typeof(car(llist))); 
    
    
RETURN VALUE     
    Returns the value of the first element in the list_expr.
    
SEE ALSO     
    cdr(), nth(), put_nth() 
                          cd([path]) 
    
DESCRIPTION      
    This macro changes the  current  working  directory.  If
    path  is  omitted, then the current path is displayed on
    the status line. 
    
EXAMPLES      
    Display current path on screen: 
    
    	cd(); 
    
    
    Change to users home directory: 
    
    	cd(inq_environment("HOME")); 
    
    
RETURN VALUE     
    0 if unsuccessful; non-zero if path changed. 
                        cdr(list_expr) 
    
DESCRIPTION      
    The cdr() macro is used to create a new list out  of  an
    existing list by removing the first atom in the list. 
    
    Using  car()  and  cdr(),  macros  can  be written which
    manipulate all elements on a list. However, it  is  more
    efficient  to  use nth() to extract individual elements,
    since internally it avoids having to copy sub-lists. 
    
RETURN VALUE     
    Returns the list formed by deleting the first element of
    the list, list_expr. 
                           ceil(x) 
    
RETURN VALUE     
    Returns smallest integer not larger than x. Return value
    is a floating point number. 
              change_window([direction], [msg]) 
    
DESCRIPTION      
    This macro is used to move to another window.  direction
    specifies in which direction to select the window. If it
    is  omitted,  then  the  user  is prompted to select the
    window, by using the cursor keys. 
    
    If direction is specified, it should  have  one  of  the
    following values: 
    
    	0	Up 
    	1	Right 
    	2	Down 
    	3	Left. 
    	4	'Other' window. 
    
    
    The  msg parameter allows the calling macro to customise
    the  message  appearing  on  the  status  line.  If  not
    omitted, the string "Point to destination" is used. 
    
RETURN VALUE     
    Returns 0 if unsuccessful; 1 if successful. 
                      chmod(mode, file) 
    
DESCRIPTION      
    This primitive is used  to  change  the  protection  and
    access  information  associated with a file. mode is the
    set of protection bits  as  defined  by  your  operating
    system,  and  file  is the name of the file or directory
    which should be changed. 
    
RETURN VALUE     
    Returns 0 on success, -1 on failure. On  a  failure  the
    global value errno is set to the reason for the failure.
    
    color([background],  [normal],   [region],   [messages],
             [errors], [hilite], [hi_foreground]) 
    
DESCRIPTION      
    This macro is used to control the colors that CRISP uses
    on  a  color  display.  (The  values  are  ignored   for
    monochrome displays). 
    
    If  any  of the first 6 parameters are omitted, then the
    values are prompted for. 
    
    background is the color for  the  background  of  normal
    text.  normal  is  the color associated with text in the
    editing windows. region is the color of text when it  is
    marked  in  a  region.  messages is the color for normal
    messages on the status line. errors is  the  colors  for
    error  messages  on  the  status line. hilite is used to
    indicate the relationship between highlited text and its
    background. 
    
    Colors may be specified as integers or strings.  Strings
    may  be  specified  in  upper  or lower case. The hilite
    parameter is to specify the  foreground  and  background
    color of hilighted text. It may be a number of a string.
    If  it  is  a  number  then the top nibble specifies the
    background color, and  the  low  nibble  the  foreground
    color.  If  it  is  a  string then it only specifies the
    background  color.  If  hi_foreground  is  specified  it
    specifies the foreground color of the hilighted region. 
    
    
    
    |==========|====================|
    |Color     |Color name          |
    |no        |                    |
    |==========|====================|
    |0         |Black               |
    |1         |Blue                |
    |2         |Green               |
    |3         |Cyan                |
    |4         |Red                 |
    |5         |Magenta             |
    |6         |Brown               |
    |7         |White               |
    |8         |Dark-Grey           |
    |9         |Light-Blue          |
    |10        |Light-Green         |
    |11        |Light-Cyan          |
    |12        |Light-Red           |
    |13        |Light-Magenta       |
    |14        |Light-Yellow        |
    |15        |Light-White         |
    |==========|====================|
    
    
RETURN VALUE     
    Nothing. 
                        command_list() 
    
DESCRIPTION      
    This macro is used to get a list of all the keywords  in
    CRISP.  Its primary purpose is to support the help macro
    package, and avoids hardcoding the macro primitives into
    a macro or text file. 
    
    
SEE ALSO     
    macro_list() 
    
RETURN VALUE     
    Returns a list consisting of a sequence of strings which
    are the names of all the CRISP macro primitives and  all
    currently defined macro names. 
                   compress(string, [trim]) 
    
DESCRIPTION      
    This macro takes a string and removes all multiple white
    space characters (spaces, tabs and newlines). If trim is
    specified   then    compress()   acts   the   same   as:
    trim(ltrim(compress(str))). 
    
    
RETURN VALUE     
    Returns a copy of  string  with  all  spaces,  tabs  and
    newlines mapped to single spaces. 
                   connect([mode], [shell]) 
    
DESCRIPTION      
    This macro is used to create a sub-process and associate
    it with the current buffer. 
    
    mode  specifies  some  flags which are defined below. By
    default, the process created is a shell process, and the
    shell is got from the  SHELL  environment  variable.  If
    shell  is specified, then it is taken as the pathname of
    a shell to execute. 
    
    Output from a sub-process is automatically inserted into
    the buffer, at a position known as the process  position
    (see  inq_process_position(),   set_process_position()).
    This position is analagous to the usual input cursor. 
    
    Any  text  which  would  normally  be  inserted into the
    buffer via self_insert(), insert() or  paste()  is  also
    forwarded to the sub-process. 
    
    CRISP  implements  sub-processes  out  of pipes or pty's
    depending on the availability  of  the  underlying  Unix
    implementation.  When  using  pipes,  CRISP  samples the
    output from the pipe on a 1 second interval.  Ptys  have
    better  interaction  since  the  select() system call is
    used. 
    
    mode is a set of flags which have the following meaning:
    
    
    
    |==========|========================================|
    |Value     |Description                             |
    |==========|========================================|
    |0x01      |If this bit is set, then  the  buffer   |
    |          |operates  in  echo  mode,  i.e.   the   |
    |          |characters  which   are   typed   are   |
    |          |inserted into the buffer. If this bit   |
    |          |is  not set, then the buffer operates   |
    |          |in no-echo mode, and  the  characters   |
    |          |the  user  types  are  not   directly   |
    |          |inserted into the buffer, but instead   |
    |          |only the output from the sub-process.   |
    |__________|________________________________________|
    |0x4000    |This  bit  indicates  whether  output   |
    |          |from a process overwrites text in the   |
    |          |buffer or  inserts  and  shifts  text   |
    |          |over as it does so. This is needed to   |
    |          |effectively allow typeahead to not be   |
    |          |destroyed  but allow escape sequences   |
    |          |to cause data in  the  buffer  to  be   |
    |          |overwritten  when   running   termcap   |
    |          |oriented programs.                      |
    |__________|________________________________________|
    |0x8000    |This  is  the wait mode of operation.   |
    |          |Normally when a  buffer  is  created,   |
    |          |the  output  from  the  subprocess is   |
    |          |inserted directly  into  the  buffer.   |
    |          |Setting  this  bit  causes the output   |
    |          |from the process  to  be  held  onto,   |
    |          |until  the  calling  macro  issues  a   |
    |          |wait() or waitfor() macro call.         |
    |==========|========================================|
    connect()  may   be  called  after  a  buffer  has  been
    connected to change the mode flag. 
    
RETURN VALUE     
    Returns 0 if buffer  already  connected;  returns  1  if
    buffer has been successfully connected. 
                          continue; 
    
DESCRIPTION      
    This  macro is used to finish the current iteration of a
    while() loop, and go  back  to  the  top  of  the  loop,
    causing the while condition to be re-evaluated. 
    
    This works similar to the C continue statement. 
    
RETURN VALUE     
    Nothing. 
                        copy([append]) 
    
DESCRIPTION      
    copy()  copies  the currently marked region to the scrap
    buffer, and un-highlites the currently marked region. 
    
    If append is specified and is non-zero, then the text is
    appended to the current scrap without deleting it first.
    
RETURN VALUE     
    Nothing. 
              copy_keyboard(src_id, [cmd1 ...]) 
    
DESCRIPTION      
    This macro is used  to  copy  key  assignments  from  an
    alternate keyboard id. cmd1, ..., are strings containing
    macro  names.  These  macro  names  are looked up in the
    source keyboard and if found are assigned  to  the  same
    keystrokes  used  in the source keyboard. If no commands
    are specified, then the entire keyboard is copied. 
    
    This macro is very useful for popup displays because  it
    allows  the  macro  writer  to ensure that if a user has
    tailored the keyboard layout that the popup will use the
    same keys at the main editing level, without  having  to
    hard-code constants all over the place. 
    
RETURN VALUE     
    Returns  current  keyboard  id  on  success.  If  source
    keyboard not found then returns zero. 
                            cos(x) 
    
RETURN VALUE     
    Cosine of x (in radians) as a floating point value. 
                           cosh(x) 
    
RETURN VALUE     
    Hyperbolic-cosine of x as a floating point value. 
    create_buffer(buffer-name,   [file-name],      [system],
                        [edit_flags]) 
    
DESCRIPTION      
    This macro is used to create a new buffer. The buffer is
    given  the  name "buffer-name" which may be any sequence
    of ASCII characters. This buffer name is used  to  label
    the  top  of  any windows the buffer is attached to (see
    attach_buffer).  Care  should  be  chosen  in  selecting
    buffer names, since  the  top  title  on  any  displayed
    window may be truncated if the window is not wide enough
    to handle the title. 
    
    "file-name"  is the full or relative path name of a file
    which should be read into the buffer. If this  parameter
    is  omitted,  then  an  initially  empty  buffer will be
    created. The "file-name" read into the buffer  is  saved
    for  later  use,   if   the   buffer   is   saved   (via
    write_buffer). 
    
    [system]  is an optional integer which indicates whether
    the buffer is to be a system buffer or user  buffer.  If
    it  is 0 or omitted, then the buffer is a user buffer; a
    non-zero value indicates a system buffer. System buffers
    are like normal buffers, except for two  side-effects  -
    no  undo() information is saved for operations on system
    buffers, and  most  high-level  macros  tend  to  ignore
    system  buffers,  e.g.  the buffer_list() macro does not
    usually display system buffers. 
    
    edit_flags is used to control  how  the  specified  file
    will  be  read in to the buffer. These flags are used to
    force CRISP to read the file in ascii, binary or  normal
    modes.  Refer   to   the   edit_file()   primitive   for
    information describing this field. 
    
    System  buffers  are  for  use  by  user macros or CRISP
    supplied macros and provide a way of storing information
    without  getting   in   the  way  of  the  user.  undo()
    information is not saved for  these  buffers,  and  thus
    means  that  operations  on  system buffers are slightly
    faster than normal buffers. It  is  not  important  that
    undo()  information  is  not  stored with these buffers,
    because these buffers tend to only be manipulated by the
    various macros - not directly by the user. 
    
EXAMPLES      
    The following example shows how to create a  buffer  and
    display  it  in  the  current window. edit_file() may be
    more appropriate  for  this  particular  task,  but  the
    example is illustrative. 
    
    	int	newbuf; 
    	 
    	newbuf = create_buffer("My Buffer", "myfile.txt"); 
    	attach_buffer(newbuf); 
    	 
    	refresh(); 
    
    
RETURN VALUE     
    Returns  the buffer identifier associated with the newly
    created buffer. 
    create_char_map([cmap_id],    [start_ch],       ch_list,
                        [flags_list]) 
    
DESCRIPTION      
    This primitive creates a character map. A character  map
    is a mapping between the characters stored in the buffer
    and  the  way  they are printed on the screen. Character
    maps have two main  uses  -  to  configure  how  control
    characters  and characters with the top bit are printed,
    or to view characters in a different format, e.g. hex. 
    
    If cmap_id is not specified, then a new character map is
    created. If cmap_id is specified it should be an integer
    value corresponding to a  previously  created  character
    map (or zero to change the default one). 
    
    Character  maps  are a mapping for all 256 possible byte
    values. The ch_list parameter is a list giving upto  256
    value  for  these  sequences.  If you only want to remap
    part of the  displayable  character  set,  then  specify
    start_ch to indicate where you are starting. 
    
    ch_list  may  have  upto  257 values. The 257th entry is
    used to indicate how the end of a line should be marked.
    By default, the end of line is marked with a space (i.e.
    not  distinguishable).   The  literal  macro  uses  this
    character to specify a '$' to mark end of lines. 
    
    CRISP understands that  certain  displayable  characters
    need  special processing. These characters are specified
    by the optional flags_list parameter. The flags list  is
    specified  as  a pairing of values. The first element in
    the pair is an integer defining the character value, and
    the second entry in the pair indicates the action to  be
    performed. The following actions are defined: 
    
    
    
    |========|==============================|
    |Value   |Meaning                       |
    |========|==============================|
    |0       |No special processing.        |
    |________|______________________________|
    |1       |Character is a tab.           |
    |________|______________________________|
    |2       |Character is a backspace.     |
    |________|______________________________|
    |3       |Character is an ESCAPE.       |
    |========|==============================|
    
    Backspace  and  ESCAPE  flags are needed if you want the
    ANSI processing mode to work. 
    
    For examples of  this  primitive,  consult  the  view.cr
    macro. 
    
RETURN VALUE     
    Returns the character map ID, or -1 if the specified map
    does not exist. 
    
SEE ALSO     
    inq_char_map(),  set_buffer_cmap(),  set_buffer_flags(),
    set_window_cmap() 
                   create_edge([direction]) 
    
DESCRIPTION      
    This macro is used to  split  the  current  window.  The
    window is split in the direction specified. If direction
    is  not specified then the user is prompted, and can use
    the arrow keys to indicate the direction of the split. 
    
    If direction is specified, it should  have  one  of  the
    following values: 
    
        	0	Up 
        	1	Right 
        	2	Down 
        	3	Left. 
    
    
RETURN VALUE     
    Returns 0 if unsuccessful; 1 if successful. 
          create_tiled_window(lx, by, rx, ty, [buf]) 
    
DESCRIPTION      
    This  macro is used to create a tiled window (as opposed
    to a popup window). Normally tiled  windows  (background
    windows)  are  created by the user splitting the current
    window.  This   macro   is   provided   to   allow   the
    implementation of the state restore macro  so  that  the
    window  layout  can  be saved and restored on restarting
    CRISP. 
    
    The (lx,by,rx,ty) arguments are the co-ordinates of  the
    window,  irrespective  of whether borders are enabled or
    not, with (0,0) being the top left hand  corner  of  the
    screen. 
    
    buf  is  an  optional  integer containing a buffer ID to
    attach to the created window. 
    
    It is probably  best  to  disable  the  screen  updating
    whilst using this macro, otherwise the screen may become
    inconsistent. (Refer to the display_windows() macro). 
    
RETURN VALUE     
    Returns the window id of the created window. 
    create_window(left_x,   bottom_y,    right_x,     top_y,
                          [message]) 
    
    
DESCRIPTION      
    This  macro  is  used  to  create  a new window. left_x,
    bottom_y, right_x and top_y specifies  the  co-ordinates
    of the window. 
    
    message  is  an  optional  string  expression,  which if
    specified is a message to appear centered on the  bottom
    line of the window. 
    
    Be careful not to create windows which do not fit within
    the physical screen, otherwise CRISP may crash. 
    
    The  new window created becomes the current window - its
    id can be inquired via inq_window(). 
    
RETURN VALUE     
    Returns the window ID of the new window. 
                        cut([append]) 
    
    
DESCRIPTION      
    
    The currently highlited region is copied  to  the  scrap
    buffer and the region deleted from the current buffer. 
    
    If  append  is  specified  and  is  non-zero,  then  the
    highlited region is appended to the  end  of  the  scrap
    buffer, without first clearing it. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                  cvt_to_object(val, [len]) 
    
    
DESCRIPTION      
    
    cvt_to_object  may  be used to parse a string and decode
    the object contained in it, e.g. a number, or  a  float.
    It  is  the  converse  to  sprintf(), and may be used to
    parse a string which may be input by the user or created
    by a program for decoding. The 'val' parameter should be
    a string which contains the object to be decoded. 
    
    len is an optional integer variable which  will  receive
    the  number  of characters used in the parsing. This may
    be useful if the string contains  multiple  items  which
    will need parsing. 
    
    
RETURN VALUE     
    
    Value  of  'val'.  The  value is an integer, or float or
    string depending on  the  syntax  of  the  item  in  the
    expression. 
    
    If  the  item cannot be parsed, then the NULL value will
    be returned. 
    
    
     date([year], [mon], [day], [month-name], [day-name]) 
    
    
DESCRIPTION      
    
    This macro retrieves the current date. year, mon and day
    are optional integer variable names  which  receive  the
    current  year,  month  number,  and day of month number.
    Year is of the form 1988; mon is in the range 1-12;  day
    is in the range 1-31. 
    
    month-name  is an optional string variable, and contains
    the name of the month, in the format: January;  day-name
    is an optional string variable containing the day of the
    week, in the form: Saturday. 
    
    
RETURN VALUE     
    Nothing. 
    
EXAMPLES      
    
    The  following  example can be used to print an american
    date string: 
    
    
    	int	day, mon, year; 
    	date(year, mon, day); 
    	message("%02d/%02d/%02d", mon, day, year - 1900); 
    
    
                          debug([n]) 
    
DESCRIPTION      
    debug turns on or off the macro trace mode.  When  debug
    is  on,  CRISP  traces  the  execution  of  every  macro
    statement, and in addition  traces  assignments  to  the
    accumulators (integer, string and list). 
    
    This is the primary means of debugging macros. 
    
    If n is omitted, then debugging is toggled and a message
    is printed on the status line saying whether debug is on
    or off. 
    
    By default, debug toggles between 0 and 1. By specifying
    a  value  for the debug macro, other events in CRISP can
    be traced. The other bits are mostly for debugging CRISP
    itself, and include the ability to trace the following: 
    
    |==========|========================================|
    |Flag      |Meaning                                 |
    |==========|========================================|
    |0x01      |Trace macro execution.                  |
    |__________|________________________________________|
    |0x02      |Trace  regular   expression  parsing.   |
    |          |This is used to  check  that  regular   |
    |          |expressions  are  being  compiled and   |
    |          |executed correctly.                     |
    |__________|________________________________________|
    |0x04      |Trace buffer undo() information.  Use   |
    |          |this  to  check  that  a primitive is   |
    |          |recording the correct information  to   |
    |          |undo it.                                |
    |__________|________________________________________|
    |0x08      |Cause  log  file  to  be flushed each   |
    |          |time it is written to. This is useful   |
    |          |when CRISP core dumps and you want to   |
    |          |see the last primitive executed. This   |
    |          |significantly slows down operation.     |
    |__________|________________________________________|
    |0x4000    |Turns  on   tracing  for  the  prompt   |
    |          |history code. This  traces  execution   |
    |          |of the command  line macros.            |
    |==========|========================================|
    
    When  debug is turned on, all debug output is put in the
    file /tmp/crisp.log.  The  name  of  this  file  can  be
    overridden  by  specifying  the   environment   variable
    CRISP_LOG. 
    
    If  the  user  is  trying  to debug a macro which causes
    CRISP to core dump, then CRISP should be run with the -f
    flag. This causes all debug info to be  flushed  to  the
    log  file as it is produced, rather than using the stdio
    buffering.  By   default   this   is   off,   since   it
    significantly slows CRISP down due to the high volume of
    output. 
    
    
EXAMPLES      
    
    The following is a small trace of debug output caused by
    reformatting this paragraph with the ^F key. 
    
    *** DEBUG ON (0x0001) *** 
    02:.......  iACC=5 
    01:......  iACC=5 
    
    KEY_EXEC 0x404c => mark 3 
    	 (mark 3 ) 
    	   iACC=3 
    
    KEY_EXEC 0x0006 => objects format_block 
    Execute macro: objects 
    02:.......(string function ) 
    	  (int arg1 ) 
    	  (get_parm 0 function ) 
    	    function := format_block 
    	    iACC=1 
    	  (get_parm 1 arg1 ) 
    	    iACC=0 
    	  (string macro_name ext ) 
    	  (inq_names NULL ext NULL ) 
    	    ext := h 
    	    iACC=0 
    	  (= macro_name (..) ) 
    	  (+ (..) function ) 
    	  (+ ext "_" ) 
    	    lookup ext = 'h' 
    	    sACC='h_' 
    	    lookup function = 'format_block' 
    	    sACC='h_format_block' 
    	    macro_name := h_format_block 
    	    rsACC='h_format_block' 
    	  (if (..) (..) ) 
    	  (! (..) ) 
    	  (inq_macro macro_name ) 
    	    lookup macro_name = 'h_format_block' 
    	    iACC=1 
    	    iACC=0 
    	    iACC=0 
    	  (execute_macro macro_name arg1 ) 
    	    lookup macro_name = 'h_format_block' 
    03:........(macro wp_options (..) ) 
    	   (macro autowrap (..) ) 
    	   (macro get_autowrap (..) ) 
    
    
