HELP MAGIC-WORDS                                 John Williams, May 1988


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

  1   What is a Magic Word ?
  2   Built-In Magic Words
  3   The MAGIC-WORD Module
  4   The Magic-Word-Handler Hash Table
  5   Defining Magic Words
  6   Cancelling Magic Words


-----------------------------------------------------------------------
1  What is a Magic Word ?
-----------------------------------------------------------------------

Magic words are symbols that are treated specially by the interactive
top-level evaluator. When encountered as top-level forms, instead of
evaluating to their value, like a normal symbol, a function is executed
instead. Magic words are normally used to simplify user-interface
software.

Magic words are not recognised during non-interactive evaluation (e.g.
when loading a disk file).

Magic words are a Poplog specific extension to Common Lisp.


-----------------------------------------------------------------------
2  Built-In Magic Words
-----------------------------------------------------------------------

The following magic words are present in the standard Poplog Common Lisp
system:

    ved im                              for entering the editor

    help ref showlib src teach          for accessing documentation

    load lib                            for loading (library) programs

    pop11 prolog                        for switching language

    cd pwd                              for changing *current-directory*

    stop  (Unix only)                   for suspending Poplog

    bye                                 for leaving Lisp top-level

They are described more fully in REF * POPLOG_ONLY.


-----------------------------------------------------------------------
3  The MAGIC-WORD Module
-----------------------------------------------------------------------

Loading the MAGIC-WORD module enables users to define their own magic
words. It also makes it possible to cancel the built-in magic words,
should these be a problem.

The module adds the following symbols to the Poplog package:

    magic-word-handler              [constant]
    define-magic-word               [macro]
    cancel-magic-word               [function]
    list-magic-words                [function]

They are described below.


-----------------------------------------------------------------------
4  The Magic-Word-Handler Hash Table
-----------------------------------------------------------------------

The bindings between magic words and their associated functions are
stored in a hash table, in the constant magic-word-handler.

A function, list-magic-words, is provided which returns a list of all
currently defined magic words. For example:

    == (list-magic-words)
    (PROLOG SHOWLIB POP11 TEACH HELP VED SRC IM)


-----------------------------------------------------------------------
5  Defining Magic Words
-----------------------------------------------------------------------

New magic words may be created using the macro define-magic-word. Its
specification is:


(define-magic-word name                                          [macro]
                  {declaration | doc-string}*
                  {form}*)

        This defines name  as a  magic word, and  associates a  function
        that executes {form}*  with name.  The body of  the function  is
        wrapped in an implicit block called name.

        The documentation string,  if present, is  associated with  name
        under the documentation class magic-word.

        Whenever  name  is  evaluated  as   a  top-level  form  by   the
        interactive top-level  evaluator,  the  associated  function  is
        executed. Its results, if any, are discarded.

        A simple example:

            (require :magic-words)

            (define-magic-word bye
                (bye))


-----------------------------------------------------------------------
6  Cancelling Magic Words
-----------------------------------------------------------------------

To cancel a magic word, use the function cancel-magic-word:


(cancel-magic-word symbol)                                    [function]
        This removes the  entry for symbol  from the  magic-word-handler
        hash-table, and  also erases  any magic  word documentation  for
        symbol. cancel-magic-word returns t if symbol was a magic  word,
        and nil otherwise.



--- C.all/lisp/help/magic-words
--- Copyright University of Sussex 1991. All rights reserved.
