REF POPLOG_ONLY                                  John Williams, May 1987
                                                       Updated June 1995

       COPYRIGHT University of Sussex 1995. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<       POPLOG-SPECIFIC       >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<       LISP FUNCTIONS        >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Poplog Common Lisp provides a number of extra functions, variables  etc.
that are not part of standard  Common Lisp (as defined in Steele  1990).
This file  describes these  Poplog-specific  features. All  the  symbols
documented herein are external symbols  of the poplog package (which  is
itself a Poplog-specific feature, of course). The poplog package is used
by the common-lisp-user (cl-user) package,  and hence these symbols  can
be notated  without a  package qualifier  while the  cl-user package  is
current.

Note that the features described in this file are available in the basic
Poplog  Common  Lisp  image.  In  contrast,  special  Poplog  facilities
provided via modules must be explictly loaded using require.

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Functions
  2   Variables
  3   Constants
  4   Magic Words
  5   Declaration Specifiers
  6   The *features* List
  7   Packages
  8   See Also


------------
1  Functions
------------

(bye)                                                         [function]
        Exits from Lisp top-level. See also the magic-word bye, below.


        This function performs the  standard startup actions that  occur
        when Poplog Common Lisp is first invoked. print-banner  defaults
        to nil. See HELP * SAVELISP.


(make-pop11-procedure function arity)                         [function]
        Converts function into an object  which can be passed to  Pop-11
        procedures   that    take   procedures    as   arguments.    See
        HELP * POPLISP.


(pop11)                                                       [function]
        Switches  from   Lisp   top-level to the Pop-11 top-level.   See
        HELP * POPLISP, also the magic-word pop11, below.


(pop11-val string)                                            [function]
        Invokes the Pop-11  compiler on string.  Calls to pop11-val  are
        generated by the read macro "@".


(restorelisp)                                                 [function]
        For restoring saved images. See HELP * SAVELISP.


(savelisp pathname &key :init :lock :share)                   [function]
        For creating saved images. See HELP * SAVELISP.


(setlisp)                                                     [function]
        Resets the  Lisp system,  unwinds  all active  procedure  calls,
        restores any variable bindings, etc. Invoked after fatal errors,
        or by interrupts.


------------
2  Variables
------------

*assert-places*                                               [variable]
        Bound to the places argument of the assert macro, for  reference
        during debugging. See HELP * DEBUG.


*break-on-errors*                                             [variable]
        If true, (the default), the debugger is entered after an  error,
        otherwise  control   returns   to  the   top-level   loop.   See
        HELP * MISHAP.


*break-on-interrupts*                                         [variable]
        If true, (the default), an interrupt signal causes the  debugger
        to be entered, otherwise a setlisp occurs.


*break-on-warnings*                                           [variable]
        If true, (the default), the debugger is entered after a  warning
        is issued  with warn.  Otherwise warn  returns immediately.  See
        HELP * MISHAP.


*constant-functions*                                          [variable]
        While true, all assignments to function cells will be classed as
        constant. If a function cell is constant, then the compiler  can

            (a) plant direct calls to its functional value

            (b) make use of any information it has inferred about
                the behaviour of the function.


*current-directory*                                           [variable]
        Contains (as a string) the current working directory (i.e.  what
        pwd would return under Unix, or show default would return  under
        VMS).


*debugger-condition*                                          [variable]
        This is bound by invoke-debugger  to the condition on which  the
        debugger was invoked. Outside of the debugger its value is  nil.
        See HELP * BREAK.


*default-package-size*                                        [variable]
        The default table size of packages created by defpackage when no
        explicit :size option is given. Its default value is 128.


*default-package-use-list*                                    [variable]
        Packages created by defpackage will use the packages in the list
        *default-package-use-list* unless  an explicit  :use option  was
        given in the defpackage form.  Initially this list contains  the
        common-lisp and  poplog packages.  The inclusion  of the  latter
        means that  the symbols  listed in  this file  are available  by
        default to new packages created by defpackage.


*error-print-length*                                          [variable]
        Assigned  to *print-length* by  error, cerror, and warn,  unless
        its value is the keyword :ignore, in which  case  *print-length*
        is not affected. The  default value of  *error-print-length*  is
        5. See HELP * MISHAP.


*error-print-level*                                           [variable]
        Assigned to *print-level*   by error, cerror,  and warn,  unless
        its value is the keyword  :ignore, in which  case  *print-level*
        is not affected. The default value of  *error-print-level* is 3.
        See HELP * MISHAP.


*inspect-print-length*                                        [variable]
        Assigned to *print-length*  by inspect, unless its value is  the
        keyword :ignore, in which case *print-length* is  not  affected.
        The   default  value   of  *inspect-print-length*   is  5.   See
        HELP * INSPECT.


*inspect-print-level*                                         [variable]
        Assigned to  *print-level* by inspect,  unless its value is  the
        keyword :ignore, in which  case  *print-level* is not  affected.
        The   default   value  of   *inspect-print-level*  is   3.   See
        HELP * INSPECT.


*interrupt*                                                   [variable]
        When a keyboard interrupt occurs (usually as a result of  typing
        CTRL-C), the value of this variable, which should be a  function
        of zero arguments, is applied. The initial value of  *interrupt*
        is a function  that enters  the Lisp debugger,  with a  continue
        restart available for resuming the interrupted computation.


*lisp-calling-limit*                                          [variable]
        This variable, if  an integer, specifies  the maximum number  of
        function names that should be included in the CALLING line of an
        error (or warning) message. Its default value is nil. Note  that
        CALLING lines are only printed if  the debugger is not going  to
        be invoked (i.e. if *break-on-errors* or *break-on-warnings*  is
        nil,  or  *debug-io*   is  not  an   interactive  stream).   See
        HELP * MISHAP.


