home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / developm / source / oodleutl.cpt / oodles-of-utils / NotInROM / NotInROM-docs.txt < prev    next >
Encoding:
Text File  |  1992-02-21  |  4.8 KB  |  133 lines
  1. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2. ;; NotInROM-docs.txt
  3. ;;
  4. ;; Copyright ⌐ 1992 Northwestern University Institute for the Learning Sciences
  5. ;; All Rights Reserved
  6. ;;
  7. ;; author: Michael S. Engber
  8. ;;
  9. ;; Documentation for #~ "Not in ROM" syntax
  10. ;;
  11. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  12.  
  13. Neither I, Northwestern University, or the Institute for the Learning
  14. Sciences make any warranties about this code. It is provided free of
  15. charge. You are free to make modifications/additions, but please keep
  16. the copyright notices intact.
  17.  
  18. Send comments and bug reports to:
  19.  
  20.  Mike Engber
  21.  The Institute for the Learning Sciences
  22.  1890 Maple Ave
  23.  Evanston, IL  60201
  24.  
  25.  (708)467-1006
  26.  
  27.  from InterNet:   engber@ils.nwu.edu
  28.  from AppleLink:  engber@ils.nwu.edu@INTERNET#
  29.  from CompuServe: >INTERNET:engber@ils.nwu.edu
  30.  
  31. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  32.  
  33. In order to load NotInROM files with require, you must make sure its
  34. folder is in require's search path. You can do this will code like:
  35.  (push #4P"ccl:Library;NotInROM;" *module-search-path*)
  36. Alternatively, you can explicitly provide the pathname to require:
  37.  (require :NotInROM "ccl:Library;NotInROM;NotInROM")
  38.  
  39. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  40.  
  41. NotInROM-u provides a way to define trap calls which MCL does 
  42. not provide. These are generally traps that are listed as 
  43. "Not in ROM" in Inside Macintosh. To call a "Not in ROM" trap 
  44. you should use the following syntax:
  45.  
  46.  (#~SomeTrap args╔)
  47.    or
  48.  (require-trap-NotInROM #~SomeTrap args╔)
  49.  
  50. The #~; reader macro will first check if there is a Not in 
  51. ROM definition in effect for the trap name. If so, that's 
  52. what will be used, if not, it will expand as if you'd used 
  53. the regular #_ MCL syntax. The require-trap-NotInROM macro
  54. works  analogously to MCL's require-trap macro.
  55.  
  56. For example:
  57.  
  58.  #~Control  expands into the high level Control call documented in IM II
  59.  
  60.  #_Control  expands into the low level trap call documented
  61.             under PBControl in IM II
  62.  
  63. In the NotInROM folder you will find a variety of files which 
  64. define "Not in ROM traps." The files use a naming convention 
  65. of starting with a + followed by the name of the interfaces 
  66. file (in MCL's interfaces folder) from which they were 
  67. omitted.
  68.  
  69. Unlike regular traps, the Not in ROM traps are not 
  70. automatically loaded on an as needed basis (maybe someday 
  71. I'll get around to it). So you will have to ensure the 
  72. +interface files you need are loaded.
  73.  
  74. If you want to just load all the Not in ROM calls at once, 
  75. load the file NotInROM.lisp. You may want to do this, because 
  76. selectively loading the files requires you to know which trap 
  77. calls are Not in ROM and which interface file they belong to. 
  78. In addition, both #~ and require-trap-NotInROM behave 
  79. equivalently to #_ and require-trap for "in ROM" traps, so 
  80. you can choose to always use them and not worry about which 
  81. traps are "Not in ROM."
  82.  
  83. The set of "Not in ROM" calls defined is not complete. It 
  84. includes the most commonly needed ones; all the high level File 
  85. Manager calls, all the high level Device Manager calls, all the 
  86. Serial Manager calls, plus others. I've been adding to it on an
  87. as needed basis.
  88.  
  89. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  90.  
  91. Macros of Interest
  92.  
  93. To define your own Not In ROM traps use these macros. 
  94. Note: all trap symbols should start with an underscore 
  95. character, '_'.
  96.  
  97. deftrap-NotInROM  symbol result-type (&rest typed-arglist) &body body
  98.  
  99.  This macro defines a Not In ROM function. See the 
  100.  various +XXX.lisp files in the NotInROM folder for 
  101.  examples of it's usage.
  102.  
  103.  
  104. require-trap-NotInROM  trap-symbol &rest arglist
  105.  
  106.  This macro works like MCL's require-trap except it works 
  107.  properly for traps of the form #~SomeTrap as well as 
  108.  traps of the form #_SomeTrap.
  109.  
  110.  
  111. deftrap-alt-name  alt-trap-symbol asm-trap-symbol
  112.  
  113.  This macro is for defining traps whose high level names 
  114.  differ from their assembly language trap names. You can 
  115.  consider this a special case of the "Not in ROM" traps 
  116.  which only requires name mapping to handle. For example, 
  117.  the function DisposeHandle uses assembly language trap 
  118.  _DisposHandle. Currently, MCL seems to define all these 
  119.  traps in both their high level and assembly language 
  120.  names. This macro is provided in case this changes or 
  121.  omissions are discovered.
  122.  
  123. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  124.  
  125. MCL provides a file of it's own "Not In ROM" function
  126. definitions, interfaces.lisp. However, these are defined 
  127. as normal lisp functions, they do not use the #_ syntax, and 
  128. the arguments they accept and the values they return are not 
  129. always the same as those documented in Inside Macintosh. 
  130. NotInROM-u is provided as an alternative which makes the "Not 
  131. in ROM" calls more consistent with the other traps calls and 
  132. behave as per Inside Macintosh.
  133.