            inq_keystroke_macro([km_id], [buf_id]) 
    
    
DESCRIPTION      
    
    This macro can be used to get the keycodes  typed  as  a
    result of a keyboard macro so that they can be saved and
    restored. 
    
    km_id  is  the  keyboard  macro  id  (as returned from a
    previous remember() macro). If not  specified  the  last
    keyboard macro defined will be used. 
    
    buf_id  is  an  optional integer variable which receives
    the buffer ID of a system  buffer  associated  with  the
    keyboard  macro.  This  buffer contains the macros which
    were executed during the remember process (as opposed to
    the raw keystrokes). This buffer may be  useful  as  the
    starting  point when writing your own customised macros.
    Consult the remember.cr  macro  file  to  see  how  this
    buffer can be saved. 
    
    
SEE ALSO     
    playback(), remember(), load_keystroke_macro() 
    
RETURN VALUE     
    
    String containing characters (in int_to_key() format) of
    characters making up a keyboard macro. 
    
    
                  inq_line_length([bufnum]) 
    
    
DESCRIPTION      
    
    This  command  is used returns the length of the longest
    line in the specified buffer (or the current  buffer  if
    bufnum is omitted). The length corresponds to the column
    position the cursor would be in if the cursor were to be
    placed  at  the  end  of the longest line, i.e. it takes
    into account any embedded tabs and  control  characters,
    etc. 
    
    If  the designated buffer has a marked region, then only
    those lines within the marked region are  looked  at  to
    find the longest line. 
    
    
    
EXAMPLES      
    
    The  following example returns the length of the longest
    line in the current buffer in between the  current  line
    and the end of the buffer. 
    
    	# include "crisp.h" 
    	 
    	 . 
    	 . 
    	int	length; 
    	 
    	drop_anchor(MK_LINE); 
    	save_position(); 
    	length = inq_line_length(); 
    	restore_position(); 
    	raise_anchor(); 
    	message("Longest line = %d cols", length); 
    
    
RETURN VALUE     
    
    inq_line_length()  returns  the  length  of  the longest
    line, or -1 if the specified buffer does not exist. 
    
    
                     inq_lines([bufnum]) 
    
    
DESCRIPTION      
    
    This macro returns the  number  of  lines  in  specified
    buffer. It is faster than going to the end of the buffer
    and doing an inq_position(). 
    
    
EXAMPLES      
    
    Following example prints number of lines in buffer: 
    
    
    	message("Lines = %d", inq_lines()); 
    
    
RETURN VALUE     
    
    Number of lines in the specified buffer - or the current
    buffer  if bufnum is not specified. Returns -1 if buffer
    does not exist. 
    
    
                     inq_local_keyboard() 
    
    
DESCRIPTION      
    
    This function returns  the  identifier  of  the  current
    local  keyboard;  this  may be needed for example if the
    keyboard is to be changed or deleted. 
    
    Refer  to  use_local_keyboard()  and  the  help  section
    "Local Keyboards" for more information on what  a  local
    keyboard is. 
    
RETURN VALUE     
    
    The  keyboard  identifier  associated  with  the current
    local keyboard, or 0 if there is no local keyboard. 
    
    
                       inq_macro(macro) 
    
    
DESCRIPTION      
    
    This macro allows the calling macro to see if the  named
    macro is defined. macro is a string expression. 
    
    Passing the name of a CRISP builtin will return 0 unless
    the built-in has been redefined by a replacement macro. 
    
RETURN VALUE     
    
    Non-zero if macro is a macro; zero otherwise. 
    
    
                       inq_mark_size() 
    
    
DESCRIPTION      
    
    This  macro  can be used to find out how many characters
    are in the currently marked region. This number  is  the
    string  length  of  a string which would be necessary to
    hold the characters. 
    
RETURN VALUE     
    
    The number of characters in the currently marked region.
    
    
    inq_marked([start_line],   [start_col],      [end_line],
                          [end_col]) 
    
    
DESCRIPTION      
    
    start_line,  start_col,  end_line,   and   end_col   are
    optional  integer  variables which receive the start and
    end positions of the current region. 
    
RETURN VALUE     
    
    Returns  0  if  buffer  does  not  have  a  region  set;
    otherwise returns current region type. 
    
    
                        inq_message() 
    
    
DESCRIPTION      
    
    This macro  returns  any  message  or  prompt  which  is
    currently  displayed  on  the status line. It is used by
    the various command completion and  abbreviation  macros
    to see what command is currently executing. 
    
    See also inq_cmd_line(). 
    
RETURN VALUE     
    
    Returns  the  message  currently on the status line plus
    any type in from the user. 
    
    
                          inq_mode() 
    
    
DESCRIPTION      
    
    This  macro   returns   the   current   state   of   the
    insert/overtype modes. 
    
RETURN VALUE     
    
    Returns 1 if in insert mode; 0 if in overtype mode. 
    
    
                    inq_modified([bufnum]) 
    
    
DESCRIPTION      
    
    This  macro  returns  a  value  indicating  whether  the
    current buffer (bufnum omitted) or the buffer  specified
    by bufnum has been modified. 
    
    This  macro  exists  as  a   shorthand   form   of   the
    inq_buffer_flags()  macro.  It  exists for compatability
    with BRIEF. 
    
    
EXAMPLES      
    
    The following example prints a  message  saying  whether
    the buffer has been modified or not. 
    
    	message("Buffer has %sbeen modified.", 
    		inq_modified() ? "" : "not "); 
    
    
RETURN VALUE     
    
    Returns  non-zero if current buffer has been modified; 0
    if buffer has not been modified  (or  has  been  written
    away). 
    
    
                       inq_msg_level() 
    
    
