                   declare var1, var2, ..; 
    
    
DESCRIPTION      
    
    This  is   used   to  define  one  or  more  polymorphic
    variables. Polymorphic variables are variables that  may
    take  on any of the available CRISP data types (integer,
    string or list), depending on context. 
    
    Polymorphic variables are most useful when dealing  with
    lists which contain unknown data types. 
    
    The  variables  declared  are made into local variables,
    unless a global() declaration follows. 
    
    By default, polymorphic variables are typed as integers,
    and are given the value zero. 
                        del(filename) 
    
    
DESCRIPTION      
    
    THIS FUNCTION IS PROVIDED FOR COMPATABILITY ONLY via the
    brief.cr MACRO FILE. 
    
    This macro is used to delete a file, as specified by the
    string expression 'filename'. 
    
    Wild-cards, etc, are not valid in 'filename'. 
    
RETURN VALUE     
    
    Zero or less if unsuccessful; greater  than  zero  means
    the file was successfully deleted. 
    
SEE ALSO     
    remove() 
                        delete_block() 
    
    
DESCRIPTION      
    
    The currently highlited block is deleted. 
    
RETURN VALUE     
    
    Nothing. 
                   delete_bookmark(book_no) 
    
DESCRIPTION      
    This  macro  is used to delete a bookmark. book_no is an
    integer containing the bookmark to delete. 
    
RETURN VALUE     
    Nothing. 
    
SEE ALSO     
    bookmark_list(), drop_bookmark(), goto_bookmark() 
                    delete_buffer(bufnum) 
    
    
DESCRIPTION      
    
    This command deletes the buffer specified by bufnum. The
    entire  buffer   contents   are  freed,  and  any  other
    resources attached to that buffer are destroyed as well.
    In the case of  a  process  buffer,  the  subprocess  is
    killed. 
    
    Any  attempt  to set_buffer() to a buffer which has been
    deleted will fail. 
    
    Care should be taken with delete_buffer() since no tests
    are made to see if the buffer being deleted is currently
    displayed. If a currently displayed buffer  is  deleted,
    then  CRISP  may core-dump. Macros using delete_buffer()
    should be carefully  tested  to  ensure  this  does  not
    happen, e.g. by calling inq_views(). 
    
    
RETURN VALUE     
    
    No value is returned. 
    
    
EXAMPLES      
    
    The  following  example  creates  a temporary buffer and
    then deletes it after restoring the  current  buffer  at
    the time of the macro is invoked. 
    
    	int	newbuf; 
    	int	curbuf; 
    	 
    	curbuf = inq_buffer(); 
    	newbuf = create_buffer("Example", NULL, 1); 
    	 
    	set_buffer(newbuf); 
    	  . 
    	  . 
    	set_buffer(curbuf); 
    	delete_buffer(newbuf); 
    
    
                      delete_char([num]) 
    
    
DESCRIPTION      
    
    This  macro  deletes  one  or  more  characters from the
    current  buffer.   If  num  is  not  specified,  then  1
    character is deleted; if  num  is  specified  then  that
    number of characters are deleted. The deleted characters
    are on and to the right of the current buffer position. 
    
    This  macro  is  the default assignment for the <Delete>
    key on the keyboard. 
                   delete_edge([direction]) 
    
    
DESCRIPTION      
    
    This macro can be used to delete a window on-screen.  It
    is  used  by specifying an edge, and if there is another
    window which adjoins the edge, then the edge is  deleted
    and the two windows combined into one. 
    
    direction  specifies  the  edge  to  delete  and  if not
    specified, is prompted for, and the  user  can  use  the
    arrow keys to specify the edge. 
    
    When  using  this macro, the edge to be deleted must not
    be obscured by  other  edges,  i.e.  only  tiled  window
    support is allowed for this macro. 
    
    If  direction  is  specified,  it should have one of the
    following values: 
    
    	0  Up 
    	1  Right 
    	2  Down 
    	3  Left 
    
    
RETURN VALUE     
    Returns <= 0 if unsuccessful; >0 otherwise. 
                        delete_line() 
    
    
DESCRIPTION      
    
    This macro deletes the line the cursor is currently  on.
    The  cursor is placed at the same column position in the
    line below the one deleted. 
    
    
EXAMPLES      
    
    The following example assigns the delete_line() macro to
    the <ALT-D> key (the usual case). 
    
    	assign_to_key("<Alt-D>", "delete_line"); 
    
    
                     delete_macro([file]) 
    
    
DESCRIPTION      
    
    This macro is used  to  delete  all  macros  which  were
    loaded  from  a  particular macro file. file is a string
    expression and if omitted is  prompted  for,  containing
    the name of the file. 
    
    This  is  currently  a  no-op  in CRISP - macros are not
    deleteable entities. The storage allocated for  a  macro
    is  lost  when  a  macro by the same name is loaded from
    another file. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                       delete_to_eol() 
    
    
DESCRIPTION      
    
    This macro deletes all characters up to the end  of  the
    line in the current buffer. 
    
RETURN VALUE     
    Nothing. 
    
    
                   delete_window([win_id]) 
    
    
DESCRIPTION      
    
    This  macro can be used to delete a window. If win_id is
    not specified then the current window is deleted. 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                         disconnect() 
    
    
DESCRIPTION      
    
    This macro is used to kill a sub-process attached  to  a
    buffer.  The  subprocess is sent a SIGTERM followed by a
    SIGKILL signal. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                    display_mode([flags]) 
    
    
