;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; NotInROM-docs.txt
;;
;; Copyright © 1992 Northwestern University Institute for the Learning Sciences
;; All Rights Reserved
;;
;; author: Michael S. Engber
;;
;; Documentation for #~ "Not in ROM" syntax
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Neither I, Northwestern University, or the Institute for the Learning
Sciences make any warranties about this code. It is provided free of
charge. You are free to make modifications/additions, but please keep
the copyright notices intact.

Send comments and bug reports to:

 Mike Engber
 The Institute for the Learning Sciences
 1890 Maple Ave
 Evanston, IL  60201

 (708)467-1006

 from InterNet:   engber@ils.nwu.edu
 from AppleLink:  engber@ils.nwu.edu@INTERNET#
 from CompuServe: >INTERNET:engber@ils.nwu.edu

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

In order to load NotInROM files with require, you must make sure its
folder is in require's search path. You can do this will code like:
 (push #4P"ccl:Examples;NotInROM;" *module-search-path*)
Alternatively, you can explicitly provide the pathname to require:
 (require :NotInROM "ccl:Examples;NotInROM;NotInROM")

In order to compile most of the files in the NotInROM directory,
you need to load the file "NotInROM-u". The following function
can be used to compile the entire package:

(defun compile-NotInROM (&optional verbose)
  (load (compile-file "ccl:examples;NotInROM;NotInROM-u" :verbose verbose))
  (dolist (file (directory "ccl:examples;NotInROM;*.lisp"))
    (unless (equalp (pathname-name file) "NotInROM-u")
      (compile-file file :verbose verbose))))

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

NotInROM-u provides a way to define trap calls which MCL does 
not provide. These are generally traps that are listed as 
"Not in ROM" in Inside Macintosh. To call a "Not in ROM" trap 
you should use the following syntax:

 (#~SomeTrap argsÉ)
   or
 (require-trap-NotInROM #~SomeTrap argsÉ)

The #~; reader macro will first check if there is a Not in 
ROM definition in effect for the trap name. If so, that's 
what will be used, if not, it will expand as if you'd used 
the regular #_ MCL syntax. The require-trap-NotInROM macro
works  analogously to MCL's require-trap macro.

For example:

 #~Control  expands into the high level Control call documented in IM II

 #_Control  expands into the low level trap call documented
            under PBControl in IM II

In the NotInROM folder you will find a variety of files which 
define "Not in ROM traps." The files use a naming convention 
of starting with a + followed by the name of the interfaces 
file (in MCL's interfaces folder) from which they were 
omitted.

Unlike regular traps, the Not in ROM traps are not 
automatically loaded on an as needed basis (maybe someday 
I'll get around to it). So you will have to ensure the 
+interface files you need are loaded.

If you want to just load all the Not in ROM calls at once, 
load the file NotInROM.lisp. You may want to do this, because 
selectively loading the files requires you to know which trap 
calls are Not in ROM and which interface file they belong to. 
In addition, both #~ and require-trap-NotInROM behave 
equivalently to #_ and require-trap for "in ROM" traps, so 
you can choose to always use them and not worry about which 
traps are "Not in ROM."

The set of "Not in ROM" calls defined is not complete. It 
includes the most commonly needed ones; all the high level File 
Manager calls, all the high level Device Manager calls, all the 
Serial Manager calls, plus others. I've been adding to it on an
as needed basis.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Macros of Interest

To define your own Not In ROM traps use these macros. 
Note: all trap symbols should start with an underscore 
character, '_'.

deftrap-NotInROM  symbol result-type (&rest typed-arglist) &body body

 This macro defines a Not In ROM function. See the 
 various +XXX.lisp files in the NotInROM folder for 
 examples of it's usage.


require-trap-NotInROM  trap-symbol &rest arglist

 This macro works like MCL's require-trap except it works 
 properly for traps of the form #~SomeTrap as well as 
 traps of the form #_SomeTrap.


deftrap-alt-name  alt-trap-symbol asm-trap-symbol

 This macro is for defining traps whose high level names 
 differ from their assembly language trap names. You can 
 consider this a special case of the "Not in ROM" traps 
 which only requires name mapping to handle. For example, 
 the function DisposeHandle uses assembly language trap 
 _DisposHandle. Currently, MCL seems to define all these 
 traps in both their high level and assembly language 
 names. This macro is provided in case this changes or 
 omissions are discovered.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

MCL provides a file of it's own "Not In ROM" function
definitions, interfaces.lisp. However, these are defined 
as normal lisp functions, they do not use the #_ syntax, and 
the arguments they accept and the values they return are not 
always the same as those documented in Inside Macintosh. 
NotInROM-u is provided as an alternative which makes the "Not 
in ROM" calls more consistent with the other traps calls and 
behave as per Inside Macintosh.