DESCRIPTION      
    
    The  message level flag is used to specify what level of
    error and informational messages are to be printed. This
    allows things like replacement macros to  operate  in  a
    silent manner. 
    
    To  see  the  meanings of the different levels, refer to
    set_msg_level. 
    
RETURN VALUE     
    
    The current value of the message level flag (0-3). 
    
    
     inq_names([full_name], [ext], [buf_name], [buf_id]) 
    
    
DESCRIPTION      
    
    This macro is used for determining the names of the file
    and buffer associated with the current buffer. If buf_id
    is specified, then that buffer  is  used  to  fetch  the
    information rather than using the current buffer. Any of
    the  parameters  may  be omitted. All the parameters are
    the names of string variables. 
    
    full_name is the full path name of the  file  associated
    with  the  buffer,  and  is the file which is written to
    when  write_buffer()   is   called;   ext  receives  the
    extension (if any) of full_name; buf_name is  the  title
    of  the  buffer  - as displayed at the top of the window
    when the buffer is attached  (see  attach_buffer)  to  a
    window. 
    
    
EXAMPLES      
    
    The  following macro executes a file-dependent macro for
    setting up initialisations, etc. 
    
    	string	ext; 
    	 
    	inq_names(NULL, ext); 
    	execute_macro(ext + "_init"); 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                 inq_position([line], [col]) 
    
    
DESCRIPTION      
    
    This macro is used to find where the  cursor  is  within
    the current buffer. line and col are the names of string
    variables  which  receive  the  current  line and column
    number (both start at 1). 
    
    This function  returns  an  indication  of  whether  the
    cursor  is  past  the  end  of the buffer. In BRIEF, the
    cursor is allowed to wander  beyond  the  last  line  of
    physical text in the buffer, upto one full screens worth
    (usually  24  or  42  lines).  CRISP doesnt support this
    capability at present, although the cursor can be  moved
    to  one  line  beyond the last line of input. Be wary of
    this when porting macros from BRIEF to CRISP. 
    
RETURN VALUE     
    
    Returns 0 if cursor is not past end of buffer; otherwise
    it returns the number of  lines  past  the  end  of  the
    buffer. 
    
    
             inq_process_position([line], [col]) 
    
    
DESCRIPTION      
    
    This  function  is  similar  to  inq_position()  but  it
    returns the current cursor position for  the  underlying
    process.  line  &  col are optional integer variables to
    receive the line & column, respectively. 
    
    The  process  position  is  used  for  output  from  the
    process; rather  than  inserting  the  output  from  the
    process  where the users cursor is, a separate cursor is
    maintained instead. This is done because it  allows  the
    user  to  move  around  the buffer whilst the process is
    generating  output  without  the  process  output  being
    sprinkled through the buffer. 
    
    For more details of operation, look at the shell.m macro
    file. 
    
RETURN VALUE     
    
    Returns -1 if  current  buffer  is  not  attached  to  a
    process; returns 0 otherwise. 
    
    
              inq_scrap([last_newline], [type]) 
    
    
DESCRIPTION      
    
    This macro returns various internal info about the scrap
    buffer. 
    
    last_newline  is  an  optional integer variable which is
    used to indicate whether the scrap has a newline at  the
    end  of the last line of the buffer (used when inserting
    text via paste()). This is currently not implemented. 
    
    type is an integer variable which receives the  type  of
    the  marked  area  which was most recently copied to the
    scrap. 
    
RETURN VALUE     
    
    Returns the buffer identifier associated with the scrap.
    
               inq_screen_size([lines], [cols]) 
    
    
DESCRIPTION      
    
    lines  and  cols  are  optional  integer  variables.  If
    specified they receive the  current  dimensions  of  the
    physical screen. 
    
RETURN VALUE     
    
    Returns  zero  if terminal is configured as a monochrome
    screen, or non-zero if in color mode. 
    
    
                         inq_system() 
    
    
DESCRIPTION      
    
    This macro can be used by other  macros  which  need  to
    look at arbritrary buffers, e.g. buffer_list(). 
    
RETURN VALUE     
    
    Returns  non-zero  if  the  current  buffer  is a system
    buffer; returns 0 if the  current  buffer  is  a  normal
    buffer. 
    
    
    inq_top_left([topline],  [topcol],  [win_id], [csrline],
                     [csrcol], [buf_id]) 
    
    
DESCRIPTION      
    
    This macro returns information about the window  win_id,
    or the current window if win_id is not specified. 
    
    topline is the name of an integer variable receiving the
    line  number  of  the  top  line  in  the window. topcol
    receives the column position of the left  hand  side  of
    the screen. 
    
    csrline  receives  the  current  cursor  line within the
    window and csrcol receives the column  position  of  the
    cursor. 
    
    buf_id  receives the buffer ID of the buffer attached to
    the window. 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                       inq_views([buf]) 
    
    
DESCRIPTION      
    
    This macro can be used to determine if  it  is  safe  to
    delete a buffer (via delete_buffer()). 
    
RETURN VALUE     
    
    Returns  the  number of windows which have the specified
    buffer on  display.  Returns  0  if  buffer  is  not  on
    display. 
    
    
                         inq_window() 
    
    
DESCRIPTION      
    
    This macro returns the id of the current window. This is
    useful  for  macros  which  wish  to  move the cursor to
    another window but when  they  have  completed  wish  to
    restore the cursor to the original window. 
    
RETURN VALUE     
    
    An  integer  representing  the identifier of the current
    window or -1 if there is no current window. 
    
    
                    inq_window_buf([win]) 
    
    