DESCRIPTION      
    
    This macro is used to read and optional set the  display
    control  flags.  The  display control flags are a set of
    attributes used to control the way certain things happen
    on the screen. The flags are defined as follows: 
    
    0x0001  Window  mode.  This  indicates  we  are  running
    natively under a windowing system, e.g. X-Windows.  This
    bit is read only. 
    
    0x0002  When set, causes pop up windows to have a shadow
    (Default is set).  This  may  be  turned  off  for  slow
    terminals. 
    
    0x0004 This indicates that the window shadow should show
    through the underlying text on the screen. 
    
RETURN VALUE     
    
    Returns previous value of display control flags. 
    
    
                  display_windows([enable]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to enable the display. By default
    when CRISP starts up, the code for updating  the  screen
    is  disabled.  The  startup  macros  initialise   CRISPs
    internal character translation tables and then call this
    macro to allow CRISP to proceed. 
    
    If  enable  is  not specified, then the current value is
    toggled. If it is non-zero, then the display is enabled.
    
    If the display is not enabled, then CRISP can be used as
    a normal programming language, in the style of  awk  and
    sed,  using  the  command  line  arguments  to  load and
    execute a file. 
    
RETURN VALUE     
    
    Previous value of the display flag. 
    
    
                      distance_to_tab() 
    
    
DESCRIPTION      
    
    This macro returns the number of characters between  the
    current  cursor  location and the next tab stop, even if
    there are no more  characters  after  the  cursor.  This
    number will always be > than zero. 
    
    If  the  cursor  is  on  a  tab stop, then the number of
    characters to the next tab stop are returned.

    
RETURN VALUE     
    
    Number of characters between current cursor location and
    next tab stop. 
    
    
                    do stmt while (cond); 
    
    
DESCRIPTION      
    
    The do keyword is used to implement a  C-like  do  loop.
    This  loop  structure  is  similar to the (while) macro,
    except the condition for loop termination is  tested  at
    the end of the loop. stmt is evaluated at least once. 
    
    break and continue may be used within a do-loop. 
    
RETURN VALUE     
    
    Returns zero. 
    
    
           dos([command] [use_shell] [completion]) 
    
    
DESCRIPTION      
    
    THIS  FILE  IS  PROVIDED  FOR COMPATABILITY ONLY via the
    brief.cr MACRO FILE. 
    
    Please see the shell() command for further information. 
    
RETURN VALUE     
    
    Returns the shell  exit  status  (under  Unix,  0  means
    command  exited  successfully,  non-zero  means  command
    failed for some reason). 
    
    
                        down([lines]) 
    
    
DESCRIPTION      
    
    Moves the cursor to the same column on the  line  below.
    If  lines  is  specified  then  cursor  is  moved to the
    lines'th line after the current. lines may  be  negative
    in which case the cursor moves backwards. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     drop_anchor([type]) 
    
DESCRIPTION      
    
    This macro is used to define a region within the current
    buffer.  type  specifies  the  type  of  region, and the
    values are given  below.  If  omitted  a  normal  marked
    region is selected. 
    
    Regions  are  areas  of  a buffer upon which some macros
    have special effects, e.g. cut() and copy() are used  to
    extract  fragments  of  buffers  and save them for later
    re-insertion. The search_fwd() and search_back()  macros
    can  be  told  to  limit their searches to the highlited
    regions, etc. 
    
    Regions are displayed on screen either  in  a  different
    color, or in reverse video so that they stand out. 
    
    The following are the different region types: 
    
    	1 Normal  
    	2 Column  
    	3 Line  
    	4 Non-inclusive. 
    
    
    A  normal  mark  is  a region which encompasses from the
    place where the anchor was dropped  upto  and  including
    the current cursor position. A non-inclusive mark is the
    same but does not include the current cursor position. 
    
    A  line  mark  selects entire lines, and allows for easy
    movement of text from one part of a buffer to another. 
    
    A column mark is similar to a  normal  mark,  except  it
    displays  differently  on screen, and allows rectangular
    sections of the current buffer to be marked. 
    
    The currently selected marked area  can  be  found,  via
    inq_marked().  Column  operations   are   not   directly
    supported by CRISP internally, but instead are supported
    by the macros supplied with CRISP. 
    
    Regions  are nestable, i.e. multiple drop_anchor()'s can
    be issued without any intervening raise_anchor(). 
    
    The  marked   region   can   be   cleared   by   calling
    raise_anchor() or performing a copy() or cut() operation
    on the buffer. 
    
RETURN VALUE     
    
    Nothing. 
    
    
    drop_bookmark([book_num], [yes], [buf], [line], [col]) 
    
    
DESCRIPTION      
    
    This macro is used to set a bookmark. A bookmark is like
    a normal bookmark - it is a place holder  in  a  buffer.
    book_num  is an identifier associated with the bookmark.
    Any valid integer can be used as the identifier. yes  is
    a  string  which  if  set  to  'y' or 'Y' will cause any
    previous  bookmark   with  the  same  identifier  to  be
    overwritten. 
    
    If buf, line & col are non-NULL, then bookmark  book_num
    is  set  to  the specified buffer at the designated line
    and column position. If buf, line or col are  NULL  then
    the  bookmark  is  set from the current buffer, line and
    column position. 
    
    
RETURN VALUE     
    
    Greater than  zero  if  bookmark  dropped,  or  zero  if
    operation failed. 
    
SEE ALSO     
    bookmark_list(), delete_bookmark(), goto_bookmark() 
    
    
                      echo_line([flags]) 
    
    
DESCRIPTION      
    
    The  echo_line()  macro  is used to control which fields
    are visible in the status line. If flags is omitted then
    the current setting is returned. 
    
    flags is an integer expression,  whose  bit  pattern  is
    interpreted as follows: 
    
    	0x01	Line: field enabled.  
    	0x02	Col: field enabled.  
    	0x04	Percentage through file enabled.  
    	0x08	Current time enabled. 
    	0x10	REmember/PAuse reminders enabled.  
    	0x20	Cursor type displayed. 
    
    
    The cursor type is only used if the screen cannot change
    the  cursor  type  to   indicate   insert/overtype   and
    normal/virtual space. 
    
    
RETURN VALUE     
    
    Previous value of flags. 
    
    
           edit_file([mode,] [file1], [file2], ..) 
    
    
DESCRIPTION      
    
    This  macro  is  the  usual  way of editing a file; if a
    buffer is already allocated for the file, then  that  is
    set  as  the  current  buffer. Otherwise a new buffer is
    created, the contents of the named file  are  read  into
    that,  and  the  filename is associated with that buffer
    (so that later on a write_buffer() can be used  to  save
    any changes made to the buffer). 
    
    The  argument list is a set of strings and optional mode
    specifications. Mode specifications are  integers  which
    are  used  to  control how subsequent files are read in.
    The default is 'normal'. In normal mode, CRISP looks  at
    the file as it is read in and tries to decide (sometimes
    wrongly)  whether  a  file  is  binary,  ascii,   or   a
    MSDOS-like  file  with  carriage  returns  as  well   as
    linefeeds  at the end of each line. When a file is read,
    if there are more than a certain number of non-printable
    characters in at the beginning of the  file  (controlled
    by  the  set_binary_size()  primitive), then the file is
    broken into fixed length chunks per  line,  rather  than
    using the line-feed character as the line terminator. 
    
    For  ASCII files, newlines preceded by a carriage return
    are treated as DOS files  and  the  carriage  return  is
    removed  and  a  flag is set for the buffer so that when
    the file is  subsequently  written  back  to  disk,  the
    carriage  returns  will  be automatically added on. Only
    the first line is checked for the CR character before  a
    LF.  If  there  isn't a CR before a LF at the end of the
    first line, then the file is a normal Unix  ascii  file.
    Any subsequent CR's detected in the file are kept. 
    
    If  the  mode  specification  flag  is specified then it
    applies to all subsequent files in the argument list, or
    until  another  mode  specification  is  met.  The  mode
    specification flag can be used to 'override' the default
    default heuristic described in the  previous  paragraphs
    and is a set of bits defined as follows: 
    
    
    
    |=====|==========|==============================|
    |Val  |Name      |Description                   |
    |ue   |          |                              |
    |=====|==========|==============================|
    |0x0  |EDIT_NOR  |This is the default.          |
    |0    |MAL       |                              |
    |_____|__________|______________________________|
    |0x0  |EDIT_BIN  |Force file to be treated as   |
    |1    |ARY       |a binary file.                |
    |_____|__________|______________________________|
    |0x0  |EDIT_ASC  |Force file to be treated as   |
    |2    |II        |an ASCII file.                |
    |_____|__________|______________________________|
    |0x0  |EDIT_CR   |Force  CR return characters   |
    |4    |          |at  end   of   line  to  be   |
    |     |          |removed  on   input,    and   |
    |     |          |written on output.            |
    |=====|==========|==============================|
    
    This  macro  supports wild-cards and the ability to edit
    multiple files at once. If more  than  one  argument  is
    specified,  then  a separate edit_file() is performed on
    each file, and the current buffer is  set  to  the  last
    file read in. 
    
    The normal c-shell wildcards are supported: 
    
    *	wild-card -- matches any number of characters.  
    ?	wild-character -- matches any single character.  
    [l-m]	any character in range at this character.  
    ~/	as first part of filename matches home directory  
    ~user/	matches 'user's home directory. 
    
    
    If  no filenames are specified, the user is prompted for
    a filename. 
    
    
RETURN VALUE     
    
    Returns 1 if new file edited; zero if edit_file  aborted
    at  the  Edit file prompt; returns < 0 if its a new file
    or permission denied. On an error, the  global  variable
    errno will be set to the reason for the failure. 
    
    
EXAMPLES      
    
    The  following  example  can  be  used to read in all .c
    files in the current directory: 
    
    edit_file("*.c"); 
                         ega([mode]) 
    
    
DESCRIPTION      
    
    This macro can be used to toggle  between  EGA  25  line
    mode  and  EGA  43 line mode -- only if CRISP is running
    under Unix V.3.2 or above on an EGA or VGA console. 
    
    If mode is not specified,  then  only  the  current  EGA
    state is returned. 
    
    NOTE:: This primitive is subject for removal. 
    
RETURN VALUE     
    
    Previous value of EGA mode. 
    
    
                       end_of_buffer() 
    
    
DESCRIPTION      
    
    Moves  the  cursor  to  the  end of the last line in the
    current buffer. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                        end_of_line() 
    
    
DESCRIPTION      
    
    Moves the cursor to the end of the current line. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                       end_of_window() 
    
    
DESCRIPTION      
    
    Moves the cursor to the last line  of  the  window.  The
    cursor stays in the same column position. 
    
RETURN VALUE     
    
    Returns  1  if  cursor  moved; 0 if cursor stayed in the
    same position. 
    
    
                error(fmt, [arg1], [arg2], ..) 
    
    
DESCRIPTION      
    
    This macro is used to print  a  message  on  the  status
    prompt  line.  fmt  is  a  string with possible embedded
    printf-like %  options.  arg1,  arg2,  ..  are  optional
    arguments  (upto  4 parameters) which either evaluate to
    strings or integer values. 
    
    The %  options  are  the  same  as  for  the  underlying
    printf()  which  the  system  supports.  (Internally the
    string coding is handled by  sprintf).  Please  see  the
    description  of  the  message()  macro for a list of the
    minimum supported set of % options. 
    
    This macro is  similar  to  message()  except  that  the
    message string is classified as an error. Error messages
    are printed in the error color (see color()). 
    
    In  addition,  if  the  pause_on_error flag has been set
    (see  pause_on_error())   then   the  error  message  is
    displayed suffixed with a '..' and CRISP waits  for  the
    user  to  type  any  key  to continue. This is useful in
    debugging. 
    
    Error messages are truncated if they are too long. 
    
    
RETURN VALUE     
    Nothing. 
    
EXAMPLES      
    
    	string	mac = "fred"; 
    	 
    	error("Macro %s not loaded", fred); 
    
    
SEE ALSO     
    message(), printf() 
                          eval(str) 
    
    
DESCRIPTION      
    
    This function evaluates the string 'str' as if it were a
    program written in the CRUNCH language. The program  may
    be  any  sequence  of  valid program statements/function
    definitions. 
    
    Please note that the C-preprocessor  functions  are  not
    available in this mode. 
    
RETURN VALUE     
    
    Result of executing the program 'str'. 
    
    
                execute_macro([macro], [args]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to  execute  another macro. It is
    needed because it is the only way  to  execute  a  macro
    which  is defined by a string expression, rather than by
    virtue of the CRISP language syntax. 
    
    macro should be a string expression and  if  omitted  is
    prompted  for;  args  are optional and are the arguments
    passed to the macro. 
    
RETURN VALUE     
    
    Returns the value of (macro args). 
    
    
                       exist(filename) 
    
    
DESCRIPTION      
    
    Checks for existence of file. The existence of the  file
    is  performed  by doing a stat() call on the named file.
    Therefore this can be used for all file types (including
    character/block devices, etc). 
    
RETURN VALUE     
    
    Non-zero if filename  exists;  zero  if  file  does  not
    exist.  If file does not exist, then the global variable
    errno is set to the reason for the error. 
    
    
                            exit() 
    
    
DESCRIPTION      
    
    This macro is  used  to  exit  from  CRISP,  or  from  a
    recursive process() macro invocation. 
    
    If  called  at  the  bottom  level  of CRISP, CRISP goes
    through its exit  procedure  and  prompts  the  user  if
    he/she is sure, if there are any buffers which have been
    modified. 
    
    If  called from within a nested invocation of process(),
    on the next attempt to read keyboard input  the  calling
    process() macro will return. 
    
    Note  that  CRISP  currently  does   not   support   the
    [are_you_sure] option which BRIEF supports. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                            exp(x) 
    
    
RETURN VALUE     
    
    Returns the irrational number 'e' to the power of x as a
    floating point value. 
                         _extension() 
    
DESCRIPTION      
    This  macro  is  a  callback macro called whenever CRISP
    edits a  file  via  the  edit_file()  primitive.  It  is
    provided  to  allow users to write their own hooks, e.g.
    to set tab stops on a file extension basis. 
    
    This macro is called with no arguments. 
                 extern TYPE var1, var2, ..; 
    
    
DESCRIPTION      
    
    The extern keyword is used to  declare  variables  which
    are not defined within the current file or function, but
    are  available elsewhere. Essentially the extern keyword
    creates a place holder in  the  symbol  table  to  avoid
    undefined symbol reference errors. 
                           fabs(x) 
    
    
RETURN VALUE     
    
    Absolute value of x, |x| as a floating point value. 
                        _fatal_error() 
    
DESCRIPTION      
    This  is  a  callback  macro.  It  is  called when CRISP
    detects a segmentation violation internally, and  exists
    to  allow the called macro to take emergency actions and
    save  any   modified   buffers   to  disk.  Segmentation
    violations should not normally occur, and may occur  due
    to  bugs  in  either  a users macro, or some rarely used
    primitive. The macro that is called should use very  few
    facilities of CRISP to avoid hitting the same bug again.
    
    Refer  to  the  core.cr macro for an example of how this
    macro is uesd. 
                      file_glob(string) 
    
    
DESCRIPTION      
    
    This macro implements a shell-style  globbing  facility,
    and  facilitates  writing  macros  which want to perform
    wild-card name expansion. 
    
    
RETURN VALUE     
    
    A list of strings corresponding to the  filenames  which
    match the wild card expression in string. 
    
    
                    file_pattern(filespec) 
    
    
DESCRIPTION      
    
    This  macro  is used in conjunction with the find_file()
    macro to implement a directory lookup mechanism. 
    
    filespec is a string expression which should evaluate to
    a file name or a  wild-card  filename.  find_file()  can
    then  be used to read the filenames of files which match
    the file-spec. 
    
    
EXAMPLES      
    
    See example in find_file() for  an  example  of  how  to
    iterate through all files in the current directory. 
    
RETURN VALUE     
    
    Nothing. 
    
SEE ALSO     
    find_file(), file_list() 
     find_file([name], [size], [mtime], [ctime], [mode]) 
    
    
DESCRIPTION      
    
    find_file() is used in conjunction to evaluate filenames
    in  a  particular  directory.  The  base  directory  and
    wild-card filename pattern are set  via  file_pattern().
    Thereafter  find_file()  can be called repeatedly, until
    it fails, receiving the next file name which matches the
    pattern set in file_pattern(). 
    
    name is an optional name of  a  string  variable,  which
    receives  the  filename which matched the pattern if the
    find_file() was successful. size is the size of the file
    (in bytes), and is an integer variable. mtime and  ctime
    are  the names of integer variables and receive the last
    modification and creation times, as returned by the Unix
    stat() system call. mode is the file mode as returned by
    stat(), and should be the name of an integer variable. 
    
    There are two hash-defines in crisp.h which  define  two
    of  the  bit  definitions  for  the  mode  field.  These
    definitions are taken from  the  /usr/include/sys/stat.h
    file.  If  you  use these #define's be careful to ensure
    they are compatible with your Unix system. 
    
    For  a  more  thorough  example  of  the  use  of  these
    primitives, see the abbrev.m macro file. 
    
    
EXAMPLES      
    
    The following example evaluates the names of  all  files
    in  the current directory and inserts the names and mode
    information into the current buffer. 
    
    	string	name; 
    	int	mode, size; 
    	 
    	file_pattern("*"); 
    	while (find_file(name, size, NULL, NULL, mode) > 0) { 
    		sprintf(buf, "file=%s, size=%d, mode=%x",  
    			name, size, mode); 
    		insert(buf + ""); 
    		} 
    
    
RETURN VALUE     
    
    Returns zero if there are no more files;  returns  1  if
    next directory entry successfully received. 
    
SEE ALSO     
    file_pattern(), file_list() 
    
    
                     find_macro(filename) 
    
    
DESCRIPTION      
    
    This  primitive is similar to the load_macro() primitive
    but it doesn't actually load the  specified  macro.  The
    current  macro  path (BPATH) is searched looking for the
    specified file. If the specified file has an  extension,
    then  an  exact  match  is  located.  If no extension is
    specified, then files with the extensions: .cm, .cr, and
    .m are searched in that order. 
    
    This macro is designed to allow user  macros  to  locate
    macro files using the same algorithm as the laod_macro()
    primitive uses. 
    
RETURN VALUE     
    
    String  containing full path and filename of macro file,
    or the NULL string if not file could be found. 
    
    
SEE ALSO     
    autoload, load_macro 
                         first_time() 
    
    
DESCRIPTION      
    
    CRISP maintains an internal 'first_time' flag for  every
    macro;  after  the  first call to the macro, the flag is
    set to FALSE. This makes it easier for macros to perform
    a once-only initialisation. 
    
RETURN VALUE     
    
    1 if this is the first time a macro has been  called;  0
    otherwise. 
    
    
                    float var1, var2, ...; 
    
    
RETURN VALUE     
    
    Declares a floating point variable. (64-bit size). 
    
    
DESCRIPTION      
    
    This  primitive  is  used for declaring a floating point
    variable. Floating  point  variables  are  stored  using
    double precision (64-bits). 
    
    Future  versions  of  CRISP  may  use  single  precision
    floating point format for floats. If you want to  ensure
    that your code will use double precision format, use the
    double declaration keyword. 
    
SEE ALSO     
    double 
                           floor(x) 
    
    
RETURN VALUE     
    
    Largest  integer not greater than x, as a floating point
    number. 
    
SEE ALSO     
    ceil 
                          fmod(x, y) 
    
    
RETURN VALUE     
    
    Floating point remainder of x/y (x and y  both  floating
    point), with the same sign as x. 
                 for (init; cond; post) stmt 
    
    
DESCRIPTION      
    
    This macro is used to implement a C-like loop structure.
    init,  cond,  post and stmts maybe expressions or a list
    of  statements   to  execute.  The  init  expression  is
    evaluated first. Next the cond condition  is  evaluated.
    If  it  is  non-zero,  then  the  stmt   expression   is
    evaluated,  followed   by   evaluation   of   the   post
    expression. The loop continues until the cond expression
    evaluates to non-zero. 
    
RETURN VALUE     
    
    Returns  the value of the last statement executed in the
    loop. Normally zero. 
    
    
                        frexp(x, exp) 
    
    
RETURN VALUE     
    
    This function converts the floating point number x  into
    a  normalized  fraction  in  the interval [1/2, 1]. This
    value is returned ans the power of  2  representing  the
    exponent  is  stored  in  exp.  exp should be an integer
    variable. 
    
    
    get_color([background], [normal], [region],  [messages],
             [errors], [hilite_bg], [hilite_fg]) 
    
    
DESCRIPTION      
    
    This  macro  can  be  used to find out the values of the
    color attributes of the  screen.  Each  argument  is  an
    optional  integer  variable  to  receive  the  specified
    color. 
    
    The colors are integers which are defined below. 
    
    |========|=============|==============================|
    |Code    |Color        |______________________________|
    |========|=============|==============================|
    
RETURN VALUE     
    
    Nothing. 
                   get_mouse_position(x, y) 
    
DESCRIPTION      
    This  primitive   is   used  to  receive  the  x  and  y
    co-ordinates of the last mouse  press  or  release.  The
    values  returned  are  only  valid immediately after the
    macro assigned to a button press event.  Any  subsequent
    calls  to  read_char()  or  process() will overwrite the
    internal values. 
    
    x and y should be integer variables. 
    
RETURN VALUE     
    Nothing 
    
SEE ALSO     
    process_mouse(), translate_pos() 
                         getenv(name) 
    
    
DESCRIPTION      
    
    This function looks up 'name'  in  the  environment  and
    returns  the  value  of  name.  It  is  similar to the C
    function getenv(). 
    
RETURN VALUE     
    
    Returns a string which is  the  contents  of  the  named
    environment variable, or the null string if the variable
    does not exist. 
     get_parm([arg], var, [prompt], [length], [default]) 
    
    
DESCRIPTION      
    
    get_parm()  is  the  mechanism  for accessing parameters
    passed to macros. get_parm() can also be used to  prompt
    the  user  for  input,  and  possibly  specify a default
    value. 
    
    Arguments passed to macros are numbered,  zero  upwards.
    If  arg  is specified, then it is evaluated to the value
    of the argument number to be retrieved. If it  is  NULL,
    then  the  user is prompted for the value, in which case
    prompt is the message to prompt the  user,  and  default
    (if  specified)  is the default value which the user can
    then edit, using the command line editing. If length  is
    specified, it is the maximum number of characters in the
    user's  input  (usually used only for string variables).
    The users input is  terminated  by  hitting  <Enter>  or
    reaching the length. 
    
    var  is the name of an integer, string or list variable.
    If the user is being prompted,  then  only  integer  and
    string  expressions  may  be input. List expressions are
    not supported. 
    
    Arguments passed to macros are passed as call  by  name,
    ie  every  time  a  get_parm() is issued on a particular
    parameter, that parameter is re-evaluated. This  can  be
    very  useful  sometimes, and at other times it can cause
    anomalous side-effects. 
    
    
RETURN VALUE     
    
    Zero if user aborted prompt, or argument number does not
    exist. Greater than zero if successful. 
    
    
    get_term_characters([top_left], [top_right], [bot_left],
                        [bot_right],  
    [vertical],  [horizontal],    [top_join],    [bot_join],
    [cross], [left_join],  
    [right_join]) 
    
    
DESCRIPTION      
    
    This  macro can be used to find out the current settings
    for the various characters which  make  up  the  special
    characters  needed  to display the window borders on the
    screen. 
    
    Each parameter is the  name  of  a  string  variable  to
    receive the string expression. Any of the parameters may
    be omitted. 
    
    This  macro  is  designed  to allow macros to be written
    which make it easier for the user to tailor the display.
    
    Refer to set_term_characters() for further detail on the
    meaning of each of these characters. 
    
RETURN VALUE     
    
    Nothing. 
    
    
    get_term_features([space], [char], [icursor], [ocursor],
                               
    [vicursor],  [vocursor],  [escape],  [repeat],  [zerom],
    [color]) 
    
    
DESCRIPTION      
    
    This macro is used  to  retrieve  the  terminal  options
    which  the  current display supports. All the parameters
    are the names of string variables, except for zerom  and
    color which are the names of integer variables. 
    
    Refer  to  set_term_features()  for a description of the
    meaning of each feature. 
    
    This macro is designed to be used to allow macros to  be
    written  which  allow  the user to easily tailor his/her
    display environment. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                    (get_term_keyboard ..) 
    
    
DESCRIPTION      
    
    This macro  is  designed  to  allow  the  calling  macro
    retrieve  the  assignments  for each key, so that a user
    interface can be written to examine and display the  key
    bindings. 
    
    See  set_term_keyboard()  for  more  details of how this
    macro is supposed to work. 
    
    This macro has not been currently implemented. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                           getpid() 
    
    
DESCRIPTION      
    
    This function exists to allow macros to be written which
    need to generate unique filenames. The process ID can be
    embedded in temporary filenames to  avoid  clashes  with
    any other users running CRISP. 
    
    
EXAMPLES      
    
    The  following  example  generates a filename for a temp
    file in the /tmp directory. 
    
    
    	string	filename; 
    	sprintf(filename, "/tmp/cr.xx%05d", getpid()); 
    
    
RETURN VALUE     
    Returns  the   current   process  ID  (as  returned  via
    getpid()). 
    
    
                    global var1, var2, ..; 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
DESCRIPTION      
    
    The global macro is used to make  local  variables  into
    global variables. Local variables are destroyed when the
    macro  executing  them  terminates.   Global   variables
    maintain  their value across macro invocation and occupy
    permanent static storage. 
    
    A variable must have been specified in a  previous  int,
    string,  list,  float or declare statement before it can
    be made into a global. 
    
    THIS PRIMITIVE IS AN INTERNAL PRIMITIVE AND  SHOULD  NOT
    BE  USED  BY  USERS  WHO  WRITE  MACROS USING THE CRUNCH
    LANGUAGE. THIS IS HANDLED AUTOMATICALLY FOR YOU  BY  THE
    COMPILER. 
      goto_bookmark([book_no], [bufnum], [line], [col]) 
    
    
DESCRIPTION      
    
    book_no  is  an integer; bufnum, line & col are optional
    names of integer variables. 
    
    This macro is used to move the cursor  to  a  previously
    saved  bookmark.  If  bufnum, line & col are all NULL or
    omitted,  then   the   buffer   and  cursor  information
    associated with book_no are selected. 
    
    If any of bufnum, line or col are specified, then  these
    variables  are  modified  to   have   that   information
    associated with the designated bookmark. 
    
    If  book_no  is  omitted, then the user will be prompted
    for the bookmark number to go to. 
    
    
EXAMPLES      
    
    The following  example  gets  the  buffer,  line  &  col
    associated with bookmark 5. 
    
    	int	buf, line, col; 
    	 
    	goto_bookmark(5, buf, line, col); 
    
    
    The following example jumps to bookmark 5: 
    
    
    	goto_bookmark(5); 
    
    
    
SEE ALSO     
    bookmark_list(), delete_bookmark(), drop_bookmark() 
    
RETURN VALUE     
    
    1  if  macro  was  successful;  0 if bookmark invalid or
    prompt was aborted. 
    
    
                     getwd(ignored, dir) 
    
    
DESCRIPTION      
    
    This function  returns  the  current  directory  in  the
    string  variable  dir.  The ignored parameter exists for
    compatability with BRIEF which allows the calling  macro
    to  specify  the  drive for the directory. Unix does not
    support the concept of multiple current directories, and
    so is ignored. 
    
RETURN VALUE     
    
    Returns 1. 
    
    
                      goto_line([line]) 
    
    
DESCRIPTION      
    
    Moves the cursor to the beginning of the specified line.
    If line is omitted it is prompted for. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                    goto_old_line([line]) 
    
    
DESCRIPTION      
    
    When a  file  is  read  into  a  buffer,  each  line  is
    internally  numbered.  These  internal  line numbers are
    maintained even if lines are inserted and  deleted  from
    the buffer. goto_old_line() moves the cursor to the line
    whose  original  line  number  was  line,  or as near as
    possible if the original lines have been deleted. 
    
    This macro gets over the problem  of  editing  a  source
    file  to  correct compilation errors, and the lines with
    errors moving as text is inserted or deleted. 
    
    If line is omitted, it is prompted for. 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
          if (expr) true-clause [else false-clause] 
    
    
DESCRIPTION      
    
    The  expression  'expr'  is  evaluated,  and  if  it  is
    non-zero (true)  or  is  a  non-null  string,  then  the
    true-clause  statements are evaluated. Otherwise, if the
    false-clause is specified, then it is evaluated. 
                index(search-string, pattern) 
    
    
DESCRIPTION      
    
    This function  is  used  to  see  whether  search-string
    contains  the  substring  pattern.  A  literal substring
    match is performed. This function returns the  place  in
    search-string  where pattern has been located or 0 if it
    does not occur in the search-string. 
    
    If the user needs to  search  for  regular  expressions,
    then the function search_string should be used instead. 
    
    
EXAMPLES      
    
    The  following  example  checks  to see if a string is a
    lower case alphabetic character: 
    
    	string	letter; 
    	 
    	if (index("abcdefghijklmnopqrstuvwxyz", letter) == 0)  
    		message("%c is upper case.", letter); 
    	else 
    		message("%c is lower case.", letter); 
    
    
RETURN VALUE     
    
    Returns 0 if pattern cannot be found  in  search-string;
    otherwise  returns  the  position  pattern  starts at in
    search-string. 
    
    
                    input_mode(char, flag) 
    
    
DESCRIPTION      
    
    This macro is used to  control  the  effect  of  certain
    'system' characters when they are typed in, specifically
    Ctrl-S (0x13), Ctrl-Q (0x11) and Ctrl-Z (0x1a). Normally
    CRISP does not see these characters and they perform the
    actions of XON/XOFF and the Job control stop. 
    
    On  serial  terminals  it  is  important  to enable flow
    control because the terminal may not be able to keep  up
    with CRISP when it is redrawing the screen. 
    
    Some  people  want  to  use these characters as keys for
    macro assignments. Therefore this macro exists to  allow
    users  to turn on and off these characters, and thus let
    CRISP see them. 
    
    char should be set to the ASCII value of  the  character
    to be changed. Flag should be set to TRUE to allow CRISP
    to  see  the  character  or to zero to let the operating
    system take its normal action. 
    
    Note, setting either of Ctrl-S and Ctrl-Q causes both to
    be set together. 
    
    Setting  Ctrl-Z  is  only  meaningful  on  systems  that
    support Job control. 
    
    Note that this primitive is  only  operational  on  Unix
    systems that support the TERMIO feature. 
    
RETURN VALUE     
    
    Returns  1  if  character   previously   enabled;   zero
    otherwise. 
    
    
                inq_assignment(key, [convert]) 
    
    
DESCRIPTION      
    
    This  macro  can  be  used  to  find  out  what  macro a
    particular keyboard character  is  assigned  to,  or  to
    which key or keys a particular macro is assigned to. 
    
    key  maybe  a  string  denoting  the  key sequence to be
    decoded or an  integer  representing  the  internal  key
    code.  If  key is a string then it should be of the form
    described under assign_to_key(). 
    
    convert is an integer expression; if  omitted  or  zero,
    then  key is treated as a keyboard character (as defined
    for assign_to_key()), and the name of the macro assigned
    to that keystroke is returned. If the character  is  not
    assigned  to a macro, and the character is inserted into
    the buffer when  the  user  hits  it,  then  the  string
    "self_insert" is returned. If there is no key assignment
    for that key, then "nothing" is returned. 
    
    If  convert  is specified and is non-zero, then 'key' is
    taken as the name of a macro and the  keys  assigned  to
    invoke  this  macro  are  returned.  The  key assignment
    returned is returned using the portable key  definitions
    defined for "assign_to_key". 
    
    If  more  than one key stroke is assigned the same macro
    invocation, then the returned string  will  contain  the
    string "<-also>" separating the key sequences. 
    
    
EXAMPLES      
    The following example displays the message '<Alt-H>': 
    
    	message("%s", inq_assignment("help")); 
    
    
RETURN VALUE     
    
    Returns  the  name of a macro assigned to a keystroke or
    the name of a keystroke assigned to a macro. 
    
    
                        inq_borders() 
    
    
DESCRIPTION      
    
    Not currently implemented. 
    
RETURN VALUE     
    
    Returns zero if borders are off; non-zero if borders are
    on. 
    
    
                      inq_brief_level() 
    
    
DESCRIPTION      
    
    This function exists for compatability with BRIEF.  This
    macro  is  supposed  to  return  the level of nesting of
    sub-shells running BRIEF/CRISP.  
    
RETURN VALUE     
    
    Returns zero if this is a  top  level  CRISP;  otherwise
    returns 2, 3, 4, ... to indicate level of nesting. 
    
    
                    inq_buffer([filename]) 
    
    
DESCRIPTION      
    
    Every  buffer  has  an  identifier  (an  integer  value)
    associated with it. These identifiers are allocated when
    the buffer is created. inq_buffer() can be used  to  get
    the  identifier for the current buffer, e.g. when saving
    the current buffer in a macro, so that after  the  macro
    has  finished  the buffer selected on entry to the macro
    can be re-instated. 
    
    If filename is specified  then  the  buffer  id  of  the
    buffer which has the file loaded is returned instead. 
    
    
EXAMPLES      
    
    The  following  example  is typical of the code sequence
    used in the CRISP macros  on  entry  and  exit  to  each
    macro. 
    
    	int	curbuf; 
    	 
    	curbuf = inq_buffer(); 
    	 . 
    	 . 
    	set_buffer(curbuf); 
    
    
RETURN VALUE     
    
    Returns  the  buffer  ID  of  the  current buffer or the
    buffer which has filename loaded into it.  Returns  zero
    if no buffer has the filename loaded. 
    
    
                  inq_buffer_flags([bufnum]) 
    
    
DESCRIPTION      
    
    This  macro returns the flags associated with the status
    of the current buffer (if  bufnum  is  omitted)  or  the
    buffer whose identifier is bufnum. 
    
    The  flags returned are a set of bits with the following
    bits being defined: 
    
    0x01 Buffer has  been  modified.  0x02  Buffer  will  be
    backed  up  when written. 0x04 Buffer is read-only. 0x08
    Reserved. 0x10 File permissions in underlying  file  has
    the  'x'  (execute  bit)  set. 0x20 Buffer has a process
    associated with it. 0x40 Buffer contains a binary  file.
    0x80  Buffer  in  ANSI  mode.  0x100 Buffer inserts real
    tabs. 0x200 Buffer is a system buffer.  0x400  Make  all
    characters  in window visible. 0x800 Dont save undo info
    for buffer. 
    
    
RETURN VALUE     
    
    Flags associated with designated buffer, or  -1  if  the
    designated buffer does not exist. 
    
    
                         inq_called() 
    
    
DESCRIPTION      
    
    This  macro  exists  so that macros can be written which
    need to differentiate between being called directly from
    the keyboard, or being called from another macro. 
    
    This is especially useful  when  writing  a  replacement
    macro. 
    
RETURN VALUE     
    
    A  string  containing the name of the macro which called
    the current macro, or "" if the macro  was  called  from
    the keyboard. 
    
    
                    inq_char_map([win_id]) 
    
    
DESCRIPTION      
    
    If  win_id  is  specified, then that character map ID of
    the underlying buffer  is  returned  (if  it  has  one),
    otherwise  the  ID associated with the specified window.
    If win_id is not specified the current window is used. 
    
    This function is used to get the character  map  as  the
    user perceives a buffer through a window. 
    
SEE ALSO     
    create_char_map(), set_buffer_cmap(), set_window_cmap().
    
RETURN VALUE     
    
    Returns  the  character  map  ID  used  to  display  the
    current. 
    
    
                         inq_clock() 
    
    
RETURN VALUE     
    
    Returns the amount of CPU time used by CRISP  since  the
    first call to inq_clock(), measured in microseconds. 
    
    
                        inq_cmd_line() 
    
    
DESCRIPTION      
    
    This macro returns the partially typed in text which the
    user is typing on the prompt line. It is used by various
    macros to perform command completion. 
    
RETURN VALUE     
    
    Returns  the  field  currently being typed in by user on
    the prompt line. 
    
    
                        inq_command() 
    
    
DESCRIPTION      
    
    This macro can be used to find  the  name  of  the  last
    macro which was invoked by virtue of it being bound to a
    keyboard key. 
    
RETURN VALUE     
    
    A string containing the name of the last macro called by
    the user. 
    
    
                    inq_environment(name) 
    
    
DESCRIPTION      
    
    THIS  FUNCTION  IS  PROVIDED  FOR  COMPATABILITY VIA THE
    brief.cr MACRO FILE. 
    
    This function looks up 'name'  in  the  environment  and
    returns  the  value  of  name.  It  is  similar to the C
    function getenv(). 
    
RETURN VALUE     
    
    Returns a string which is  the  contents  of  the  named
    environment variable, or the null string if the variable
    does not exist. 
    
SEE ALSO     
    getenv() 
                      inq_idle_default() 
    
    
DESCRIPTION      
    
    This function returns the interval for the idle keyboard
    interval  timer.  The  idle keyboard interval timer is a
    timer which is started after the last keystroke.  If  no
    keys  are  hit  for  inq_idle_default() seconds then the
    type 4 registered macros are called. 
    
    The default idle timer is set by the '-i'  command  line
    switch. If it is not set on the command line explicitly,
    then CRISP uses a default value of 60 seconds. 
    
RETURN VALUE     
    
    Returns  the  value  of the idle keyboard interval timer
    (in seconds). 
    
    
                       inq_idle_time() 
    
    
DESCRIPTION      
    
    This function returns the number of  seconds  since  the
    last key was pressed. This macro is used by the autosave
    macros to see if it is time to save the editing buffers.
    
RETURN VALUE     
    
    Returns  the  number  of  seconds since the last key was
    pressed. 
    
    
                        inq_kbd_char() 
    
    
DESCRIPTION      
    
    This macro provides a simple way of determining  whether
    a  character  is  available to be read from the keyboard
    without actually reading it. (See read_char()). 
    
RETURN VALUE     
    
    Returns non-zero if there is a character to be read from
    the keyboard; 0 if no character is available. 
    
    
                        inq_keyboard() 
    
    
DESCRIPTION      
    
    This macro may be used to  find  out  what  the  current
    keyboard identifier is so that it may be restored later.
    
    See  keyboard_push,  keyboard_pop for further details on
    keyboard identifiers. 
    
RETURN VALUE     
    
    Returns  the  identifier  associated  with  the  current
    keyboard. 
    
    
