    set_term_keyboard(range1,  key-list1, range2, key-list2,
                             ..) 
    
    
DESCRIPTION      
    
    This macro is used to define the keyboard bindings.  The
    keyboard  bindings  is  an  internal  table   to   CRISP
    describing  which physical keys on the keyboard generate
    which internal key code. 
    
    When a key is pressed CRISP scans the internal key  code
    table  to  see if the character it has just read is part
    of a function key sequence. If  so  it  waits  until  it
    receives  an  unambiguous  string  of  characters either
    identifying the function key or a sequence typed by  the
    user. 
    
    This  primitive  allows  the  user  to  define  mappings
    between the escape sequences generated by  the  function
    keys and the internal key codes. It also allows multiple
    physical  keys  to  be  mapped  to the same internal key
    code. For example, on a Sun keyboard the L1 and F1  keys
    can  be mapped so that they are indistinguishable by the
    various macro primitives. 
    
    The internal function keys are given numbers out of  the
    range of 8-bit ASCII characters. 
    
    On  non-PC  keyboards, e.g. SUN-3 keyboard, the function
    keys and LEFT/RIGHT keys can be used  as  a  'META'  key
    prefix (much the way ALT is used on a PC keyboard). 
    
    The  arguments  to  set_term_keyboard()  consists  of  a
    sequence of ranges and key-lists. The  ranges  exist  to
    make  it  easy  to  allocate the keys and read the macro
    afterwards. This avoids having to call this  macro  with
    upwards  of  100  key  definitions,  and  the  resultant
    inability  to   decipher   mistakes  made  on  the  51st
    argument, for example. 
    
    The include file tty.h defines the ranges.  A  range  is
    simply  a  number.  The first function keys (<F1>..<F12>
    start at 128). By specifying a range of 128, this  means
    that  consecutive  key  definitions  will  start at this
    range, and be allocated consecutive slots from  thereon.
    (See  the  tty-*.m  files  for  an  example  of how this
    works). 
    
    The key-list is simply a list of strings describing each
    consecutive key. If the keys are to be hard-wired,  then
    the quote_list() function will be very useful. Otherwise
    the  list  can  be  constructed  with  the  other   list
    primitives. 
    
    Ambiguous  key prefixes are allowed. This allows keys to
    be defined with the  usual  ESC-type  prefixes.  If  the
    start  of an ambiguous key sequence is typed, then CRISP
    will wait upto .5 second for more keystrokes to  resolve
    the  ambiguity.  After  this  time,  CRISP  treats   the
    original  ambiguous  characters  as  standalone. On some
    keyboards, viz. Suns, RTPCs, Microport and  Interactive,
    this  means that hitting the ESCape character will delay
    progress for 0.5 second, until CRISP  realises  that  no
    more keys are coming. 
    
    Because  of  this  ambiguity problem, problems can arise
    when using CRISP across a  network,  for  example.  When
    using  applications  like telnet, keeping your finger on
    the <Up> or <Down> keys, etc, can cause CRISP to misread
    the keyboard, with the effect that instead  of  treating
    something like ESC[A as <Up>, it treats it as the single
    characters,  ESC,  [, A causing them to be inserted into
    the buffer. I do not know of any cure for  this,  except
    to  increase the default .5 second timer. Increasing the
    .5 second timer inside CRISP causes the side effect that
    hitting the ESC  key  at  the  buffer_list  prompt,  for
    example, causes an annoying delay. 
    
RETURN VALUE     
    
    Nothing. 
    
    
    
EXAMPLES      
    
    The  following  example  is  the  first  section  of the
    set_term_keyboard() macro from  the  tty/at386.cr  macro
    file. 
    
    	set_term_keyboard(F1_F12,  
    		quote_list("\x1BOP", "\x1BOQ", 
    			"\x1BOR", "\x1BOS", "\x1BOT", "\x1BOU", 
    			"\x1BOV", "\x1BOW", "\x1BOX", "\x1BOY",  
    			"\x1BOZ", "\x1BO[")); 
    
    
    set_top_left([line],   [col],    [win_id],    [csrline],
                       [csrcol], [buf]) 
    
    
DESCRIPTION      
    
    This macro is used to set the  position  of  the  buffer
    attached  to a window. It sets the display position. All
    variables are optional integer expressions. 
    
    line and col  are  optional  integer  expressions  which
    specify the line in the buffer which is to appear as the
    top  line  in  the  screen, and col specifies the column
    number which should appear in the top left hand position
    in the screen. 
    
    csrline and csrcol specify the buffer position to set in
    the associated buffer. 
    
    win_id specifies the window to use. buf indicates to use
    the window which  has  the  specified  buffer  attached.
    win_id is used first, and if not specified, then the buf
    parameter  is  used.  If  neither are specified then the
    current window is assumed. 
    
    
EXAMPLES      
    
    The following example  puts  the  current  line  in  the
    center  of the window (this is the macro normally mapped
    to <Ctrl-C>). 
    
    
    	set_center_of_window() 
    	{ 
    		int	cur_line; 
    
    		inq_position(cur_line); 
    		 
    		set_top_left(cur_line - inq_window_size() / 2); 
    	} 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                      set_window(win_id) 
    
    
DESCRIPTION      
    
    Changes the current window to the  window  specified  by
    win_id.  win_id  is  a  window identifier, as previously
    returned via inq_window(). 
    
RETURN VALUE     
    
    Nothing. 
    
    
             set_window_cmap([cmap_id], [win_id]) 
    
    
DESCRIPTION      
    
    This primitive is used to associate a character map with
    a window. A character  map  is  a  way  of  viewing  the
    underlying data in a buffer. The character map is simple
    a  map  of  each of the 256 possible byte values and the
    string to be printed. Character maps allow the  user  to
    write customised macros, for example to view a buffer in
    hexadecimal mode. 
    
    cmap_id  is a character map ID previously created by the
    create_char_map() primitive, or NULL to use the internal
    default map. 
    
    win_id is  the  window  to  set  the  map  for.  If  not
    specified, then the current window is used. 
    
SEE ALSO     
    create_char_map(), inq_char_map(), set_buffer_cmap(). 
    
RETURN VALUE     
    
    Nothing 
             set_wm_name(window_name, icon_name) 
    
    
Description      
    This function is used to allow a macro to set the window
    name  and/or  icon  name,  when CRISP is running under a
    windowing system. It is a no-op on other systems. 
    
    window_name and icon_name are string values. Either  one
    may  be  omitted in which case the appropriate name will
    not be modified. 
    
    This function is designed to allow macros to be  written
    which  can set the window name to the current directory,
    for example. 
    
RETURN VALUE     
    Nothing 
         shell([command], [use_shell], [completion]) 
    
    
DESCRIPTION      
    
    This command is used to execute a command  in  a  shell.
    command  is  a  string  expression  which evaluates to a
    command  (with   or  without  its  arguments)  which  is
    exec()ed by CRISP. 
    
    The use_shell parameter is an integer  expression  which
    controls  whether  the  display should be left intact or
    not. If it is omitted  or  zero,  then  CRISP  puts  the
    terminal  back  into normal cooked mode and executes the
    command  string.   When  the  sub-process  exits,  CRISP
    repaints the screen.  If  use_shell  is  non-zero,  then
    CRISP  does not repaint the screen. Setting use_shell to
    non-zero  is   useful  for  things  like  the  make  and
    directory manipulation macros which know the sub-process
    cannot destroy the screen. 
    
    The command string is passed to  the  shell  so  it  can
    execute  and interpret the command string (e.g. wildcard
    expansion, semicolons etc). The  shell  used  is  gotten
    from  the  SHELL environment variable. If this fails, it
    defaults to /bin/csh. 
    
    The return from this macro is the shell exit status. 
    
    If completion is specified, then it should be  the  name
    of  a  macro (in quotes - with optional arguments) which
    will be called when  the  sub-process  terminates.  When
    using  this  facility,  you  should  set  the  use_shell
    parameter to 1 to  avoid  CRISP  from  waiting  for  the
    sub-shell to complete. 
    
    The  completion  routine  is  called  with   the   first
    parameter  set  to the return status from the underlying
    process. Any other positional parameters are shifted  up
    one. 
    
    
EXAMPLES      
    
    The  following  macro  can  be used to get a subshell to
    type commands into. The user terminates the sub-shell by
    typing the usual ^D or exit. (This is the same  as  what
    <Alt-Z> is usually mapped to). 
    
    
    shell() 
    
    
    The  following  example  performs  a  who(1) command and
    saves the output in a  temporary  file  so  the  calling
    macro can maybe display it prettily afterwards: 
    
    
    	shell("who >& /tmp/who.tmp", 1); 
    
    
    The '1' tells CRISP not to bother repainting the screen.
    
    The  following  example causes a macro to be called when
    the sub-process terminates. The sub-process then  prints
    a message saying that the process has terminated. 
    
    	shell("make", 1, "completion"); 
    	 ... 
    	completion(int status) 
    	{ 
    		message("Job done, status = %d", status); 
    	} 
    
    
RETURN VALUE     
    
    Returns  the  shell  exit  status  (under  Unix, 0 means
    command  exited  successfully,  non-zero  means  command
    failed for some reason). 
    
    
                            sin(x) 
    
    
RETURN VALUE     
    
    Returns the sine of x (in radians) as a  floating  point
    number. 
    
SEE ALSO     
    cos, tan, asin, acos, atan 
                           sinh(x) 
    
    
RETURN VALUE     
    
    Returns  the  hyperbolic-sine  of  x as a floating point
    number. 
    
SEE ALSO     
    cosh, tanh 
                         sleep([sec]) 
    
    
DESCRIPTION      
    
    This macro causes the calling macro  to  sleep  for  sec
    seconds (or 1 if omitted). 
    
RETURN VALUE     
    
    Nothing. 
    
    
                    sort_buffer([bufnum]) 
    
    
DESCRIPTION      
    
    This  macro can be used to sort the lines in the current
    buffer or the buffer specified by bufnum. If the  buffer
    specified  has  a  region  marked, then only those lines
    within the region are sorted. 
    
    The lines  are  sorted  alphabetically  -  there  is  no
    mechanism  to  perform sorting based on keys within each
    line,  or   based   on   other  criteria,  e.g.  sorting
    numerically, etc. 
    
    Be wary of this macro -- if it is used on  a  non-system
    buffer, it is not possible to 'undo' the sort. 
    
    This  macro  is   an   experimental   macro,   and   its
    functionality may change in the future or be deleted. 
    
    
EXAMPLES      
    
    The following example sorts all the lines in the current
    buffer into order: 
    
    sort_buffer() 
    
RETURN VALUE     
    
    Nothing. 
    
    
               split(string, chars, [numeric]) 
    
    
DESCRIPTION      
    
    This macro can be used to parse a string and split it up
    into  tokens,  in  a  similar  manner  to the C function
    strtok, but it does the breaking up of the input  string
    in  one  go  and  returns  a  list of strings. The chars
    parameter is a  string  containing  delimiter  character
    used to split the tokens. 
    
    If numeric is specified and is non-zero, then all tokens
    which  start  with  a  digit  are converted to a number,
    rather than a string. 
    
    
EXAMPLES      
    
    The following example causes 'lst' to be assigned a four
    element list containing strings where each string is one
    of the words of the parameter. 
    
    	list lst; 
    
    	lst = split("The quick brown fox", " "); 
    
    
SEE ALSO     
    sscanf, index, substr. 
    
    
RETURN VALUE     
    
    List of strings where each string is a 'token' from  the
    string parameter. 
    
    
            sprintf(buf, fmt, [arg1], [arg2], ..) 
    
    
DESCRIPTION      
    
    This macro acts like the C sprintf() function. It copies
    the  string  'fmt'  to  the  string  variable  'buf' and
    applies  the   printf   style   formatting  commands  as
    specified in fmt, and using the argument list. 
    
    Refer  to   the  (message)  macro  for  details  on  the
    formatting options available. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                           sqrt(x) 
    
    
RETURN VALUE     
    
    Returns the square root of x, as a floating point value.
    
                        srand([seed]) 
    
    
DESCRIPTION      
    
    This macro is used to set a seed for the  random  number
    generator  returned  by rand(). If seed is not specified
    then the current time in  seconds  is  used.  Specifying
    seed  allows  the calling macro to have a repeatable set
    of random numbers. 
    
    
SEE ALSO     
    
RETURN VALUE     
    
    Nothing. 
    
    
            sscanf(string, format, sym1, sym2, ..) 
    
    
RETURN VALUE     
    
    Number of variables actually assigned to. 
    
    
DESCRIPTION      
    
    This function is similar  to  the  C  language  sscanf()
    function  and  is somewhat more generic than the split()
    function. It is used to parse a string and break  it  up
    into  constituent  elements  assigning   them   to   the
    specified variables. 
    
    THIS PRIMITIVE IS NOT YET IMPLEMENTED. 
                     _startup_complete(n) 
    
DESCRIPTION      
    This  macro  is a callback macro. It is called after all
    command line  switches  have  been  process,  after  all
    command  line  files  have  been  read in, and after the
    startup() macro has been called. The macro is passed  an
    integer  parameter, with the value 0 to indicate that no
    command line files were specified, or 1 to indicate that
    command line files were read in. 
    
    This macro  is  used  by  the  restore  macro  to  avoid
    restoring the state of buffers and files when files have
    been specified on the command line. 
    
    Refer  to  the  restore.cr  macro file for an example of
    this macro. 
                    string var1, var2, ..; 
    
    
DESCRIPTION      
    
    This macro is used to define local variables  which  are
    to contain only string values. The variables defined are
    local  variables,  and  are  destroyed  when  the  macro
    executing this declaration terminates. 
    
    String variables can  contain  variable  length  strings
    (upto 2^32 bytes long on machines with 32-bit int's, and
    2^16 bytes on machines with 16-bit int's). 
               string_count(string, char-list) 
    
    
DESCRIPTION      
    
    This macro is used to count the occurences of characters
    in  the  string argument. char-list can be a string with
    one or more characters in it.  The  string  argument  is
    parsed  looking  at  each character to see if any of the
    characters from char-list match it. 
    
    
EXAMPLES      
    
    The following example counts how many  spaces  occur  in
    the input string: 
    
    	string	s; 
    	int	num; 
    	 
    	num = string_count(s, " "); 
    
    
    The following example counts how many upper case letters
    appear in the input string: 
    
    	num = string_count(s, "ABCDEFGHIJKLMNOPQRSTUVWXYZ")); 
    
    
RETURN VALUE     
    
    Returns  the number of times the characters in char-list
    occur in the string parameter. 
    
    
                     strlen(expr, [step]) 
    
    
DESCRIPTION      
    
    This macro can be used to find out how long a string  is
    or  the  length of the longest string in a list. If expr
    is  a  list  expression,  then  step  indicates  whether
    certain entries should be skipped over, e.g. if the list
    contains paired tuples where the  odd  elements  of  the
    list are sub-lists, etc. If omitted, step defaults to 1.
    
    When finding the lengths of lists, it always starts with
    the  first  element of the list. strlen silently ignores
    none string elements in the list. 
    
RETURN VALUE     
    
    Returns  the   number   of   characters  in  the  string
    expression, expr or the length of the longest string  in
    the specified list. 
    
    
               substr(string, start, [length]) 
    
    
RETURN VALUE     
    
    Returns  the sub-string of string which starts at start,
    and goes on for length characters, or  the  end  of  the
    string if length is omitted. 
                          suspend() 
    
    
DESCRIPTION      
    
    This  macro  is  equivalent to typing Ctrl-Z if you have
    job control enabled. It may be called from  a  macro  to
    suspend  crisp and allow the user to user an alternative
    key to Ctrl-Z if that is being used for something else. 
    
    This macro will only work on systems which  support  job
    control. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                        swap_anchor() 
    
    
DESCRIPTION      
    
    This  macro  swaps  the current cursor position with the
    start of the currently marked region, i.e. if the cursor
    is at the end of the marked region, the cursor is  moved
    to  the  start  of  the marked block, keeping the marked
    block intact. 
    
RETURN VALUE     
    
    Nothing. 
    
    
      switch (expr) { case-1: list-1 case-2: list-2 ..} 
    
    
DESCRIPTION      
    
    This macro implements the CRISP switch  statement.  expr
    is  an  integer  or string expression which is evaluated
    and then compared with  each  of  case-1,  case-2,  etc.
    case-1,  etc  should  be expressions of the same type as
    expr. If a match is found, then the statements in list-n
    are executed. 
    
    If CRISP encounters a case-n value of NULL, then this is
    taken to be the default and the list is  unconditionally
    executed. 
    
    If statement list associated with an expression is NULL,
    then  the next non-NULL statement list associated with a
    case expression is executed. This allows multiple values
    to be associated with the same set of  statements.  (See
    example below). 
    
EXAMPLES      
    
    The  following example illustrates an example of integer
    switches. If the value of i, is 1, 2, or 3 then word  is
    assigned   the   strings   "one",   "two"   or   "three"
    respectively. If i is not one  of  these  three  values,
    then word is assigned the ascii representation of i. 
    
    	string	word, buf; 
    	int	i; 
    	 
    	switch (i) { 
    	  case 1:	word = "one"; 
    	  		break; 
    	  case 2:	word = "two"; 
    	  		break; 
    	  case 3:	word = "three"; 
    	  		break; 
    	  default: 
    	  		sprintf(buf, "%d", i); 
    			break; 
    	  } 
    
    
    The following shows the reverse: 
    
    	string	word; 
    	int	i; 
    
    	switch (word) { 
    	  case "one":	i = 1; 
    	  		break; 
    	  case "two":	i = 2; 
    	  		break; 
    	  case "three":	i = 3; 
    	  		break; 
    	  default: 
    	  		i = atoi(word); 
    			break; 
    	  } 
    
    
    The  following  shows  an example of using multiple case
    values: 
    
    	string word; 
    	 
    	switch (word) { 
    	  case "y": 
    	  case "Y": 
    		word = "YES"; 
    		break; 
    	  case "n": 
    	  case "N": 
    		word = "NO"; 
    		break; 
    	  } 
    
    
               tabs([tab1], [tab2], .., [tabn]) 
    
    
DESCRIPTION      
    
    This macro is used to set the tab stops for the  current
    buffer.  tab1,  tab2, set the first tab stops. Tab stops
    are set every (tabn - tabn-1) stops after the  last  tab
    stop. The first column in the line is column 1. 
    
    Upto 5 unique tab stops can be specified, thereafter all
    tab  stops default to the difference of the last two tab
    stops. 
    
    In soft tab mode (see (use_tab_char)), whenever a tab is
    inserted into  the  text,  enough  spaces  are  inserted
    automatically  to  take the cursor to the next tab stop.
    When in hard  tab  mode,  physical  tab  characters  are
    inserted. 
    
    When in hard tab mode, the tab stops only affect the way
    the  text  buffer  is displayed; if tab stops other than
    the default 8 are used, then the user may have  problems
    printing  files  or using other utilities to examine the
    file due to column misalignment. 
    
    
EXAMPLES      
    
    The following sets tab stops to every 4 columns: 
    
    	tabs(1, 5); 
    
    
    The following sets tab stops to every 8 columns: 
    
    	tabs(1, 9); 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                            tan(x) 
    
    
RETURN VALUE     
    
    Returns the tangent of x  (in  radians)  as  a  floating
    point number. 
                           tanh(x) 
    
    
RETURN VALUE     
    
    Returns  the hyperbolic tangent of x as a floating point
    number. 
                 time([hours], [mins], [sec]) 
    
    
DESCRIPTION      
    
    hours, mins and  secs  are  optional  integer  variables
    which receive the current time. 
    
    hours  is  a  number in the range 0-23; mins is a number
    0-59; secs is a number 0-59. 
    
    
EXAMPLES      
    
    The current time can be printed as such: 
    
    
    	int	hours, mins, secs; 
    	 
    	time(hours, mins, secs); 
    	message("Time now: %02d:%02d:%02d", hours, mins, secs);
    
    
    
RETURN VALUE     
    
    Returns time in seconds measured  from  the  base  date:
    00:00:00 GMT Jan 1 1970 for Unix based systems. 
    
    
                       top_of_buffer() 
    
    
DESCRIPTION      
    
    Moves  the  cursor to the start of line 1 in the current
    buffer. 
    
RETURN VALUE     
    
    Returns non-zero if the cursor  changed  position;  zero
    otherwise. 
    
    
                       top_of_window() 
    
    
DESCRIPTION      
    
    Moves  the  cursor to the start of the line displayed at
    the top of the window. 
    
RETURN VALUE     
    
    Returns non-zero if the cursor  changed  position;  zero
    otherwise. 
    
    
    transfer(buf_id,   start_line,    start_col,   end_line,
                           end_col) 
    
    
DESCRIPTION      
    
    This function is used to copy a block of text  from  one
    buffer  to  another.  buf_id is the buffer identifier of
    the source buffer. start_line, start_col, end_line,  and
    end_col specify the bounds of the text to be copied. 
    
    The  copied  text is copied to the current buffer at the
    current cursor position. 
    
    It is provided  for  compatability  with  BRIEF.  It  is
    usually far easier to use the region macros. 
    
RETURN VALUE     
    
    Returns  zero  or  less   if   unsuccessful;   zero   if
    successful. 
    
    
    translate([pattern],  [replacement],   [global],   [re],
                           [case], 
    [block], [forward]) 
    
    
DESCRIPTION      
    
    This macro is used to perform string translations within
    the  current buffer. pattern is the string to translate.
    If re is not specified or is non-zero, then  pattern  is
    treated as a regular expression, otherwise it is treated
    as  a  normal  string.  If  case  is not specified or is
    non-zero,  then   the   search   is    performed    case
    insensitively.  If  block  is specified and is non-zero,
    then the search is  limited  to  the  currently  hilited
    region. 
    
    replacement is a string containing the string to replace
    pattern with. 
    
    If  global  is  specified  and  is  non-zero, then every
    occurence in the current buffer from the cursor  to  the
    end of the buffer is translated. If global is zero, then
    only the first occurence is translated. If global is not
    specified, then the user is prompted for each change. 
    
    If  pattern  or  replacement  is not specified, then the
    user is prompted for the change. 
    
    If is non-zero or omitted, then the translation is  done
    in  the  forwards  direction, otherwise it will occur in
    the backwards direction. 
    
RETURN VALUE     
    
    Returns the number of translations. 
         translate_pos(x, y, [win_id], [line], [col]) 
    
    
DESCRIPTION      
    This macro is designed to map an (x,y) co-ordinate  pair
    into  an  actual line/column position within a window. x
    and  y   are  the  co-ordinates  as  returned  from  the
    get_mouse_position() primitive  representing  the  place
    where the mouse was hit.  
    
    win_id  is  filled  with the ID of the window upon which
    the (x,y) position falls. If line and col are  specified
    then  these receive the line and column positions within
    the buffer specified. 
    
    This function returns a code  indicating  what  type  of
    object the mouse was hit on. 
    
RETURN VALUE     
    The following returns are possible: 
    
    
    
    |============|========================================|
    |Value       |Meaning                                 |
    |============|========================================|
    |0           |Mouse  not  pressed  inside or on any   |
    |            |window (i.e. the status line).          |
    |____________|________________________________________|
    |1           |Mouse  pressed   on  left  border  of   |
    |            |window.                                 |
    |____________|________________________________________|
    |2           |Mouse  pressed  on  right  border  of   |
    |            |window.                                 |
    |____________|________________________________________|
    |3           |Mouse  pressed   on   top  border  of   |
    |            |window.                                 |
    |____________|________________________________________|
    |4           |Mouse pressed  on  bottom  border  of   |
    |            |window.                                 |
    |____________|________________________________________|
    |5           |Mouse pressed inside window.            |
    |____________|________________________________________|
    |6           |Mouse pressed on window title.          |
    |============|========================================|
    
SEE ALSO     
    get_mouse_position(), process_mouse() 
                    trim(string, [delim]) 
    
    
DESCRIPTION      
    
    This function is used to remove trailing characters from
    the specified string. The default is to remove all tabs,
    spaces  and  newline  characters. If delim is specified,
    then all characters in the delim string are removed from
    the end of string. 
    
RETURN VALUE     
    
    Returns a copy of string with all trailing  white  space
    characters removed. (spaces, tabs and newlines). 
    
    
                         typeof(expr) 
    
    
DESCRIPTION      
    
    This  macro  is  an  alternative  way  to  determine the
    current type of a polymorphic variable. 
    
    
RETURN VALUE     
    
    Returns one of the string constants, "NULL",  "integer",
    "float",  "string",  or  "list" depending on the type of
    expr. 
                        umask([mask]) 
    
DESCRIPTION      
    The umask() function is used to set and/or get the  file
    creation  mask.  The  file  creation  mask  is used when
    creating  files.   When   a   file   is   created   (via
    write_buffer() or write_block()) the umask  is  used  to
    mask  off  certain  protection  bits.  The mask bits are
    operating system dependent but are by and large the same
    from one system to another.  For  example,  setting  the
    umask  to  022  (octal) causes newly created files to be
    read and writable by the  owner  but  only  readable  by
    others and anyone in the same group. 
    
RETURN VALUE     
    Returns the previous value of the mask. 
    
SEE ALSO     
    write_buffer(), write_block() 
              undo([move], [write_mark], [redo]) 
    
    
DESCRIPTION      
    
    This  is  the  macro  used to undo buffer modifications.
    When  called  with  no  arguments  it  undoes  the  last
    operation performed on the buffer, e.g. move the cursor,
    insert deleted text, unmark area, etc. If  the  previous
    operation  on  the  buffer  was  a  macro,  or a complex
    operation, e.g. global translate, then  all  the  buffer
    modifications performed are undone in one step. 
    
    If  move  is  specified  and  is non-zero, then the undo
    command undoes all buffer operations back upto the  last
    buffer  modification.  If  the last command was a buffer
    modification,  then   setting   move   to   non-zero  is
    equivalent  to  not  specifying  it.  If  the  last  few
    operations were simply cursor movements, then move  goes
    back  to  the  last point in the buffer where the buffer
    was actually modified. 
    
    There is a separate undo stack for each buffer. Normally
    when  a  buffer  is  written  away  the  undo  stack  is
    discarded so  that  it  is  not  possible  to  undo  any
    operations  performed  on  the  buffer  before  the last
    (write_buffer) operation. If write_mark is specified and
    is non-zero, then this allows the undo to go  back  past
    the last (write_buffer) mark. 
    
    Unlike  BRIEF, it is possible to call (undo) from within
    a macro, but its use their  is  highly  dubious.  It  is
    normally called by the user directly from one of the key
    assignments. 
    
    The  redo  parameter  indicates whether a redo operation
    should be performed. If it is specified then a  redo  is
    performed,  otherwise  an  undo  is  performed.  A  redo
    operation allows an undo to be undone. 
    
RETURN VALUE     
    
    Nothing. 
    
    
             unregister_macro(n, macro, [local]) 
    
    
DESCRIPTION      
    
    This macro is used to remove  a  macro  which  has  been
    registered   for    a    particular    trigger.     (See
    (register_macro) for a description of the triggers). 
    
    If a particular macro has been registered more than once
    then  (unregister_macro)  should  be  called  for   each
    register   of    the    macro.    (The    return    from
    (unregister_macro) can be used in a loop). 
    
    If  local   is   set  to  1,  then  the  macro  will  be
    unregistered only if it was registered as a local macro.
    If it is omitted or not equal to 1 then both  the  local
    and global registered macro will be unregistered. 
    
    
EXAMPLES      
    
    The following unregisters all occurences of a macro: 
    
    
    	while (unregister_macro(trigger, "macro_name") > 0) 
    		; 
    
    
RETURN VALUE     
    
    Zero  if  macro  was  not  registered;  1  if  macro was
    registered and has now been unregistered. 
    
    
                           up([n]) 
    
    
DESCRIPTION      
    
    This macro moves the cursor to the previous line in  the
    buffer,  maintaining  the  same column position. If n is
    specified then the cursor is moved to the n'th  previous
    or n'th following (if n < 0) line. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                        upper(string) 
    
    
RETURN VALUE     
    
    Returns  a  copy  of  string with all lower case letters
    mapped to their upper case equivalents. 
                  use_local_keyboard(kbd_id) 
    
    
DESCRIPTION      
    
    This macro is used to associate a keyboard map with  the
    current  buffer. The local keyboard map takes precedence
    over the global keyboard map. Whenever  this  buffer  is
    selected,  the  local  keyboard  map is searched for key
    bindings first; if there is no key binding for  the  key
    typed  by  the  user,  then  the  global keyboard map is
    searched as usual. 
    
    kbd_id is the identifier of the keyboard as returned via
    inq_keyboard().  Specifying   zero   removes  the  local
    keyboard and if necessary frees  the  memory  associated
    with  it  if  there  are  no  other  references  to  the
    keyboard. 
    
    Local keyboards are usually used to effect  things  like
    language  sensitive  editing  modes, e.g. in C mode, the
    braces { and } may be associated with a macro to perform
    C style indenting; obviously it is not a good  thing  to
    perform C style indenting on an nroff text buffer. Using
    local  keyboards  avoids  macros  being  complicated  by
    having to check the buffer type each time, and also make
    CRISP run faster. 
    
RETURN VALUE     
    
    Returns 0 if operation successful; -1 if kbd_id is not a
    valid keyboard id. 
    
    
                      use_tab_char(yes) 
    
    
DESCRIPTION      
    
    This macro allows the user to specify  whether  hard  or
    soft  tabs  should  be  used. yes is a string expression
    which should be set to "y" if tabs are to be  physically
    inserted  into  the  buffer;  otherwise  spaces are used
    instead to fill up to the next tab stop. 
    
    If 'yes' is an integer expression then only the value of
    the tab toggle is returned. 
    
    
RETURN VALUE     
    
    Returns the previous value of the use tab char toggle. 
    
    
                version([maj], [min], [edit]) 
    
    
DESCRIPTION      
    
    This macro is used to get the current version level. The
    arguments are  the  names  of  integer  variables  which
    receive  the  major, minor and edit level. If maj is not
    specified then the version message is displayed  on  the
    command line. 
    
    Displays the current version on the status line. 
    
    
RETURN VALUE     
    
    Returns  the current version number * 100 plus the minor
    level. 
    
    
                        wait([status]) 
    
    
DESCRIPTION      
    
    This macro waits for the process attached to the current
    buffer to die. When the process dies, if status has been
    specified (the name of an integer  variable),  then  the
    exit status of the process is placed in it. 
    
    This macro may be aborted by pressing a space. 
    
RETURN VALUE     
    
    Returns  -1  if  there  is  no  process  attached to the
    current buffer. -2 if user aborted the wait.  Returns  0
    if process has died. 
    
    
                  wait_for([timeout], expr) 
    
    
DESCRIPTION      
    
    This  macro is used to wait for a sequence of characters
    to be output by the sub-process attached to the  current
    buffer.  timeout specifies how long to wait (in seconds)
    and if omitted or zero, the wait occurs indefinitely. 
    
    expr is  either  a  string  expression,  representing  a
    regular  expression  of  what  is to be waited for, or a
    list of regular expressions. If it is  a  list,  then  a
    parallel  match  is  performed as each character is read
    from the buffer. If any of the atoms in  the  list  (all
    string  constants)  match the characters from the stream
    then (wait_for) terminates. 
    
    This macro is used by the various process control macros
    to wait for magic strings, e.g. shell prompts. 
    
    
EXAMPLES      
    
    See dial.cr and shell.cr for  examples  of  how  to  use
    wait_for(). 
    
RETURN VALUE     
    
    Returns  -1 if there is no process currently attached to
    the current buffer, or user interrupted wait. Returns  1
    if  expr  is  a  string  expression  and  the expression
    matched; returns n if expr is a list and atom n matched.
    
    
                         (watch ...) 
    
    
DESCRIPTION      
    
    This macro currently is a no-op. It is intended to allow
    macros to be written which  allow  other  macros  to  be
    debugged.  The  idea  is  that  a  macro can monitor any
    variable to see if it gets changed. The  code  does  not
    exist,  and  the  ideas have not been thoroughly thought
    out yet. 
    
    This may be supported in a later  version  of  CRISP  if
    there is sufficient demand. 
                      while (expr) stmt 
    
    
DESCRIPTION      
    
    This  macro  is  used  to  implement  a  while-loop. The
    expression  expr  is  evaluated  and  if  non-zero,  the
    statements are  executed.  Afterwards,  expr  is  tested
    again.  This  continues until either a (break) statement
    is encountered in list, or the expression  evaluates  to
    false. 
               window_color([color], [win_id]) 
    
    
DESCRIPTION      
    
    This  macro  is  used to set the color of the background
    associated with a window, and is used only when  borders
    are turned off. 
    
    color  is  the color to set. If it is not specified then
    the old color is returned only. If win_id  is  specified
    then the change is applied to the specified window. 
    
    This macro is currently not implemented. 
    
RETURN VALUE     
    
    Returns previous background color of window. 
    
SEE ALSO     
    inq_window_color() 
    write_block([filename],    [append],      [keep-region],
                           [pause]) 
    
    
DESCRIPTION      
    
    This macro is used to write  out  the  currently  marked
    region  to a file. If filename is not specified, then it
    is prompted for. 
    
    Writing out a marked region does not affect  the  backup
    flag  or  the  undo  information  flag.   (See   (undo),
    (set_backup)). 
    
    If  keep-region  is  not  specified or is zero, then the
    current anchor is raised. Otherwise it  is  left  alone,
    e.g. so that you can delete the region afterwards. 
    
    If  append is specified and is non-zero, then the marked
    area is appended to the file. 
    
    If the filename starts with a  '|'  character  then  the
    data  is  written  to  a pipe (via popen()) instead of a
    file. The data after the '|' is passed as an argument to
    the popen() call. When writing the block to  a  command,
    the  command may destroy the screen by writing to stdout
    or stderr. If this is the case, then the pause parameter
    can be used to force the  screen  to  be  redrawn  after
    execution. If not-specified or is non-zero then the user
    is prompted to hit <Enter> before continuing. 
    
    If  the  filename  starts  with  either  the '>' or '>>'
    characters then the region is appended to the  specified
    file. (The leading '>' or '>>' are removed). 
    
    This primitive knows how to correctly write out a column
    marked region. 
    
RETURN VALUE     
    
    Zero or less if the macro was unsuccessful. Greater than
    zero if the write was successful. 
    
    
              write_buffer([filename], [append]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to  write out the contents of the
    current buffer to a file. If filename  is  omitted  then
    the  file is written to the filename associated with the
    current buffer (i.e. as  specified  via  create_buffer).
    Otherwise filename is used. 
    
    If  this  is  the  first time that write_buffer has been
    called for this buffer, then a backup copy of  the  file
    will  be  made. (See the section on making backups for a
    discussion of the algorithm used). Subsequent  calls  to
    write_buffer do not create backups. 
    
    If  append is specified and is non-zero, then the output
    file is appended to. 
    
    
RETURN VALUE     
    
    Returns zero if file saved  (or  no  modifications  were
    made); returns -1 if an error occurred during saving. 
    
    
    
    