DESCRIPTION      
    
    This macro can be used to find the buffer ID  associated
    with a window. Given the buffer ID, the actual file name
    of the buffer can then be found. 
    
RETURN VALUE     
    
    Returns the buffer ID associated with the current window
    or the window indicated by the win argument. 
    
    
                  inq_window_color([win_id]) 
    
    
DESCRIPTION      
    
    This  macro returns the background color of a window. If
    win_id is not specified then the background color of the
    current window is returned. 
    
    If the window color is set to  <  0,  then  the  default
    background color will be used. If the color is set to >=
    0 then the specified color will be used. 
    
RETURN VALUE     
    
    The  color  associated  with  the  background   of   the
    specified window. 
    
SEE ALSO     
    window_color() 
    inq_window_info([win_id],  [buf_id],  [lx],  [by], [rx],
                            [ty]) 
    
    
DESCRIPTION      
    
    This macro returns the  information  about  the  current
    window. All the parameters are optional names of integer
    variables to receive the information. 
    
    win_id receives the window id of the window. 
    
RETURN VALUE     
    
    Returns  zero  if window is tiled, or non-zero if window
    is a popup. 
    
    
          inq_window_size([lines], [cols], [right]) 
    
    
DESCRIPTION      
    
    This macro is used to determine the  dimensions  of  the
    current window. lines, cols & right are optional integer
    variables.  lines  and  cols receive the number of lines
    and columns in the current window. 
    
    right receives the amount the current buffer is  shifted
    within the window for sideways scrolling. If the current
    buffer  hasn't  been  sideways scrolled, then right will
    receive 0. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     insert(expr, [num]) 
    
    
DESCRIPTION      
    
    insert() is another means  for  inserting  text  into  a
    buffer. (The others are self_insert() and paste()). expr
    is  a string expression which is to be inserted into the
    current buffer, as if typed  by  the  user.  Backslash-n
    characters are treated as new-lines. 
    
    If  num is specified, then the string, expr, is inserted
    num times. If omitted, it defaults to 1. 
    
    If expr evaluates to an integer then the character whose
    ascii value is 'expr' is inserted into the buffer.  This
    is  a  special  feature in that inserting 0x0a inserts a
    <Line-feed>  character  (^J)  into  the  buffer  without
    ending the current line. This feature  is  used  by  the
    quote() macro. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     insert_mode([mode]) 
    
    
