                          process() 
    
    
DESCRIPTION      
    
    The  process()  macro is the mechanism for causing CRISP
    to nest keyboard invocations. CRISP maintains a  process
    level  counter  which  is normally set to 1. When in the
    process mode, CRISP accepts keystrokes and executes  the
    macros bound to those keystrokes. 
    
    A  call  to  process()  is  usually  made after creating
    buffers and windows for display on  screen,  and  having
    set  up  a temporary keyboard map. Return from a call to
    process() only occurs as a result of a macro calling the
    exit() macro. 
    
    The current process level is terminated via  a  call  to
    exit(). When the process level goes to zero, CRISP exits
    (possibly after prompting the user to save buffers). 
    
    Process  nesting  may  occur  to  any  depth, within the
    bounds of CRISPs maximum nesting level. 
    
    The term 'process' is a misnomer  and  in  this  context
    should not be confused with process buffers, which are a
    completely different concept. 
    
RETURN VALUE     
    
    Nothing. 
    
    
            process_mouse(but1, but2, but3, x, y) 
    
    
DESCRIPTION      
    
    This  macro  exists to allow user macros to interface to
    CRISP so that internal mouse processing can be performed
    in a generic manner for different types  of  mice.  Some
    mice  require  internal  support  whereas  others can be
    totally  handled   by  user  level  macros,  but  at  an
    execution time cost. 
    
    This macro gets called with the  current  state  of  the
    mouse buttons, zero means the button is up, and non-zero
    means the button is down. 
    
    The  x  and y parameters specify the co-ordinates of the
    mouse on the screen, with (0,0) being the  top  left  of
    the screen. 
    
    When  the macro is called, the states of the buttons are
    compared with the last recorded state and the  REG_MOUSE
    registered  macro  is called with information about what
    type of object the mouse was clicked on. 
    
    Refer to the mouse.cr macro for details. 
    
RETURN VALUE     
    
    Nothing. 
    
SEE ALSO     
    translate_pos 
                       profile([expr]) 
    
    
DESCRIPTION      
    
    profile() exists  solely  to  help  profile  CRISPs  own
    execution  so  that  it  may  be optimised. By default a
    mon.out file is created whenever a program  exits  which
    was  compiled  with the cc -p flag. When CRISP exits, it
    usually avoids calling exit() so that the  mon.out  file
    does  not  get written. This allows CRISP to be compiled
    with the -p flag and  installed  without  causing  every
    user  to inadvertently create mon.out files all over the
    file system. 
    
    In order to get a  mon.out  file  on  exit  from  CRISP,
    either run CRISP with the -p flag, or call this macro. 
    
    If  expr  is  omitted, the profile option is toggled. If
    expr is non-zero then a mon.out file will be created; if
    it is zero, then mon.out will not be created. 
    
    Note that this option only works if CRISP  was  compiled
    with the profiling code included. 
    
RETURN VALUE     
    
    Nothing. 
                    _prompt_begin(string) 
    
DESCRIPTION      
    This  macro is a callback macro called whenever the user
    is about to  be  prompted  on  the  command  line.  This
    function  is  called  with  the  string  which forms the
    prompt, and exists to allow the command line history and
    abbreviations mechanisms to be implemented. 
    
SEE ALSO     
    _prompt_end() 
                        _prompt_end() 
    
DESCRIPTION      
    This macro is a callback macro called after the user has
    finished entering text on the command line. It exists to
    allow the history facility of the  command  line  to  be
    implemented.  The called macro normally saves the string
    the user typed in so it can be recalled. 
    
SEE ALSO     
    _prompt_begin() 
                        push_back(key) 
    
    
DESCRIPTION      
    
    This macro is used to push a  character  back  into  the
    typeahead  buffer. The character pushed back sits at the
    front of the input buffer and is read  before  any  user
    typeahead. 
    
    key  is  an  integer  internal key code, usually derived
    from a read_char() or key_to_int() macro call. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                 put_nth(expr list_var value) 
    
    
DESCRIPTION      
    
    put_nth() is used to modify or insert a new atom into  a
    list.  list_var  is the list; expr is the atom number to
    be inserted (0 is the first atom). value is an  integer,
    string or list expression which is to be inserted. 
    
    If  the  atom  to  be inserted already exists, then that
    atom is deleted, and replaced by the new value. 
    
    If the expr'th  atom  does  not  exist,  then  value  is
    inserted onto the end of the list. It is not possible to
    create  sparse  lists, only new entries may be tacked on
    to the end of a list. 
    
    
EXAMPLES      
    
    The  following   example  creates  a  list  of  the  ten
    integers, 1..10: 
    
    	int	i; 
    	list	l; 
    	 
    	for (i = 1; i <= 10; i++) 
    		l += i; 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                     put_parm(num, value) 
    
    
DESCRIPTION      
    
    This macro is used to modify a  calling  parameter.  num
    specifies the argument number, and value is the value to
    place  in  that  argument.  value  may be a string or an
    integer expression. (Lists are not currently supported).
    
    This macro allows the calling  macro  to  pass  multiple
    values  to  its  calling macro. The calling macro should
    call this macro with the name of an  integer  or  string
    macro in the num'th position. 
    
    
RETURN VALUE     
    
    Returns  0  if successful; greater than zero if argument
    num does not exist. 
    
    
                    quote_list(list_expr) 
    
    
DESCRIPTION      
    
    The quote_list() macro is  the  mechanism  for  creating
    list  literal  constants.  It  is  normally   used   for
    assigning  initial  values  to  lists, or for passing an
    anonymous macro to another macro. 
    
    For example, the following sets the list, l, to the  two
    element list ("one" "two"): 
    
    	list	l; 
    	l = quote_list("one", "two"); 
    
    
    If quote_list() wasn't used, and the expression appeared
    as: 
    
    	l = "one", "two"; 
    
    
    CRISP would assign the value "two" to the list, since in
    this context the comma is a binary operator. 
    
    Any  CRISP  expression  can appear after the quote_list,
    including a sequence of commands. 
    
    
