home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d181 / amxlisp.lha / AMXLISP / Interface.doc < prev    next >
Lisp/Scheme  |  1989-02-25  |  8KB  |  180 lines
  1. PRELIMINARY DOCUMENTATION FOR THE EXTENDED VERSION OF XLISP IN AMIGA:
  2.                      AMXLISP
  3.  
  4. Installation:
  5.    the kernel of AMXlisp is named amxlisp
  6.    you need these files from the AMXlisp distribution disk:
  7.       init.lsp           some functions are modified, others added
  8.       interface.lsp      C-structure manipulations
  9.       defamiga.lsp       amiga libraries interface
  10.       fd (dir)           preprocessed fd.files (V1.2)
  11.       xlinclude (dir)    preprocessed C include files(V1.2)
  12.  
  13. Execution:
  14. 1> assign fd: amxlisp:fd
  15. 1> assign xlinclude: amxlisp:include
  16. 1> amxl
  17.  
  18. (in fact, assigns are automatically executed in init.lsp when loading)
  19.  
  20. I         C-structures Manipulation
  21. -----------------------------------
  22. (load-c-struct "<include_file>" [<structure_list>] )
  23.             where <include_file> is the name of the include file
  24.             containing the definitions of the C-structures you want to
  25.             use.
  26.              ex: (load-c-struct "exec/execbase")
  27.             The optionnal argument is to be used if you want to load
  28.             only a limited subset of definitions
  29.              ex: (load-c-struct "intuition/intuition" '(window))
  30.                   will load only the <window> structure definition
  31. CAVEAT: there is no automatic loading of involved structures, like in
  32.    C preprocessing. Loading structure window will NOT automatically load
  33.    Rastport definition for example.
  34.  
  35. Every definition loaded is now accessible via some method applied to its
  36. name.
  37. Methods:
  38.    :new  <pointer>     creates a new instance of the structure
  39.                        pointing to <pointer>. This call does not allocate
  40.                        memory in the C heap. The call creates a lisp-object.
  41.                         ex: (setq eb (send execbase :new (memory-long 4)))
  42.  
  43.    :ptr                access (read only) to the pointer
  44.                         ex: (send eb :ptr)
  45.                               returns the integer 4
  46.  
  47.    :size-of            returns the size (in bytes) of the C-structure.
  48.                        This method should be used when you want to
  49.                        allocate a new structure in the C heap, via
  50.                        an AllocMem()
  51.                        It is also used internally.
  52.  
  53.    :fshow              this method prints all C-fields of the structure
  54.                        Involved structure definitions are needed (see
  55.                        CAVEAT on load-c-struct), otherwise you will get
  56.                        an error. This function is not recursive, though
  57.                        it could be done with some care.
  58.  
  59.    :-> <fieldname> [<value>]
  60.                        Usenet readers: this is not a joke.
  61.                        This is the main method. You should pronounce ":->"
  62.                        "access-field". The symbol has been chosen for
  63.                        similarity with C symbol.
  64.                        The <fieldname> is the word that is used in
  65.                        C-include files.
  66.                         ex: (send mywindow :-> 'LeftEdge)
  67.                               will return the actual value of the field
  68.                               LeftEdge of your <mywindow> structure
  69.                        AMXlisp is not case sensitive. But don't forget the
  70.                        quote.
  71.                        <value> is an optionnal value for write access.
  72.  
  73.                        There is a mecanism of object generation.
  74.                        If Rasport definition is loaded, and mywindow is
  75.                        a window object,
  76.                         (send mywindow :-> 'Rastport)
  77.                         will return a Rastport structure, with the actual
  78.                         pointer in its instance variable.
  79.                        This mecanism allows multiple access in one
  80.                        simple lisp expression:
  81.                         (send (send (send mywindow :-> 'Rastport)
  82.                                     :-> 'BitMap)
  83.                               :-> 'Rows)
  84.                        If you want to write in a pointer field, you may
  85.                        pass a corresponding structure, the pointer will
  86.                        be extracted and stored in memory.
  87.  
  88. Other functions:
  89. (class-of <object>)    will return the name of the class as a string.
  90.                        This was written because the predefined method
  91.                        :class only returns an object, which is not really
  92.                        informative.
  93.  
  94. (c-to-string <ptr>)    while reading the include files, we have no means
  95.                        to detect if a (char *) points actually toward
  96.                        a null-terminated string. Therefore, we provide
  97.                        this function, to be used by the experimented
  98.                        programmer who knows where the strings are:
  99.                         (c-to-string (send (send mywindow :-> 'Title) :ptr))
  100.                               will return a lisp string (static) containing
  101.                               precisely the title of <mywindow>.
  102.  
  103.  
  104. II Amiga Libraries Functions
  105. ----------------------------
  106. (openlibrary '<library>)
  107.                is the correct way to open a library for using its
  108.                functions. It will create the symbol <library>.
  109.                The function definitions and the library base are
  110.                stored in this symbol.
  111.                You may compute the library base with:
  112.                   (cassoc 'base <library>)
  113.                      if the library has been opened
  114.  
  115. (defamiga '<function> '<library>)
  116.                will load the definition for <function> in <library>
  117.                and eventually open the <library>
  118.                Not case-sensitive.
  119.                 ex: (defamiga 'DisplayBeep 'intuition)
  120.                     (defamiga 'FindTask    'exec)
  121.  
  122.  
  123. (callamiga '<function> <library> [<par1>] ...)
  124.             will call <function> of <library> with parameters <par1> ...
  125.             You must give the actual number of parameters needed.
  126.             Parameters can be: lisp strings
  127.                                lisp integers
  128.                                lisp object defined with C-structures
  129.                                     manipulation functions.
  130.             When an object is passed as a parameter, its pointer is
  131.             extracted and passed to callasm, which is the hard-coded part.
  132.  
  133.             examples:
  134.                (callamiga 'displaybeep intuition 0)
  135.                (callamiga 'openlibrary exec "console.library" 0)
  136.                (callamiga 'setwindowtitles intuition <window>
  137.                               "Shoobeedoo" 0)
  138.                (callamiga 'sizewindow intuition <window> -40 -40)
  139.  
  140. CAVEATS:
  141. The SetWindowTitles() call is dangerous because of non-persistency
  142. of the string. (see Real Programmer section)
  143. At the moment, callasm will return the weird number 1163022930, if it
  144. detects an error (bad parameter type, incompatibility between argument list
  145. and register list, ...).
  146. This value comes from
  147.    DC.L 'ERRR'
  148. in the assembly part.
  149. It should be possible to invoke the standard error mechanism, but it
  150. has not been implemented.
  151.  
  152. REAL PROGRAMMER WARNINGS:
  153.  
  154. - you may define your own C-structures, your own libraries, granted
  155. you create a corresponding xlinclude file and fd file.
  156. Formats for these can be found in the comments of the interface/defamiga
  157. lisp files.
  158.  
  159. ******* NOT VALID IN 2.0 *****************************************************
  160. *-warning: since Xlisp is monovalued (there is only one value for each
  161. *   symbol) it is unsane to define a C-structure whose name is the name
  162. *   of a lisp function.
  163. *   ex: list         we had to rename the C-structure "list" into "c_list"
  164. *                    everywhere in the xlinclude files.
  165. ******* NOT VALID IN 2.0 *****************************************************
  166.  
  167. - using :-> in write mode maybe dangerous.
  168.    The code still lacks some features to write fields correctly in
  169.    complicated cases (ie writing a field more than 4 bytes long).
  170.  
  171. - methods are shared (i think) by all defined structures. If you want to add or
  172.    modify a method, please report to the code and be careful
  173.  
  174. - note on recursion of :fshow method:
  175.    the problem lies in C_list structures, where you will loop on lh_succ
  176.    field.
  177.  
  178.  
  179.  
  180.