*lispfiletypes*                                               [variable]
        List of file extensions that signify Common Lisp program  files;
        used by  the Poplog  editor Ved,  the load  function, and  other
        system  utilities  that  need  to  know  which  Poplog  language
        compiler  to  use  on  a  given  file.  The  initial  value   of
        *lispfiletypes* is the list:

            (".lsp" ".l" ".lisp" ".cl")

        Users may  add their  own file  extensions to  this list;  these
        should be  simple  strings  (not  pathnames),  and  include  the
        initial ".".


*load-lock*                                                   [variable]
        Used as the default for the  :lock argument to load. So, if  set
        true, (its  initial value  is nil),  the heap  will be  "locked"
        after  every  load  operation.  This  can  help  reduce  garbage
        collection time. See HELP * STOREUTILS and REF * SYSTEM.


*making-saved-image*                                          [variable]
        This variable (initially  nil) should  be set true  by the  user
        before loading code that is to  be stored in a saved image  with
        savelisp. See HELP * SAVELISP for details.


*module-directory-list*                                       [variable]
        List of directory pathnames where require should search for  the
        source code of a module. See HELP * MODULES.


*raw-terminal-io*                                             [variable]
        An input/output stream that provides raw access to the terminal.


*read-prompt*                                                 [variable]
        The prompt  string  used  by read  and  similar  functions  when
        reading interactively. User-assignable, but currently reverts to
        its initial value ("== ") after a setlisp (a bug !).


*test-form*                                                   [variable]
        Holds the place  form being tested  in various debugging  macros
        (ccase,  assert  etc),   for  reference   when  debugging.   See
        HELP * DEBUG.


*test-value*                                                  [variable]
        Bound to the value of *test-form*  by various debugging  macros,
        like ccase, assert, etc. See HELP * DEBUG.


*time-zone*                                                   [variable]
        Integer indicating current time zone, specifying number of hours
        west of GMT. Initial value is 0.


*trace-args*                                                  [variable]
        List of arguments about to be  passed to a function traced  with
        the :break option. See HELP * TRACE.


*trace-results*                                               [variable]
        List of results about to be returned from a function traced with
        the :break option. See HELP * TRACE.


*trace-print-length*                                          [variable]
        Assigned  to  *print-length*  while  arguments  and  results  of
        traced functions  are being  printed, unless  its value  is  the
        keyword :ignore, in which case  *print-length* is not  affected.
        The   default   value   of  *trace-print-length*   is   5.   See
        HELP * TRACE.


*trace-print-level*                                           [variable]
        Assigned to  *print-level* while arguments and results of traced
        functions are being  printed, unless  its value  is the  keyword
        :ignore, in  which  case *print-level*   is  not  affected.  The
        default value of *trace-print-level* is 3. See HELP * TRACE.


------------
3  Constants
------------

<termin>                                                      [constant]
        The Pop-11 end-of-file object termin.


--------------
4  Magic Words
--------------

Poplog Common Lisp recognises the following magic words:

help    topic                                               [magic-word]
im      filename                                            [magic-word]
ref     function | topic                                    [magic-word]
showlib modulename                                          [magic-word]
src     filename                                            [magic-word]
teach   topic                                               [magic-word]
ved     filename                                            [magic-word]
        These commands all invoke the editor. In each case, the argument
        is optional. If omitted,  the most recently  edited file of  the
        appropriate class will be displayed. See HELP * LISPVED.


bye                                                         [magic-word]
        Exits  the  Lisp  top-level  loop.  Equivalent  to  calling  the
        function (bye).


cd directory                                                [magic-word]
        Sets *current-directory* to directory (which should be a string,
        not a pathname). If directory is omitted, *current-directory* is
        set to the user's "home" directory. The new value is written  to
        *standard-output*.


lib  module-name                                            [magic-word]
        Searches for, and loads, the library module-name. Like require.


load filename                                               [magic-word]
        Loads filename. Equivalent to  calling the function load.  (Note
        this symbol is actually in the common-lisp package).


pop11                                                       [magic-word]
        Redirects the current  input stream to  the Pop-11 compiler. See
        HELP * POPLISP.


pwd                                                         [magic-word]
        Writes the value of *current-directory* to *standard-output*.


stop                                                        [magic-word]
        Unix only. Suspends Poplog, returning control to the shell.


-------------------------
5  Declaration Specifiers
-------------------------

Poplog Common  Lisp recognises  the following  non-standard  declaration
specifiers:

    # constant
    # optimise
    # tail-recursion

See HELP * DECLARE and HELP * OPTIMISE.


----------------------
6  The *features* List
----------------------

From Lisp version 1.5 onwards, only keyword symbols are included in the
*features* list. See HELP * FEATURES.


-----------
7  Packages
-----------

The following non-standard packages are included in Poplog Common Lisp:

    # empty
    # pop11
    # poplog

The empty package contains no symbols. It is used by apropos to fool the
printer into displaying every symbol's home package name.

Symbols interned  in the  pop11  package are  treated specially  by  the
compiler: they denote Pop-11 procedures, variables, data types, etc. See
HELP * POPLISP for more details.


-----------
8  See Also
-----------

# HELP * POPLISP

# HELP * MAGIC-WORDS

# HELP * DECLARE

# HELP * MODULES



--- C.all/lisp/ref/poplog_only
--- Copyright University of Sussex 1993. All rights reserved.