RETURN VALUE     
    
    The quoted list, list_expr. 
    
SEE ALSO     
    make_list() 
                     quote_regexp(string) 
    
    
DESCRIPTION      
    
    This macro is used to quote a string so that it  can  be
    used in searches. 
    
    For  example,  suppose the macro writer wishes to search
    for the pattern "<>" at the  start  of  a  line  in  the
    buffer. The correct way to do this is to write something
    like: 
    
    search_fwd("<\<\>") 
    
    It  is possible for the macro writer to parse the string
    and insert the appropriate backslashes, but  this  would
    be  a  very  expensive  operation. It is not adequate to
    turn off regular expression  parsing  with  search_fwd()
    since then the macro couldnt be sure to match the string
    at the start of the line. 
    
    In  this  case,  quote_regexp() does the tedious work of
    translating the string so that it will match exactly. 
    
    
RETURN VALUE     
    
    Returns a string with all regular expression  characters
    quoted. 
    
    
                        raise_anchor() 
    
    
DESCRIPTION      
    
    raise_anchor()  is  used  to  raise  the  current marked
    region, i.e. remove it. The currently  highlited  region
    is unhighlited. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                         rand([num]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to  evaluate  random numbers. The
    number returned is an integer in the  range  0..2^31  or
    0..num.  The  numbers  may  or may not be random enough,
    depending on the underlying implementation  of  rand(3).
    CRISP tries to use the randomness of rand() to add a bit
    of  variety  to  the  low  order  bits  of tyhe returned
    number. However this may not be effective. 
    
RETURN VALUE     
    
    Random number in range 0..2^31 or 0..num 
    
    
    re_search([flags],   [pattern],    [object],    [start],
                          [lensym]) 
    
    
DESCRIPTION      
    
    This primitive is designed to  replace  the  search_fwd,
    search_back,  search_string  and search_list primitives.
    It provides the same functionality, but is  compact  and
    somewhat easier to read and remember. The motivation for
    this  primitive  is to allow the syntax mode of a search
    to be set temporarily for a search rather than  for  the
    entire  session.  This allows macros to be written which
    do not have to worry about the environment the user  may
    have established. 
    
    The  actual  type  of  search depends on the type of the
    expression returned by object. If object  is  a  string,
    then  a  string search is performed. If object is a list
    then a list search is done; otherwise a  search  on  the
    current buffer is performed. 
    
    pattern  is the regular expression to look for. start is
    used for list searches and indicates the starting  point
    in the list to start the search from. lensym is used for
    string  searches  to  contain  the length of the matched
    string found. 
    
    flags is a set of bits defined in crisp.h which  control
    the options of the search. The flags are as follows: 
    
    |======================|==============================|
    |Flag                  |Description                   |
    |======================|==============================|
    |0x01 SF_BACKWARDS     |Perform  a backwards search   |
    |                      |on the current  buffer.  If   |
    |                      |not  specified  a   forward   |
    |                      |search  is  performed. Only   |
    |                      |meaningful   for     buffer   |
    |                      |searches or translates.       |
    |______________________|______________________________|
    |0x02 SF_IGNORE_CASE   |Ignore case when  comparing   |
    |                      |strings.                      |
    |______________________|______________________________|
    |0x04 SF_BLOCK         |Limit searches to hilighted   |
    |                      |block.   (Buffer   searches   |
    |                      |only).                        |
    |______________________|______________________________|
    |0x08 SF_UNIX          |Select Unix syntax mode. If   |
    |                      |not specified,  CRISP/BRIEF   |
    |                      |mode is used.                 |
    |______________________|______________________________|
    |0x10 SF_LENGTH        |If     specified       then   |
    |                      |successful   match     will   |
    |                      |return  length  of  matched   |
    |                      |string  +   1.   If    not,   |
    |                      |returned  length  will take   |
    |                      |into account any  c  escape   |
    |                      |sequences  in  the pattern.   |
    |                      |Buffer search only.           |
    |______________________|______________________________|
    |0x20 SF_NOT_REGEXP    |Dont  treat  pattern  as  a   |
    |                      |regular expression.           |
    |______________________|______________________________|
    |0x40 SF_GLOBAL        |(re_translate only) Perform   |
    |                      |a global translate.           |
    |______________________|______________________________|
    |0x80 SF_PROMPT        |(re_translate only)  Prompt   |
    |                      |user  for each translation.   |
    |______________________|______________________________|
    |0x100 SF_MAXIMAL      |When  using   CRISP   style   |
    |                      |syntax  match  the  longest   |
    |                      |string possible.              |
    |======================|==============================|
    
SEE ALSO     
    re_translate,  search_fwd,  search_back,  search_string,
    search_list, re_syntax 
    
RETURN VALUE     
    
    
    |====================|====================|
    |buffer search:      |0 if pattern  not   |
    |                    |found.              |
    |                    |-1 on an error      |
    |                    |length of matched   |
    |                    |text + 1            |
    |list search:        |-1 if pattern not   |
    |                    |found               |
    |                    |index  of atom if   |
    |                    |found               |
    |string search:      |0 if pattern  not   |
    |                    |found               |
    |                    |index  of   first   |
    |                    |character      of   |
    |                    |match               |
    |====================|====================|
    
                      re_syntax([mode]) 
    
    
DESCRIPTION      
    
    This  macro  allows  the  user  to  select  the  regular
    expression syntax mode. By default, the mode is set  for
    BRIEF/CRISP regular expression syntax. If mode is set to
    1,  then  Unix  like syntax is selected. The differences
    are as follows: 
    
    In Unix mode, the '*'  and  '.'  characters  have  their
    normal  meanings. The BRIEF/CRISP characters '@' and '?'
    act as non regular expression characters. Also the { and
    } characters  are  replaced  by  their  backslash-(  and
    backslash-) equivalents. 
    
RETURN VALUE     
    
    Returns  the  current regular expression syntax mode - 0
    for BRIEF/CRISP syntax, 1 for Unix-like syntax. 
    
    
    re_translate([flags],    [pattern],       [replacement],
                          [string]) 
    
    
DESCRIPTION      
    
    This function is a  new  interface  to  the  translate()
    primitive  which  allows  the  regular expression syntax
    mode to be specified temporarily  for  the  translation.
    This  function  allows  translations  to  be made in the
    current buffer or to a  string.  (Translating  a  string
    provides similar functionality to awk's sub() and gsub()
    functions). 
    
    flags  are a set of flags which control the translation.
    See description of re_search() for further details. 
    
    pattern is the string to search for. 
    
    replacement is the string to replace the pattern with. 
    
    If string is specified then the substitutions  are  made
    to  the  string,  and the resulting translated string is
    returned. 
    
    If either pattern or replacement are not specified  then
    they will be prompted for. 
    
RETURN VALUE     
    
    For buffer translations, the number of translations made
    is  returned.  For  string  translations, the translated
    string is returned. 
    
    
                         read([num]) 
    
    
DESCRIPTION      
    
    If num is not specified,  then  all  characters  to  the
    right  of  the  cursor  are  returned, together with the
    newline character which terminates all lines. 
    
    If num is specified, then that number of characters  are
    read  from  the  buffer.  If  num  is  longer  than  the
    remaining characters on the current line, then only  the
    rest of the current line is returned. 
    
RETURN VALUE     
    
    Returns a string containing the next num characters from
    the  input  buffer,  or  the  rest of the line after the
    cursor if num is not specified. 
    
    
                 read_char([millisec], [raw]) 
    
    
DESCRIPTION      
    
    This macro  can  be  used  to  see  if  a  character  is
    available  from  the typeahead buffer. If a character is
    available, it is returned (in internal key  code  form),
    and the character removed from the typeahead buffer. 
    
    If millisec is specified then the read_char() macro will
    wait  the  specified  number  of  milliseconds   for   a
    key-press  before returning. If millisec is set to zero,
    then read_char() will wait until a key is pressed  (same
    as not specifying millsec for CRISP). If millisec is set
    to  -1,  then  the  keyboard  will be polled (similar to
    BRIEF). 
    
    If a non-destructive peek into the typeahead  buffer  is
    required, use inq_kbd_char(). 
    
    If  the  second  parameter  raw  is  specified  and   is
    non-zero,  then  a  raw  character will be read from the
    keyboard. This means that hitting a  function  key  will
    usually  return  the first ESCAPE character forming that
    key code, rather than being translated into the internal
    keycode. This facility is used by the quote() macro. 
    
    Internal key codes  should  not  be  manipulated  as  is
    (unless  the  keys  are  being inserted into the current
    buffer), but rather should be converted to the canonical
    key-code format, via int_to_key. 
    
RETURN VALUE     
    
    Internal key  code  of  character  typed  or  -1  if  no
    character available. 
    
    
                    read_file([filename]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to  read  a file into the current
    buffer at the current cursor position.  If  filename  is
    omitted, then the user is prompted for the file-name. 
    
RETURN VALUE     
    
    Zero  if  unsuccessful; non-zero otherwise. On an error,
    the global variable errno will be set to the reason  for
    the failure. 
                           redraw() 
    
    
DESCRIPTION      
    
    This  macro is used to physically redraw every character
    on the screen, after first clearing the  screen.  It  is
    sometimes  required  on  serial  lines,  etc,  where the
    screen has garbage on it, and CRISP has lost control. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                          refresh() 
    
    
DESCRIPTION      
    
    This macro is used to update  the  screen  after  making
    various  changes to buffers and/or windows. It optimises
    the amount of output to the screen. 
    
RETURN VALUE     
    
    Nothing. 
    
    
              register_macro(num macro [local]) 
    
    
DESCRIPTION      
    
    Registered macros are hooks into the execution of CRISP.
    CRISP defines triggers which allow the user's macro's to
    be activated when certain conditions arise in CRISP. 
    
    The conditions are described  by  the  'num'  parameter,
    which  is  an  integer  expression.  The  conditions are
    listed below. 
    
    macro is the name of a macro to call when the trigger is
    pulled. If local is specified and is non-zero, then  the
    macro  is only registered for this buffer, otherwise the
    event may be triggered even when the current  buffer  is
    not selected. 
    
    Multiple  macros  may  be  associated  with a particular
    registered macro. When the registered macro  is  called,
    the macros are called in FIFO order. 
    
    Registered  macros  may  be   removed   by   using   the
    unregister_macro()  macro  call; a particular registered
    macro can be triggered via call_registered_macro(). 
    
    |==========|========================================|
    |Trigger   |Description                             |
    |==========|========================================|
    |0         |A character has  been  inserted  into   |
    |          |the current buffer via self_insert().   |
    |__________|________________________________________|
    |1         |This is called every time the current   |
    |          |buffer is changed via edit_file().      |
    |__________|________________________________________|
    |2         |This  is  triggered  every  time  the   |
    |          |<Alt-H> key is pressed, and  is  used   |
    |          |for  the   context   sensitive   help   |
    |          |feature.                                |
    |__________|________________________________________|
    |3         |This   is   triggered   whenever   an   |
    |          |unassigned key is pressed.              |
    |__________|________________________________________|
    |4         |This is triggered when  the  keyboard   |
    |          |idle  timer  expires.  It  allows the   |
    |          |autosave feature to be implemented.     |
    |__________|________________________________________|
    |5         |This  is  called  just  before  CRISP   |
    |          |exits. It allows macros  to  tidy  up   |
    |          |after   themselves,    e.g.    delete   |
    |          |temporary files, save editing state.    |
    |__________|________________________________________|
    |6         |This is called every time a new  file   |
    |          |is  read  in   to   a   buffer   (via   |
    |          |edit_file).                             |
    |__________|________________________________________|
    |7         |This  is  called  whenever  the  user   |
    |          |types  the  interrupt  character  (by   |
    |          |default ^Y). This  allows  macros  to   |
    |          |set  a  flag  which can cause them to   |
    |          |abort.                                  |
    |__________|________________________________________|
    |8         |This  is  called  whenever  the  user   |
    |          |types in an invalid key during  input   |
    |          |on  the  status/prompt   line.   This   |
    |          |allows  the  abbreviation  and   help   |
    |          |facilities to be implemented.           |
    |__________|________________________________________|
    |9         |An  internal error occured. This used   |
    |          |to  trap   segmentation    violations   |
    |          |inside  CRISP  and  allows  users  to   |
    |          |write their own 'emergency' macro  to   |
    |          |save   buffers.   (One   is   already   |
    |          |provided  --  refer  to  the  core.cr   |
    |          |macro).                                 |
    |__________|________________________________________|
    |10        |Called when mouse activity  detected.   |
    |          |This  is  not  fully   supported   at   |
    |          |present.                                |
    |__________|________________________________________|
    |11        |Called  when  process input available   |
    |          |from a process buffer.                  |
    |__________|________________________________________|
    |12        |Called when  keyboard  buffer  empty.   |
    |          |This  macro  MUST  return  an integer   |
    |          |value. If the  value  is  zero,  then   |
    |          |keyboard  input can be read. If it is   |
    |          |non-zero, then  the  keyboard  should   |
    |          |not  be  read,  but the internal code   |
    |          |will check the push-back  buffer  for   |
    |          |input.                                  |
    |==========|========================================|
    
RETURN VALUE     
    
    Nothing. 
    
    
                remember([overwrite], [macro]) 
    
    
DESCRIPTION      
    
    remember  is used to record a keyboard macro (a sequence
    of  keystrokes)  that  can  later  be  played  back  via
    playback(). 
    
    The argument overwrite is an optional string whose first
    character  is   examined  to  see  whether  an  existing
    keyboard macro should  be  overwritten.  If  a  keyboard
    macro  already  exists,  and overwrite is not specified,
    then the user is prompted to  overwrite  the  macro.  If
    overwrite  is  specified  and  the  first  character  of
    overwrite is a 'y' or 'Y' then the keyboard  macro  will
    be overwritten. 
    
    macro  specifies  which  keyboard  macro  to  store  the
    keystrokes in. If macro is  unspecified  then  the  next
    free keyboard 
    
    If remember is called whilst recording a keyboard macro,
    then the recording is terminated. 
    
    remember is not usually called as part of a macro but is
    usually bound to a keyboard key (<F7>). 
    
    remember  will  also create a buffer called KBD-MACRO-xx
    where xx is  the  keyboard  macro  number.  This  buffer
    contains  the  top  level  macros  executed  by the user
    typing in the keys. This facility  allows  the  user  to
    save  and  edit  a keyboard macro. Note that not all the
    macros executed by the user are saved in  the  buffer  -
    only  the  top  level  ones.  What  this  means  is that
    keyboard input to things like  dialog  boxes  (e.g.  the
    buffer  list)  will not be listed. The buffer so created
    is a normal buffer but will not be  automatically  saved
    when  you  exit. It is the user's responsibility to save
    the buffer is you want to keep the macro. 
    
RETURN VALUE     
    
    On completion of the recording, a keystroke macro ID  is
    returned containing. 
                     remove(string file) 
    
    
DESCRIPTION      
    This  function  is  equivalent  to  the  ANSI C function
    remove() for removing files.  
    
RETURN VALUE     
    On success a return  value  >=  0  is  returned;  -1  is
    returned  on  an error, and the global variable errno is
    set to the reason for the error. 
    
SEE ALSO     
    del() 
                  rename(old_file, new_file) 
    
    
DESCRIPTION      
    This primitive is used to rename a  file.  old_file  and
    new_file  should  be strings containing the names of the
    file. 
    
RETURN VALUE     
    Returns zero on success and -1 on  failure.  On  failure
    the  global  variable errno is set to the reason for the
    failure. 
                   restore_position([move]) 
    
    
DESCRIPTION      
    
    This macro restores a saved position from  the  position
    stack.  move  is an optional integer expression. If move
    is specified and is zero, then the saved position is not
    restored, but simply discarded. 
    
    The saved position stack is independent of  the  current
    buffer. 
    
RETURN VALUE     
    
    Returns  0 if there is no saved position on the stack; 1
    if position was successfully restored. 
    
    
                        return [expr]; 
    
    
DESCRIPTION      
    
    This  macro   is  used  to  return  from  a  macro,  and
    optionally return a value. If expr is specified, it  may
    be an integer, string or list expression. 
    
    The  current  macro  is terminated and control passes to
    the calling macro. 
    
RETURN VALUE     
    
    Value of expr. 
    
    
                       returns([expr]) 
    
    
DESCRIPTION      
    
    This macro is similar to return, except it doesn't cause
    the current macro to terminate. It  simply  sets  CRISPs
    internal  accumulator  with  the  value  of expr. If any
    other statements follow the execution of returns(), then
    the accumulator will be overwritten. 
    
    Use of this macro is not recommended. 
    
    This macro is not strictly compatible with the returns()
    macro of BRIEF. 
    
RETURN VALUE     
    
    Value of expr. 
    
    
                          right([n]) 
    
    
DESCRIPTION      
    
    Moves the cursor 'n' positions to  the  right.  This  is
    equivalent to adding 'n' to the current column position.
    Note  that  when  the  cursor  moves it doesnt move over
    characters atomically but one column  at  a  time.  This
    allows the cursor to move beyond the end of the line and
    into the middle of a tab stop, for example. 
    
    If  you  want  to move over physical characters, use the
    next_char() and prev_char() macros instead. 
    
    n may be positive or  negative.  negative  amounts  move
    leftward. 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                rindex(search-string, pattern) 
    
    
DESCRIPTION      
    
    This  function returns the index in search-string of the
    last occurence of pattern. This function is  useful  for
    splitting  a  filename  into  its filename and directory
    components. 
    
    If the user needs to  search  for  regular  expressions,
    then the function search_string should be used instead. 
    
    (See also index()). 
    
    
EXAMPLES      
    
    The  following  example splits a string into a directory
    and filename part. 
    
    	string	dir, file, filename; 
    	int	i; 
    	 
    	i = rindex(filename, "/"); 
    	if (i != 0) { 
    		dir = substr(filename, i - 1); 
    		file = substr(filename, i + 1); 
    		} 
    	else { 
    		dir = "."; 
    		file = filename; 
    		} 
    
    
RETURN VALUE     
    
    Returns 0 if pattern cannot be found  in  search-string;
    otherwise  returns  the  last  occurence  of  pattern in
    search-string. 
    
    
                       save_position() 
    
    
DESCRIPTION      
    
    This macro is used to save the current buffer and cursor
    position. It makes use of an  internal  position  stack;
    restore_position()  can  be  used  later  to restore the
    cursor position. 
    
    Note that the position stack is an independent stack  of
    any  buffer.  This  means that restore_position() may be
    called to pop off the top entry of the stack  even  when
    the  current buffer is not the same as buffer referenced
    by the top of the saved position stack. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     screen_dump([file]) 
    
    
DESCRIPTION      
    
    This macro is used to get  a  snapshot  of  the  current
    screen  image.  It  will write the current screen to the
    named file or to  the  file  /tmp/crisp.screen  if  file
    isn't specified. 
    
    It  does  not  make  use  of  the   screen's   character
    attributes  and  makes  an  approximation for the screen
    drawing characters. 
    
RETURN VALUE     
    
    -1 if cannot write file; 0 if successful. 
    
    
    search_back([pattern], [re], [case], [block], [length]) 
    
    
DESCRIPTION      
    
    This function searches from the current cursor  position
    backwards  towards  the  top  of  the buffer looking for
    pattern. 
    
    If pattern is omitted, it is prompted for. 
    
    If re is specified and  it  is  zero,  then  pattern  is
    treated  as  a  pure  string;  if  it  is  omitted or is
    non-zero,  then   pattern   is   treated  as  a  regular
    expression. (See  section  on  Regular  Expressions  for
    details of the syntax of regular expressions). 
    
    If  case  is  specified and is zero, then the pattern is
    treated  non-case   sensitively,   i.e.   A  matches  a.
    Otherwise  the  search  is  performed  with  case  being
    sensitive. 
    
    If block is specified and is non zero, then  the  search
    is confined to the currently marked region. 
    
    If  length  is  specified  and  is  non-zero,  then   it
    indicates  that on a successful return the length of the
    matched string should be returned +  1.  If  it  is  not
    specified, then the return length will take into account
    any c parameters in the regular expression. 
    
RETURN VALUE     
    
    Returns  0  if  pattern  not  found.  -1  if an error is
    detected. Otherwise it returns the length of the matched
    text + 1. 
    
    
                     search_case([case]) 
    
    
DESCRIPTION      
    
    This macro is used to set the value of the  search  case
    flag.  By  default all searches are case sensitive, i.e.
    "A" does not match "a". By  setting  case  to  non-zero,
    case  sensitivity  will  be  ignored   when   performing
    matches. 
    
    If case is omitted, the current value is toggled. 
    
RETURN VALUE     
    
    Returns the previous value of the case flag. 
    
    
    search_fwd([pattern], [re], [case], [block], [length]) 
    
    
DESCRIPTION      
    
    This  function searches from the current cursor position
    towards the end of the buffer looking for pattern. 
    
    If pattern is omitted, it is prompted for. 
    
    If re is specified and  it  is  zero,  then  pattern  is
    treated  as  a  pure  string;  if  it  is  omitted or is
    non-zero,  then   pattern   is   treated  as  a  regular
    expression. (See  section  on  Regular  Expressions  for
    details of the syntax of regular expressions). 
    
    If  case  is  specified and is zero, then the pattern is
    treated  non-case   sensitively,   i.e.   A  matches  a.
    Otherwise  the  search  is  performed  with  case  being
    sensitive. 
    
    If block is specified and is non zero, then  the  search
    is confined to the currently marked region. 
    
    If  length  is  specified  and  is  non-zero,  then   it
    indicates  that on a successful return the length of the
    matched string should be returned +  1.  If  it  is  not
    specified, then the return length will take into account
    any c parameters in the regular expression. 
    
RETURN VALUE     
    
    Returns  0  if  pattern  not  found.  -1  if an error is
    detected. Otherwise it returns the length of the matched
    text + 1. 
    
    
    search_list([start],  pattern,   list_expr,    [regexp],
                           [case]) 
    
    
DESCRIPTION      
    
    This  macro is used to search a linked list for a string
    pattern. 
    
    If start is not specified, the search  is  started  from
    the  beginning  of the list; otherwise the search starts
    from the atom numbered start. 
    
    pattern is the string to search for, and may or may  not
    be  a  regular  expression,  depending  on  the value of
    regexp. list_expr is the list to search. 
    
    If regexp is not specified or is zero, then  pattern  is
    not  treated as a regular expression. If it is specified
    and non-zero then pattern is considered to be a  regular
    expression. 
    
    If  case  is  specified  and  is non-zero, then the case
    sensitivity is taken into account. 
    
RETURN VALUE     
    
    The index of the atom in list_expr where the pattern was
    found; -1 otherwise. 
    
    
    search_string(pattern, string, [length], [re], [case]) 
    
    
DESCRIPTION      
    
    This macro is used to search  string  for  the  pattern,
    pattern. If re is specified and is zero, then pattern is
    treated  as  a literal string - not a regular expression
    (in which case this function is similar to index()).  If
    case  is  specified and is zero, then the search is done
    with case insensitive. 
    
    If length is specified (name of  an  integer  variable),
    then  it will receive the length of the matched pattern,
    if the search is successful. 
    
RETURN VALUE     
    
    Returns the starting character in string where the match
    was found, or zero if the match failed. 
    
    
                       self_insert([n]) 
    
    
DESCRIPTION      
    
    This macro is the means for the user to type  data  into
    the  current  buffer. It causes the last character to be
    typed to be inserted into the buffer  (or  overtyped  if
    overtype mode is on). 
    
    If  n is specified, then the character whose ASCII value
    is n is inserted into  the  file  instead  of  the  last
    character typed. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     send_signal(signal) 
    
    
DESCRIPTION      
    
    This  macro  is  used to send a signal to a process. The
    signal is sent to the process attached  to  the  current
    buffer.  If no process is attached to the current buffer
    then it is a no-op. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     set_backups([mode]) 
    
    
DESCRIPTION      
    
    This macro can be used to inquire  or  turn  on/off  the
    setting  of the backups flag. The backups flag is tested
    every time a buffer is written away (via  write_buffer).
    If the flag is on, then a backup file is made. 
    
    If  mode  is  not  specified,  then  the  backup flag is
    toggled. A non-zero value for mode turns backup creation
    on. Zero turns it off. 
    
    If called from the keyboard, then one of  the  following
    messages are printed: 
    
    Backups will be created. Backups will not be created. 
    
RETURN VALUE     
    
    Returns the previous value of the backup flag. 
    
    
                    set_binary_size(size) 
    
    
DESCRIPTION      
    
    This  macro  sets  a value called the binary chunk size.
    This is used when reading in binary files  to  break  up
    lines  into  chunks  so that the lines fit on the screen
    reasonably. The default chunk size  is  16  bytes.  Each
    line in a buffer needs about 16 bytes of memory overhead
    plus  the  data  for the line itself. This means that in
    the default condition, CRISP may need  memory  equal  to
    twice the size of the file being read in. Increasing the
    binary chunk size will lower this overhead considerably.
    
    If  the  value specified is <= 0, then files will not be
    interpreted as binary files when they are read in. 
    
RETURN VALUE     
    
    Previous value of the binary chunk size. 
    
    
                      set_buffer(bufnum) 
    
    
DESCRIPTION      
    
    This macro is used  for  changing  the  current  buffer;
    bufnum  is  a  buffer  identifier,  as  returned  via  a
    create_buffer() or inq_buffer() call. 
    
    set_buffer() does not cause any registered macros to  be
    called (unlike edit_file). 
    
RETURN VALUE     
    
    Returns  the ID of the previous buffer or less than zero
    if bufnum is an invalid buffer. 
    
    
             set_buffer_cmap([cmap_id], [buf_id]) 
    
    
DESCRIPTION      
    
    This macro is used to apply a  character  mapping  to  a
    buffer.  A  character  map  associated with a buffer has
    higher precedence than a map associated with a window. 
    
    The character map is used in converting column positions
    in a line into  the  actual  character  pointer  in  the
    internal code. 
    
    
SEE ALSO     
    create_char_map(), inq_char_map(), set_window_cmap() 
    
RETURN VALUE     
    
    Returns  value  of  cmap_id  or  -1  if  the   specified
    character map does not exist. 
    
    
           set_buffer_flags([and_mask], [or_mask]) 
    
    
DESCRIPTION      
    
    This  primitive  is  used  to  modify the internal flags
    associated with a buffer. If and_mask is set,  then  the
    internal mask is AND'ed with the mask; if or_mask is set
    then  the  internal  mask  is  OR'ed  with the mask. The
    and_mask  is   performed  before  the  or_mask.  If  the
    and_mask turns off the buffer  changed  flag,  then  the
    internal  'number of modifications' flag associated with
    the buffer is also cleared. 
    
    This allows a calling macro to make a set of changes  to
    a  buffer,  but  not  have  the  buffer  marked as being
    modified for the buffer_list macro or the exit code. 
    
    
    
    |==========|========================================|
    |Flag      |Meaning                                 |
    |==========|========================================|
    |0x01      |If set, buffer has been modified.       |
    |__________|________________________________________|
    |0x02      |If set, buffer will be backed up when   |
    |          |written away.                           |
    |__________|________________________________________|
    |0x04      |Buffer is marked as read-only.          |
    |__________|________________________________________|
    |0x08      |Reserved.                               |
    |__________|________________________________________|
    |0x10      |Underlying   file     has     execute   |
    |          |permission.                             |
    |__________|________________________________________|
    |0x20      |Process attached.                       |
    |__________|________________________________________|
    |0x40      |Buffer is in binary mode.               |
    |__________|________________________________________|
    |0x80      |ANSI mode -- color  escape  sequences   |
    |          |will  be  processed.  ANSI  mode will   |
    |          |only work if  the  current  character   |
    |          |map  has  the  ESCAPE  and  BACKSPACE   |
    |          |characters defined appropriately.       |
    |__________|________________________________________|
    |0x100     |Buffer does not map tabs to spaces.     |
    |__________|________________________________________|
    |0x200     |Buffer is a system buffer.              |
    |__________|________________________________________|
    |0x400     |Make  all   characters   in    window   |
    |          |visible.                                |
    |__________|________________________________________|
    |0x800     |Dont save undo info for buffer.         |
    |==========|========================================|
    
SEE ALSO     
    create_char_map(), set_buffer_cmap() 
    
RETURN VALUE     
    
    Nothing. 
    
    
                    set_calling_name(name) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to  set  the  calling name of the
    current macro. The calling name can be retrieved via the
    inq_called() macro. 
    
RETURN VALUE     
    
    Nothing. 
                     set_font(font_name) 
    
DESCRIPTION      
    This primitive is used to change the character font when
    running CRISP in a windowing  environment,  for  example
    X11. It is a no-op in other environments. Its purpose is
    to use the selected font name (which is a string). 
    
RETURN VALUE     
    Returns 0 on success and -1 on a failure. 
                   set_idle_default(value) 
    
    
DESCRIPTION      
    
    This  macro  can be used to change the value of the idle
    timer. 
    
RETURN VALUE     
    
    Previous value of idle timer. 
    
    
                   set_msg_level(msg_level) 
    
    
DESCRIPTION      
    
    This macro is used to set the message level. The message
    level is used to control what sort of messages are to be
    displayed on the status  line.  It  is  needed  by  some
    macros  which  dont  want  CRISP internal messages to be
    displayed. 
    
    msg_level  is  a  number  in  the  range  0-3  with  the
    following effects: 
    
    
    
    |==========|========================================|
    |Value     |Meaning                                 |
    |==========|========================================|
    |0         |This is the default  -  all  messages   |
    |          |on.                                     |
    |__________|________________________________________|
    |1         |Normal  messages  (those  printed via   |
    |          |(message) are not  displayed).  Error   |
    |          |messages still display.                 |
    |__________|________________________________________|
    |2         |Error messages are disabled.            |
    |__________|________________________________________|
    |3         |normal  messages  and  error messages   |
    |          |are disabled.                           |
    |==========|========================================|
    
    Message level 3  can  be  used  to  ensure  a  macro  is
    'quiet'. 
    
RETURN VALUE     
    
    Nothing. 
    
    
             set_process_position([line], [col]) 
    
    
DESCRIPTION      
    
    This  macro  sets the line and/or column associated with
    the input from a sub-process. line & col  are  optional,
    and  if specified are integer values specifying the line
    and column where input should carry on from. 
    
    Processes maintain their own independent  input  in  the
    buffer  so  that  it  is  easier  to  write macros which
    manipulate sub-processes. 
    
RETURN VALUE     
    
    Returns -1 if  current  buffer  is  not  attached  to  a
    process; returns 0 otherwise. 
    
    
    set_scrap_info([insert_newline], [mark_type], [buf_id]) 
    
    
DESCRIPTION      
    
    This macro is used to set the newline flag at the end of
    the  scrap bufferk. This flag controls whether a newline
    should  be  inserted  into  the  buffer  after  a  paste
    operation. This field is not currently supported. 
    
    The mark_type parameter is used to set the type of scrap
    information. The mark_type should be a number indicating
    the type of region which was  inserted  into  the  scrap
    buffer.  These  numbers  are  the  same  as  those   for
    drop_anchor(). 
    
    If  buf_id  is specified then that buffer is used as the
    new scrap buffer. 
    
RETURN VALUE     
    
    Nothing. 
    
    
    set_term_characters([top_left], [top_right], [bot_left],
                         [bot_right], 
    [vertical],  [horizontal],    [top_join],    [bot_join],
    [cross], 
    [left_join], [right_join]) 
    
DESCRIPTION      
    
    This macro is used to set the escape sequences needed to
    support  the  CRISP  window  drawing  characters.  These
    escape sequences are  non-standard  in  the  sense  that
    termcap  does  not  support them (although some of these
    are supported by terminfo, but CRISP does not  currently
    support terminfo). 
    
    This  macro  should  be  called  before  the  display is
    enabled (see enable_display()). 
    
    Each parameter is either NULL indicating that  no  value
    is  being  provided, or an integer or string expression.
    If an integer expression is specified, then CRISP treats
    this  as  meaning  that  the  escape  sequence  as  such
    consists of a single ASCII  character,  whose  value  is
    given  by the integer expression. If a string expression
    is given, then this string is printed when the  specific
    character is needed on the display. 
    
    The following parameters have the following meanings: 
    
    top_left  Printed  at  top  left  of  window.  top_right
    Printed at top right  of  window.  bot_left  Printed  at
    bottom  right of window. bot_left Printed at bottom left
    of window. vertical Printed at vertical line at side  of
    window. horizontal Printed on horizontal line at top and
    bottom  of  window.  top_join  Character used at the top
    right and top left  of  windows  where  they  abut  each
    other.  (Not  currently implemented). bot_join Character
    used at the bottom right  and  bottom  left  of  windows
    where they abut cross Character used to print where four
    windows  intersect  at  a   common   corner.   left_join
    Character  used  at intersection of three windows on the
    left side of main window. right_join Character  used  at
    intersection  of three windows on the right hand side of
    main window. 
    
    
EXAMPLES      
    
    For examples of how this macro is  used,  refer  to  the
    tty/*.cr  macros,  which  have  examples for a number of
    common environments. 
    
RETURN VALUE     
    
    Nothing. 
    
    
    set_term_features([space], [char], [icursor], [ocursor],
                         [vicursor], 
    [vocursor],  [escape],   [repeat],   [zerom],   [color],
    [escC],  
    [clr_color_is_black], [noscroll]) 
    
    
DESCRIPTION      
    
    This macro is used to specify certain  attributes  about
    the  current display - features which are not adequately
    handled by termcap of terminfo. 
    
    Each  parameter  is  either  NULL  indicating  that  the
    feature is  not  available,  or  an  integer  or  string
    expression.  zerom and color are boolean expressions and
    only integer expressions (zero or  non-zero)  should  be
    specified  for  these  two.  The   others   are   escape
    sequences, along the lines of set_term_characters(). 
    
    If  these escape sequences are not specified, CRISP will
    still function but will not perform very well. 
    
    If any of the  escape  sequences  can  be  described  as
    single  ASCII  characters then that particular parameter
    can be specified as an integer expression whose value is
    that ASCII character. 
    
    The parameters describe the following  features  of  the
    display: 
    
    |==========|========================================|
    |Arg       |Description                             |
    |==========|========================================|
    |space     |This  is  an  escape sequence used to   |
    |          |blank  out   the   next  N  character   |
    |          |positions. This is usually defined as   |
    |          |"x1B[%dX"  for  those  displays  that   |
    |          |understand the ANSI ESC  [  X  escape   |
    |          |sequence.  The  escape  sequence must   |
    |          |have  an  embedded  '%d'  to  specify   |
    |          |where the numeric qualifier goes.       |
    |          |                                        |
    |          |If  this   escape   sequence  is  not   |
    |          |defined, then  CRISP  makes  do  with   |
    |          |printing the correct amount of spaces   |
    |          |and  then  moving  the cursor back to   |
    |          |the start of the cleared region. This   |
    |          |is not  as  efficient  as  the  ESC[X   |
    |          |escape sequence when N is larger than   |
    |          |about 8 or 9 characters.                |
    |__________|________________________________________|
    |char      |This  is  an  escape sequence used to   |
    |          |allow access to characters  with  the   |
    |          |top   bit    set.    Some   displays,   |
    |          |especially those based on the  IBM/PC   |
    |          |require  a special escape sequence to   |
    |          |access the characters  with  the  top   |
    |          |bit set.                                |
    |          |                                        |
    |          |It  is valid for a '%c' or '%d' to be   |
    |          |embedded in the character definition.   |
    |          |                                        |
    |          |If  this   escape   sequence  is  not   |
    |          |defined, CRISP  will  avoid  printing   |
    |          |characters  with  the top bit set and   |
    |          |will use  the  display_mode()  option   |
    |          |instead.                                |
    |          |                                        |
    |          |If  this  option  is  defined,  CRISP   |
    |          |turns  off   the  display  mask  (see   |
    |          |dislpay_mode).    This        ensures   |
    |          |characters  with  the top bit set get   |
    |          |printed properly. If you  want  8-bit   |
    |          |characters   to   be   displayed   in   |
    |          |Hex/Octal then you'll need  to  reset   |
    |          |the mask.                               |
    |__________|________________________________________|
    |icursor,  |These  escape  sequences  are used to   |
    |          |change what the  cursor  looks  like.   |
    |vicursor  |These  sequences represent the insert   |
    |,         |cursor,   virtual-insert      cursor,   |
    |ocursor,  |overtype cursor, and virtual-overtype   |
    |          |cursor respectively.                    |
    |vocursor  |                                        |
    |          |If  these  escape  sequences  are not   |
    |          |defined  CRISP  will  display  a  two   |
    |          |character mnemonic on the status line   |
    |          |indicating what mode  the  cursor  is   |
    |          |in.                                     |
    |__________|________________________________________|
    |repeat    |This  defines  an escape sequence for   |
    |          |repeating  the   previous   character   |
    |          |printed. It is not currently used.      |
    |__________|________________________________________|
    |escape    |This defines an escape sequence  used   |
    |          |for  printing  out  the ESC character   |
    |          |itself.  This  is  available  because   |
    |          |some systems have a  feature  whereby   |
    |          |there  is a short cut to printing the   |
    |          |ESC character.                          |
    |__________|________________________________________|
    |zerom     |If this is non-zero, then whenever an   |
    |          |ESC[0m is printed, it is assumed that   |
    |          |the background and foreground colours   |
    |          |get  reset.   This   is    true    of   |
    |          |Interactive   V.3    (although    not   |
    |          |Microport).                             |
    |__________|________________________________________|
    |color     |If non-zero, then  terminal  supports   |
    |          |color. The escape sequences for color   |
    |          |are  built  into CRISP. CRISP assumes   |
    |          |that if this is set, that the ANSI  X   |
    |          |3.64 escape sequences are valid.        |
    |__________|________________________________________|
    |escC      |Indicates escape sequence to move 'n'   |
    |          |columns  over  is  available. (Needed   |
    |          |because termcap cannot describe  this   |
    |          |entry).                                 |
    |__________|________________________________________|
    |clr_colo  |Sending  an  escape sequence to erase   |
    |r_is_bla  |an area (e.g. to end  of  line)  sets   |
    |ck        |the  area  to  black   if   this   is   |
    |          |specified.  If  not   specified,   or   |
    |          |FALSE,  then  area  gets  set  to the   |
    |          |current background color.               |
    |__________|________________________________________|
    |noscroll  |Set to TRUE to  avoid  scrolling  the   |
    |          |window  when  attempting  to optimise   |
    |          |output. On  some  bitmapped  displays   |
    |          |its faster to rewrite the window.       |
    |__________|________________________________________|
    |graphics  |Escape  sequence to send when sending   |
    |          |graphics (line drawing) characters.     |
    |__________|________________________________________|
    |text      |Escape sequence to send when  exiting   |
    |          |graphics  mode  and  going  back   to   |
    |          |normal character set.                   |
    |==========|========================================|
    
EXAMPLES      
    
    Refer to the tty/*.cr files for examples of this macro. 
    
RETURN VALUE     
    
    Nothing. 
    
    
