HELP MAGIC-WORDS John Williams, May 1988 CONTENTS - (Use 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.