DESCRIPTION      
    
    This macro allows the user to set and/or get the current
    value  of  the  insert  mode. The insert mode is applied
    when the user types in text. By default CRISP  comes  in
    insert  mode,  i.e. characters typed in cause characters
    to the right of the cursor to be shifted over.  Overtype
    mode causes the character under the cursor to be deleted
    and replaced by the inserted characters. 
    
    ins_mode  is  zero if overtype mode should be turned on,
    and non-zero if insert mode should be turned on. 
    
    If ins_mode  is  omitted,  then  the  current  value  is
    toggled. 
    
    Note  that  the  insert/overtype   mode   only   affects
    self_insert() not insert() or paste(), etc. 
    
    If  the  display  terminal  is not able to change cursor
    shape, then  the  echo  status  line  will  display  the
    current  status  of the insert/overtype mode. (Note that
    it has to compete with other values on the display  line
    so  it may disappear, for example, if percentage through
    file is turned on. (See echo_line()). 
    
    
EXAMPLES      
    
    The  following   example   prints   the   state  of  the
    insert/overtype mode without changing the mode. 
    
    	int	mode; 
    	 
    	mode = insert_mode(); 
    	 
    	/* Toggle mode back to original value. */ 
    	insert_mode(); 
    	 
    	message(mode ? "Insert mode" : "Overtype mode"); 
    
    
RETURN VALUE     
    
    Returns non-zero if the previous value was insert  mode;
    returns zero if the previous value was overtype mode. 
    
    
                 insert_process(expr, [num]) 
    
    
DESCRIPTION      
    
    insert_process()  is  similar  to  insert()  except  the
    inserted text is sent to an attached process instead  of
    being  inserted  into  the  text buffer. No auto echo is
    performed - it is the calling macros  responsibility  to
    echo any input sent to the process. 
    
    If  num is specified, then the string, expr, is inserted
    num times. If omitted, it defaults to 1. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     int var1, var2, ..; 
    
    
DESCRIPTION      
    
    This macro is used to define local variables  which  are
    to  contain  only  integer values. The variables defined
    are local variables, and are destroyed  when  the  macro
    executing this declaration terminates. 
    
    Integers  are  two's  complement  integers,  32-bits  in
    length on all machines. 
                       int_to_key(key) 
    
    
DESCRIPTION      
    
    This function takes an  integer  argument,  which  is  a
    key-code,  e.g.  as returned by read_char(). The integer
    key-code is converted to a string in the canonical  form
    understood  by  assign_to_key.  This allows macros to be
    written  portably,   rather   than   returning  the  raw
    key-code. 
    
    int_to_key()  and  key_to_int()  are  inverses  of  each
    other. 
    
RETURN VALUE     
    
    Returns a string in the format of assign_to_key(). 
    
    
                       is_integer(var) 
    
    
DESCRIPTION      
    
    This macro can be used  to  test  the  data  type  of  a
    polymorphic  variable,  for  example when walking down a
    list. 
    
RETURN VALUE     
    
    Returns 1 if var is an integer variable; zero otherwise.
    
    
                        is_list(expr) 
    
    
DESCRIPTION      
    
    This macro can be used  to  test  the  data  type  of  a
    polymorphic variable. 
    
RETURN VALUE     
    
    Returns 1 if var is an list variable; zero otherwise. 
    
    
                        is_null(expr) 
    
    
DESCRIPTION      
    
    This  macro  can be used to test if a particular element
    of a list actually exists (i.e. to avoid walking off  of
    the end of a list). 
    
RETURN VALUE     
    
    Returns  1  if  var  is  contains  a  null  value;  zero
    otherwise. 
    
    
                       is_string(expr) 
    
    
DESCRIPTION      
    
    This macro can be used  to  test  the  data  type  of  a
    polymorphic variable. 
    
    
RETURN VALUE     
    
    Returns 1 if var is a string variable; zero otherwise. 
    
    
         key_list([kbd_id], [self_insert], [buf_id]) 
    
    
DESCRIPTION      
    
    This  macro is used to get a list of all key-bindings in
    a keyboard map. The macro  returns  a  list  of  strings
    where the even elements in the string are the key names,
    and the odd elements are the macro names associated with
    those keys. 
    
    Upto  two  keyboard  maps can be specified. If buf_id is
    specified, then the  local  keyboard  assigned  to  that
    buffer is used. If not specified then the local keyboard
    map of the current buffer is used. 
    
    If  kbd_id  is  specified  then that keyboard is used as
    well; otherwise the current global keyboard is used. 
    
    If self_insert is specified and is  non-zero,  then  the
    keys  for  the self-inserting keys are returned as well.
    The default is to omit them. 
    
    When scanning a local and  a  global  keyboard,  and  an
    entry  is  defined for a keycode in the local and global
    map, then only the local keyboard enrty is returned. 
    
    This macro is defined so that the help macro can display
    a list of all valid keys currently mapped  in  both  the
    current local and global keyboard maps. 
    
RETURN VALUE     
    
    Returns  a  list  containing  pairs of strings where the
    first string in each pair  is  the  key  name,  and  the
    second string is the macro assigned to that key. 
    
    
                    key_to_int(key, [raw]) 
    
    
DESCRIPTION      
    
    This  function  is  the  inverse of int_to_key. key is a
    string to be converted to an internal keycode number. If
    raw is not specified  or  is  zero,  then  the  internal
    keycode associated with the key sequence is returned. In
    this  case, key should be a valid key-sequence which can
    be passed to assign_to_key(). 
    
    If raw is specified and is non-zero, then key is  a  raw
    key  stroke,  as  entered  by  a  function  key  on  the
    keyboard. In this case, the keycode assigned to that key
    is returned. 
    
EXAMPLES      
    The following example returns the  keycode  for  the  F1
    function key. 
    
    	key_to_int("<F1>"); 
    
    
    The  following  example  returns the keycode for the key
    whose raw  key  sequence  is  that  specified.  If  this
    keycode  corresponds  to the <F1> key, then the internal
    keycode for the <F1> key will be returned: 
    
    	key_to_int("x1B[224z"); 
    
    
RETURN VALUE     
    Returns an integer representing the  internal  key  code
    assigned  to  the  specified  key sequence, or -1 if the
    sequence does not correspond to an valid key definition.
    
SEE ALSO     
    assign_to_key(), int_to_key() 
                       keyboard_flush() 
    
    
DESCRIPTION      
    
    keyboard_flush can be used to flush any pending input. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     keyboard_pop([save]) 
    
    
DESCRIPTION      
    
    This macro is used to pop the current keyboard  off  the
    keyboard  stack; save is an integer expression. If it is
    non-zero, then the current keyboard is saved  for  later
    use (by keyboard_push). If it is zero, then the keyboard
    map is discarded. 
    
    
EXAMPLES      
    
    See  keyboard_push()  for  an  example  of  creating   a
    temporary keyboard map. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                   keyboard_push([kbd_id]) 
    
    
DESCRIPTION      
    
    keyboard_push  is  used  to create a new keyboard table.
    The current keyboard map is saved on a stack, and can be
    retrieved by using keyboard_pop. 
    
    kbd_id is an integer expression. If it is omitted,  then
    a  new  keyboard  map  is  pushed  on  the stack, and by
    default  all  the  keys  in  the  map  are  assigned  to
    nothing(), i.e. pressing them has no effect.  If  kbd_id
    is  specified,  it  should be a value which was obtained
    from a previous inq_keyboard() call. This will push  the
    keyboard whose identifier is kbd_id on top of the stack.
    
    A keyboard map is a table of all possible keys, together
    with the macros that are bound to them. By default CRISP
    comes  up  with  the usual editing keys, but some macros
    need to  temporarily  bind  macros  to  keys  for  their
    operation.  For example, the buffer_list macro creates a
    new keyboard and binds various keys to it,  so  that  it
    can  intercept  the  users  requests to delete and write
    away buffers. 
    
    Having keyboard maps saves the macro writer from  having
    to  write  complicated,  and  CPU   expensive   keyboard
    parsers. 
    
    
EXAMPLES      
    
    The  following  example  shows how to create a temporary
    keyboard mapping for use within a macro. 
    
    	int	curkbd; 
    	 
    	curkbd = inq_keyboard(); 
    	 
    	keyboard_push(); 
    	assign_to_key("<Alt-H>", "help"); 
    	 .. 
    	 .. 
    	process(); 
    	keyboard_pop(); 
    	 
    	keyboard_push(curkbd); 
    
    
RETURN VALUE     
    Nothing. 
    
    
                     keyboard_typeables() 
    
    
DESCRIPTION      
    
    keyboard_typeables is a quick method  of  setting  up  a
    keyboard  map  so  that  the usual insertable characters
    (ASCII  0-127)   do   their  default  actions  of  being
    insertable. 
    
    It is a shorthand way of doing the following: 
    
    	assign_to_key("A", "self_insert"); 
    	assign_to_key("B", "self_insert"); 
    	 . 
    	 . 
    
    It is useful after creating a new blank keyboard. 
    
RETURN VALUE     
    Nothing. 
                           ldexp(x) 
    
    
RETURN VALUE     
    
    Returns x*2^n as a floating point value. 
                          left(num) 
    
    
DESCRIPTION      
    
    Moves the cursor  one  character  to  the  left  or  num
    characters  to  the  left,  if  specified.  num  may  be
    negative. 
    
    Unlike BRIEF, if the cursor is moved past the  beginning
    of the current line, then the cursor wraps around to the
    end of the previous line. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                  length_of_list(list_expr) 
    
    
RETURN VALUE     
    
    The number of atoms in the list. 
    
    
DESCRIPTION      
    
    length_of_list()  returns the number of atoms in a list;
    it only counts the top level atoms. For example, if (car
    list_expr) is a list expression itself, then  this  only
    counts   as   one   atom,   not   (length_of_list   (car
    list_expr)). 
                     list var1, var2, ..; 
    
    
DESCRIPTION      
    
    This macro  is  used  to  define  list  variables.  List
    variables  may be defined as global (see global()). List
    variables are given an initial value of  the  NULL  list
    (i.e. length_of_list() returns 0). 
    
    Lists  are  data  types  similar  to arrays, except each
    element of a list (referred to as an atom) may have  any
    of  the CRISP primitive data types (including list), and
    lists can be expanded at the end simply by concatenating
    entries on the end (see append_list() and put_nth()). 
                  load_keystroke_macro(str) 
    
    
DESCRIPTION      
    
    This macro provides a way of creating a  keyboard  macro
    without  using  the  keyboard. This macro is designed to
    allow user macros to load macros from external files. 
    
    str  is  a  string  in  a  similar  format  returned  by
    inq_keystroke_macro() which is parsed and  stored  as  a
    keystroke macro. 
    
SEE ALSO     
    playback(), remember(), inq_keystroke_macro() 
    
RETURN VALUE     
    
    Keystroke macro ID associated with the keystroke macro. 
    
    
                      load_macro([file]) 
    
    
DESCRIPTION      
    
    This  macro  is used to load a .m or .cm macro file into
    CRISP. file is a string expression which  specifies  the
    name of the macro file. If omitted, it is prompted for. 
    
    Note that unlike BRIEF, macros in source form (.m files)
    can be loaded with this macro. 
    
    The  extension can be omitted, in which case CRISP looks
    for  either  file.m  or  file.cm  If  the  extension  is
    supplied, then only a file matching the  extension  will
    be  searched  for.  Otherwise CRISP looks for a .cm file
    before looking for a .m file. 
    
    If file does not  contain  a  path  specification,  then
    CRISP  searches  all  the  directories  in   the   BPATH
    environment  variable  (or  uses  an internal default if
    BPATH is not specified). 
    
    When  searching   for  a  .m  or  .cm  it  searches  the
    directories in order, i.e. if a .cm  file  exists  in  a
    later  path  than the .m then the .m file will be loaded
    first. 
    
    When loading .cm files, CRISP checks the version  number
    of  the file to see if it is compatible with the current
    version of CRISP, and issues an  error  message  if  the
    version number does not agree. 
    
    If  a .m file has a syntax error then the loading of the
    file is aborted with an error message displayed. 
    
    If a macro called '_init' exists in the macro file being
    loaded, then that macro is  executed  immediately.  This
    facility   exists    to    allow   macros   to   perform
    initialisation functions. 
    
RETURN VALUE     
    
    Returns 1 if  macro  file  was  successfully  loaded;  0
    otherwise. 
    
    
                            log(x) 
    
    
RETURN VALUE     
    
    Returns  the  natural  logarithm  of  x,  ln(x).  x is a
    floating point value which must be > 0. 
    
SEE ALSO     
    log, exp 
                           log10(x) 
    
    
RETURN VALUE     
    
    Returns the base-10 logarithm of  x,  x  is  a  floating
    point value which must be > 0. 
    
SEE ALSO     
    log10, exp 
                        lower(string) 
    
    
SEE ALSO     
    upper 
    
RETURN VALUE     
    
    Returns  a  copy  of  string with all upper case letters
    mapped to their lower case equivalents. 
                        ltrim(string) 
    
    
DESCRIPTION      
    
    This function is used to remove leading characters  from
    the specified string. The default is to remove all tabs,
    spaces  and  newline  characters. If delim is specified,
    then all characters in the delim string are removed from
    the beginning of string. 
    
    
SEE ALSO     
    trim, compress 
    
RETURN VALUE     
    
    Returns a copy of string with all  leading  white  space
    characters removed. (spaces, tabs and newlines). 
    
    
                      (macro name list) 
    
    
RETURN VALUE     
    
    Result of last statement executed in the macro. 
    
    
DESCRIPTION      
    
    (macro)  defines  a  new  macro.  It  is  normally  only
    processed when loading a .m or .cm file.  The  macro  is
    given  the  name  'name'  and consists of the executable
    statements in the list, list. 
    
    If a macro is given the special name _init, then  it  is
    automatically executed when the macro file is loaded. 
    
    THIS  IS  A  LOW  LEVEL  PRIMITIVE  NOT AVAILABLE IN THE
    CRUNCH  LANGUAGE.   THE  CRUNCH  COMPILER  AUTOMATICALLY
    PRODUCES  MACRO  DEFINITIONS  FOR  EACH  DEFINED  CRUNCH
    FUNCTION. 
                         macro_list() 
    
    
DESCRIPTION      
    
    This macro  is  similar  to  command_list()  but  simply
    returns a list of all the currently defined macros. 
    
RETURN VALUE     
    
    A  list of strings containing the names of all currently
    defined  macros  (not  CRISP  keywords),  in  alphabetic
    order. 
    
    
                 make_list(expr1, expr2, ..) 
    
    
DESCRIPTION      
    
    This macro is used to create a new list constructed from
    the  argument  list.  Each  argument  is  evaluated  and
    appended  to   the   next   list.   Contrast  this  with
    quote_list() which does not evaluate the arguments. 
    
    
EXAMPLE      
    
    	int i = 4, j = 5;  
    	list l = make_list(i, j); 
    
    	/* l = {4 5} */ 
    
    
SEE ALSO     
    quote_list() 
    
RETURN VALUE     
    
    List constructed from arguments. 
    
    
             make_local_variable(var1, var2, ..) 
    
    
DESCRIPTION      
    
    This macro is used to make existing local variables into
    buffer local variables. CRISP supports the  concepts  of
    three  storage  classes  for variables - local, which go
    out of scope when the current macro terminates;  global,
    which  never go out of scope; and buffer-local, which go
    out of scope when the current buffer is changed. 
    
    Buffer-local  variables  are  useful  for  saving  state
    information on a per buffer basis. 
    
    When searching for a variable, CRISP searches the symbol
    tables in the following order: 
    
    1. Local  variables.  2.  Global  variables.  3.  Buffer
    variables. 
    
    Therefore  be  careful  when  overloading  symbol names.
    CRISP  allows  local  variables,  global  variables  and
    buffer variables to all be in scope at  once,  in  which
    case the variable at the highest level in the above list
    is only accessible. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                         mark([type]) 
    
    
DESCRIPTION      
    
    mark()  is similar to raise_anchor()/drop_anchor(). If a
    marked region is currently displayed, then mark() raises
    the anchor; if no anchor is displayed, then mark() drops
    an anchor. 
    
    type is an optional integer variable which  is  used  to
    define  the  mark type if one is to be dropped. If it is
    omitted, it defaults to a normal marked region. 
    
    See drop_anchor() for a description of the marked region
    types. 
    
RETURN VALUE     
    
    Nothing. 
    
    
               message(fmt, [arg1], [arg2], ..) 
    
    
DESCRIPTION      
    
    This macro is used to display a message  on  the  status
    prompt()  line  at  the  bottom  of the screen. fmt is a
    string  and   may   contain   printf-like  %  formatting
    characters.  arg1,   arg2,  ..  are  integer  or  string
    expressions used to satisfy the  %  formatting  options.
    Upto 6 arguments are allowed. 
    
    This macro can be used to display informational messages
    on the bottom of the screen; if error messages are to be
    displayed then the error() macro should be used instead.
    
    The following format identifiers are supported: 
    
    |==========|========================================|
    |Format    |Description                             |
    |==========|========================================|
    |%d        |Print  an integer expression. Options   |
    |          |such as %03d can be used  to  perform   |
    |          |zero  insertion  and  supply  a field   |
    |          |width.                                  |
    |__________|________________________________________|
    |%x        |Print integer expression in hex.        |
    |__________|________________________________________|
    |%o        |Print integer expression in octal.      |
    |__________|________________________________________|
    |%s        |Print  a   string.  Field  width  and   |
    |          |alignments are allowed.                 |
    |__________|________________________________________|
    |%c        |Print a character.                      |
    |__________|________________________________________|
    |%p        |If its less than a second  since  the   |
    |          |last  call  to  message (or printf or   |
    |          |error),  then   don't   display   the   |
    |          |message. This is used by macros which   |
    |          |want to print progress messages.        |
    |==========|========================================|
    The following prefixes are supported: 
    
    |==========|========================================|
    |Prefix    |Description                             |
    |==========|========================================|
    |%l...     |User long format for  printing,  e.g.   |
    |          |floats   are    printed   with   full   |
    |          |double-precision.                       |
    |__________|________________________________________|
    |%-..      |Value is printed left justified.        |
    |==========|========================================|
    
EXAMPLES      
    
    	message("The %s %s %s %s %s.", 
    	        "cat", "sat", "on", "the", "mat"); 
    	message("%pMacro  completed:   %d%%",  (val  *  100)  /
    total); 
    
    
RETURN VALUE     
    
    Nothing. 
                     mkdir(path, [mode]) 
    
Description      
    This function creates a new diretory. The path specified
    should be a string variable and is  passed  directly  to
    the mkdir(2) operating system call. 
    
    mode  is  the  protection  codes  used  to  create   the
    directory.  If  omitted, the value 0755 (rwxr-xr-x) will
    be used. 
    
RETURN VALUE     
    On success, zero is returned. Otherwise -1  is  returned
    and  the  global variable errno is set to the reason why
    the call failed. (Refer to the system  manual  page  for
    the error codes). 
                         modf(x, ip) 
    
    
RETURN VALUE     
    
    Returns  integer  part  of x as a floating point number,
    and stores the fractional part  of  x  in  the  floating
    point  variable  ip. Both the return value and the value
    stored in ip have the same sign as x. 
                   move_abs([line], [col]) 
    
    
DESCRIPTION      
    
    This macro moves the cursor to the  specified  line  and
    column  position.  If either line or col are unspecified
    or zero, then  the  line  or  column  position  is  left
    unchanged. 
    
RETURN VALUE     
    
    Returns  non-zero  if  cursor  moved; 0 if cursor didn't
    move. 
    
    
               move_edge([direction], [amount]) 
    
    
DESCRIPTION      
    
    This macro is used  to  expand  or  contract  a  window.
    direction  specifies  the edge which is to be moved. The
    expansion is  performed  interactively.  This  macro  is
    designed to support tiled windows. 
    
    If  direction  is  specified,  it should have one of the
    following values: 
    
    	0 Up  
    	1 Right  
    	2 Down  
    	3 Left 
    
    
    Amount  is   an  optional  integer  expression.  If  not
    specified, the user will be prompted to  move  the  edge
    with the arrow keys. If it is specified it specifies the
    number  or  characters  or lines to move the window. The
    number is relative to the top left  of  the  screen,  so
    positive  numbers move further away and negative numbers
    move nearer. 
    
RETURN VALUE     
    
    Returns <= 0 if unsuccessful; > 0 otherwise. 
    
    
                   move_rel([line], [col]) 
    
    
DESCRIPTION      
    
    This macro moves the current  line  or  column  plus  or
    minus  the  number  of lines specified, i.e. the move is
    relative to the current cursor position. 
    
    
RETURN VALUE     
    
    Returns non-zero if cursor moved;  0  if  cursor  didn't
    move. 
    
    
                next_buffer([system], [prev]) 
    
    
DESCRIPTION      
    
    next_buffer()  is  the  mechanism  for  enumerating  all
    buffers. It returns the buffer id of the next buffer  in
    the list. 
    
    system  is  an  optional  integer  which  if present and
    non-zero allows the calling macro to walk  through  each
    system  buffer  as  well  (see  create_buffer). If it is
    omitted, then system  buffers  are  stepped  over.  This
    facility  is  used  by  the  buffer_list()  macro if the
    systems option is turned on. 
    
    If prev is specified and  non-zero,  then  the  previous
    buffer can be found. 
    
    
EXAMPLES      
    
    The  following  example  shows  how  to  walk  down each
    buffer, including system buffers: 
    
    	int	curbuf, buf; 
    	 
    	curbuf = inq_buffer(); 
    	buf = curbuf + 1; 
    	while (curbuf != buf) { 
    		... 
    		buf = next_buffer(1); 
    		} 
    
    
RETURN VALUE     
    
    Returns the buffer id of the next buffer in  the  buffer
    list. 
    
    
                       next_char([num]) 
    
    
DESCRIPTION      
    
    This  function is similar to right() except it moves the
    cursor over physical characters, e.g. tabs  are  treated
    as single characters, rather than virtual spaces. 
    
    If  num  is  specified  then  that  number  of character
    positions are skipped over. 
    
    If the cursor is moved past the end of  the  line,  then
    the cursor wraps around to the start of the next line. 
    
    When  skipping  characters  for text files, the implicit
    newline at the end of  each  line  is  included  in  the
    count.  When  skipping  over characters in binary files,
    the end of line is not treated as a character.  Thus  to
    go  to an absolute offset in a binary file, it is merely
    necessary to go to the top of the buffer and  perform  a
    next_char() function the appropriate number of times. 
    
RETURN VALUE     
    
    Returns non-zero if the cursor changed position; zero if
    it didn't. 
    
    
                    next_window([win_id]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to move to the 'next' window. The
    definition of next is related to the order  the  windows
    appear  in  the screen. Windows internally are sorted in
    top-left to bottom-right order. This  primitive  changes
    window and sets the current buffer up appropriately. 
    
    If  win_id  is  specified  then the next window from the
    specified window is returned. 
    
RETURN VALUE     
    
    New window ID or -1 if window cannot be found. 
    
    
                          nothing() 
    
    
DESCRIPTION      
    
    This macro is a no-op.  It  exists  simply  as  a  place
    holder  for the language and is valid anywhere any other
    macro is valid. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                     nth(expr, list_expr) 
    
    
DESCRIPTION      
    
    This macro allows the caller to extract individual atoms
    from a list. The first element of a list is  element  0;
    the  nth() macro allows lists to be treated like arrays.
    The last element of a list is length_of_list()-1. 
    
    nth is a more efficient way of accessing random elements
    in a list, than for  example,  using  car()  and  cdr(),
    since  the  list expression doesn't need to be copied so
    much. 
    
    This primitive is not normally accessed from the  CRUNCH
    language.  When the user uses array subscripts to access
    a list, CRUNCH converts the  subscripts  into  calls  to
    this macro. 
    
RETURN VALUE     
    
    Returns the n'th atom in list_expr, where n is the value
    of the integer expression expr. 
    
    
                   output_file([filename]) 
    
    
DESCRIPTION      
    
    This  macro  is  used  to change the filename associated
    with  the   current  buffer.  By  default  the  filename
    associated with  the  current  buffer  is  the  filename
    specified  on  an  edit_file()  or create_buffer() call.
    output_file() allows this to be changed to the value  of
    the string expression, filename. 
    
    If  filename  is  omitted, then the user is prompted for
    the new file name. 
    
    
RETURN VALUE     
    
    Returns <= 0 on an error, or > 0 on success. 
    
    
                         page_down() 
    
    
DESCRIPTION      
    
    Moves the cursor one window-full towards the end of  the
    buffer. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                          page_up() 
    
    
DESCRIPTION      
    
    Moves  the  cursor one window-full towards the beginning
    of the buffer. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                           paste() 
    
    
DESCRIPTION      
    
    This macro copies the contents of the scrap  buffer  and
    inserts  it  into the current buffer where the cursor is
    located. The cursor is moved to the end  of  the  pasted
    region. 
    
    When  using CRISP on a windowing system (e.g. X11), this
    key should be bound to the <Ins> key. When a mouse paste
    operation is performed, CRISP  checks  to  see  if  this
    macro  is  bound  to  the  <Ins> key and if not will not
    paste the selection. This is done to avoid allowing  the
    user to paste data with the mouse into a popup window. 
    
RETURN VALUE     
    
    Returns 1 on success; 0 on failure. 
    
SEE ALSO     
    cut(), copy(), inq_scrap(), set_scrap_info(). 
                           pause() 
    
    
DESCRIPTION      
    
    pause()  is  used  to pause a keyboard macro definition.
    Usually all keyboard input  typed  during  a  remember()
    sequence is saved in the keyboard macro buffer. Pressing
    a key assigned to pause() causes the remember() sequence
    to suspend saving the characters. 
    
RETURN VALUE     
    
    Nothing. 
    
    
                   pause_on_error([pause]) 
    
    
DESCRIPTION      
    
    This  macro  is used to set or toggle the pause on error
    flag. This flag is tested after every error() message is
    displayed. If this flag is on then the error message  is
    displayed  with  a  '..'  suffix added to the end of the
    error message and CRISP waits for the user to  type  any
    key on the keyboard to continue. This allows the user to
    see  error messages before they get overwritten by other
    messages. 
    
    By default this is off. If  pause_on_error()  is  called
    with  no argument, then the current state is toggled and
    CRISP  prints   the  message  'Pausing  errors  on.'  or
    'Pausing errors off.' If pause  is  specified  then  the
    current  setting  is  set  to  the  value of the integer
    expression pause. 
    
    
EXAMPLES      
    
    The following example shows how pause_on_error() can  be
    used  around  a call to a macro so that the user can see
    the  errors   being   displayed  by  the  macro  without
    resorting to sight-reading. 
    
    	pause_on_error(); 
    	fred(); 
    	pause_on_error(); 
    
    
RETURN VALUE     
    
    Non-zero if previous setting was paused messages  on;  0
    is previous setting was no pausing of error messages. 
    
    
                      playback([macro]) 
    
    
DESCRIPTION      
    
    playback()  causes  the  saved  keyboard  macro  to   be
    replayed. If macro is not specified, then the last macro
    defined is played back. 
    
    playback()  is  not  usually called from within a macro,
    but instead is usually bound to the <F8> key. 
    
RETURN VALUE     
    
    Returns greater than or equal to zero  if  playback  was
    successful. Less than zero otherwise. 
    
    
                         (post++ var) 
    
    
DESCRIPTION      
    
    This  macro  is used to access a variable and perform an
    auto increment on the variable AFTER its value has  been
    used (c.f. (++)). 
    
    THIS  PRIMITIVE  IS  NOT  DIRECTLY  ACCESSIBLE  FROM THE
    CRUNCH LANGUAGE AND IS USED WHEN COMPILING  THE  POSTFIX
    INCREMENT OPERATOR (x++). 
    
RETURN VALUE     
    
    Returns the value of the variable var. 
    
    
                         (post-- var) 
    
    
DESCRIPTION      
    
    This  macro  is used to access a variable and perform an
    auto decrement on the variable AFTER its value has  been
    used (c.f. (--)). 
    
    THIS  PRIMITIVE  IS  NOT  DIRECTLY  ACCESSIBLE  FROM THE
    CRUNCH LANGUAGE AND IS USED WHEN COMPILING  THE  POSTFIX
    DECREMENT OPERATOR (x--). 
    
RETURN VALUE     
    Returns the value of the variable var. 
    
    
                          pow(x, y) 
    
    
RETURN VALUE     
    
    Returns  x  to the power of y (x^y). x, y and the return
    value are floating point values. 
                       prev_char([num]) 
    
    
DESCRIPTION      
    
    Moves  the  cursor  backwards  by  num  characters.  The
    movement is by physical characters, and treats tabs, etc
    as single characters. 
    
    If the cursor is  moved  beyond  the  beginning  of  the
    current  line then the cursor wraps around to the end of
    the previous line. 
    
    When skipping characters for text  files,  the  implicit
    newline  at  the  end  of  each  line is included in the
    count. When skipping over characters  in  binary  files,
    the  end  of line is not treated as a character. Thus to
    go to an absolute offset in a binary file, it is  merely
    necessary  to  go to the top of the buffer and perform a
    next_char() function the appropriate number of times. 
    
RETURN VALUE     
    
    Nothing 
    
    
                           print() 
    
    
DESCRIPTION      
    
    This macro is used to send the currently  marked  region
    to  the printer. The internal primitive is defined to do
    nothing. At the user interface level, the print macro is
    assigned to  a  macro  which  will  send  the  currently
    hilighted  region to the printer or the entire buffer if
    no region is hilighted. 
    
    Because there is no  standard  printer  mechanism  under
    Unix,  the  user  is  prompted for the command to use to
    print the region. Please consult the user guide for more
    information (the section on .crinit configuration). 
    
    
RETURN VALUE     
    
    Nothing. 
    
    
                printf(fmt, [arg1], [arg2] ..) 
    
    
DESCRIPTION      
    
    This macro can be used for  debugging  macros,  although
    its  use  is  questionable.  It exists for compatability
    reasons with BRIEF. It causes the formatted string to be
    sent  directly   to  stdout,  bypassing  all  of  CRISPs
    internal screen manipulations. 
    
    Its use is questionable since it is presumably  provided
    for use with BRIEF and MS-DOS for debugging BRIEF itself
    and BRIEF macros. Under MS-DOS, BRIEF writes directly to
    the video memory and it may be useful to have a separate
    error logging channel which can be redirected to a file.
    
    Under  Unix, stdout is used for all display purposes, so
    the printf output stream would be intermingled with  the
    display stream. 
    
    If  you  need  to  track  the  progress  of a macro, use
    debug() since it gives you a much finer  granularity  of
    output. 
    
RETURN VALUE     
    
    Nothing. 
    
    
