Aamb!:XffU V V W X X Y t mbHH $ d HHHHff@  d'  Footnote TableFootnote**. . / - :;,.!?iron/ ^"7/aA   *EquationVariables3.0a!U U V V     !    X g W h W q !*X X Y Y    219425: Heading 2: 2.1. Loading and Finding Objects 318541: Heading 2: 4.2. Specifying class inheritance 112575: Heading 2: 4.1. Implicit class definitions$U T dV J AQC 3AW Y 219425: Heading 2: 2.1. Loading and Finding Objects 3BX Y 318541: Heading 2: 4.2. Specifying class inheritance 3CY Y 318541: Heading 2: 4.2. Specifying class inheritanceI i W I <$lastpagenum>J <$daynum> <$monthname> <$year>K (<$daynum> <$shortmonthname> <$shortyear>L 4<$daynum> <$monthname> <$year> <$hour24>:<$minute00>M ><$daynum> <$shortmonthname> <$shortyear> <$hour24>:<$minute00>N <$daynum> <$monthname> <$year>O (<$daynum> <$shortmonthname> <$shortyear> P  <$fullfilename> Q  <$filename> R  <$paratext[Title]>S  <$paratext[Heading]>T  <$curpagenum>U  <$marker1>V  <$marker2>X Pagepage <$pagenum>95:Y Heading Number3<$paranum[Heading 1,Heading 2,Heading 3,Heading 4]>2Z Heading 1 Number<$paranum[Heading 1]>[  Heading Text4<$paratext[Heading 1,Heading 2,Heading 3,Heading 4]>\ Paragraph Text <$paratext>] Number<$paranum> a^ Heading 1 Text<$paratext[Heading 1]>=}E 2=  >  ?  Ancl@  A  B  A(C AhtyD! ; Atea" >ut# da$ rna% y$h& n' a<$( <) a<$* ash+  , a- i> . te/ 0 H1. 1 uumF er3 5. >4 $p5 :3. d6 $m[7 e2,8 e4]9 e1 : aHe; He< te= 1ng> 3ng? gr@ $3.1. A D B a aC nxtD tngE EF G H I J K L M 5.1. N  O P Q yR   S  T  U  V  W X G 2. H  M $ T h V  W  _   Table 1: teX Y H1.Z  [  \  ] ^ :_  ` [ i  , j! ] k" - l# e m$ e n% e o& g p' g q( r r) s* D t+ a au, nxtv- tngw. Ex/ y0 z1 {2 |3 }4 ~5 6 7 8 9 : ; < = > ? @ A B C  D  E  F  G  5.2. H  I J K L M N O P Q R S 5.3. T -U eV eW eX gY gZ r[ \ D] 5.4. ^ nxt_ tng` 7. a b 5.c 1.d 3.e  2.f 4.g h i j k l 6. m  n  o 6.1. p  q  r  s  t  u  v  w  x 7.2. y  z  {  |  }  ~               -  e  e  e  g  g  r    D   nxtZ t4.    5.      .       6.  7.1.   1.          \  ]  ^  _  `  a                  w 8. x ~ - e e e g g r  D  9.   j          .         .                    10.   ^   . 8     12.  e  g  g  r   ! D " .& ' ( ) b Appendix III -- j k p .y ~   '  :  C .D E F  13. G o  T  W  X  Y  ^ _ ` a Appendix I -- s I.i. t  w     0|     -I.ii.           !  "  #  $  %  &  ' Appendix II -- ( nd)  *  + Appendix IV -- , Appendix V -- - . #/ I.iii. $0 -1 ~2 .3 4 5 6  7  Y8  9  :  ;  <  =  >  ?  @ p IA B .C D E F G H I J K diiL  M  N  O  P  Q  &R  S  (T  )U  *V  +W  -X IY ndZ  [  \ Ap] -1.^ p4.-_  5.` 6.a 7..b  3.c 8.d 2.e  f 1. (g V.i. h 3.i 2.3j  k  l  V.ii. m  n  o  p  q  r  s  t  V.iii. u  v  w  x  y  z  { i |  }  ~                  4   6.2.          p   .  7.      .  . / 0 1  2 .a b c iid  e  f  g  h  i  j  k  l m n o p q r s t u v w x y z { | } ~   2.                       11.    .       .   ii              5  6 7 ; o t y z { |         I < d    U d     V H$   H$      UUd   HM   HM   UUd   HH  HH  UUd   H+   H+    TUTUn  page # H   .H    TUTU`   HH  HH  UUd   d   W H$HH  $HH  UUd   d   X HG[#p  HG[#pHrhNHrhN Footnote Hc.p  Hc.pHrhHrh  Single LineE$]   Footnote    HE2p ! HE2pHrhHrh  Double LineH$    Double Line  "    1 "  1d11H    $  Single Line   "      H. hSp # H. hSpHH PTemplate by Steve Shafer, School of Computer Science, Carnegie Mellon UniversityH94p # H94pH$H$ 9Based very loosely on templates by Frame Technology Corp.H'#p # H'#pH)H) H'#p # H'#pH)H) 2H./p # 2H./pH6H6 #BlankPage Version 1.0, October 1990 d   ole! ! Y HH   HH!!   ! ! `  The Melange Interface Generator *UU`  Robert Stockton  ;UU   School of Computer Science GUU Carnegie Mellon University HSUU@ Pittsburgh PA 15213 dUUn H 22 May 1997 b` ho  Abstract SUU  elf The Melange interface generator provides a mechanism for providing access to native C code. It is UU n dmodeled upon Apple Computers Creole, and shares Creoles goals of automatically providing full supHUU hport for a foreign interface based upon existing interface descriptions. It also, like Creole, provides UU cmechanisms for explicitly adapting these interfaces to provide a greater match between C and Dylan UU@ data models. UU  i Melange, however, differs from Creole in a number of significant ways. This document, therefore, pro UU evides a gentle introduction to Melange without attempting to build upon any existing descriptions of UU@ Creole. l9 ` ce Introduction XUU  lox Melange is an automatic interface generator which provides transparent access to both functions and data defined or dUU  Szgenerated by existing C libraries. It allows users to import interfaces  from existing C header files, controlled by pUU n tthe contents of a define interface top-level form which may be included in the same file as arbitrary Dylan code. |UU orrThe user may use the functions and data specified by this interface as if they were native Dylan objects, and may UU@ ciexport them to other modules. UU  m{ Melange provides reasonable interpretations for the various sorts of C declarations which may appear in a header file, le UU@ nisas well as mechanisms for explicitly modifying the default interpretations when necessary. For example, users may: mptUU`R an4specify rules for the translation of foreign names leUU`T ?explicitly specify new names for specific objects or routines utoUU`U neGspecify parameter passing conventions or mutability of foreign objects d oUU`V Ospecify mappings or equivalences between foreign data and native equivalents  UU`X adFchoose to import only a subset of the declarations in the header file UU W elyAll of these customizations, as well as the name of the C header file, are specified by a define interface clause. See sUU@W d !the next section for an example. a0UU  , sThe basic model for interface importation is based upon that used within Apple Computers Creole interface genererp<UU varator. There are, however, significant differences in some of the details. (For instance, the equate, map, and HUU ngtobject-file directives used in the above example are unique to Melange. Likewise, Creoles type directive would anH   H ew r sciTUTUd# tisOr possibly  mindy -f melange.dbc class.intr , depending upon the installation on your particular machine. VH]   e H] ve  nts ` ad  e2]   sn 2]    elAlUUd. za nHo  ,reHoe  cus`/ / minimal-name-mapping-with-structure-prefix d  po" " [ ud HH  gerHHyva22er, sign" en2UU` . module: Junk tUU` , #synopsis: A poor imitation of ls e UU` t a*UU` nidefine library junk se6UU` di use dylan; nBUU`  use streams; NUU` end library junk; ZUU`  fUU` define module junk bc rUU` ep use dylan; ~UU` ur use extensions; UU`  use extern; UU` H use streams; veUU`  use standard-io;  eUU` end module junk; UU`  UU` eldefine interface UU` B // This clause is more complex than it needs to be, but it does UU` . // demonstrate a lot of Melanges features. UU` ( #include /usr/include/sys/dirent.h, UU` & mindy-include-file: dirent.inc, UU` HG equate: {char /* Any C declaration is legal */ * => }, 2UU` . & map: {char * => }, UU` taD // The two functions require callbacks, which we dont support. ib&UU` : exclude: {scandir, alphasort, struct _dirdesc}, 2UU`  seal-functions: open, >UU`  read-only: #t, JUU` nk' name-mapper: minimal-name-mapping; ~VUU` 7 function opendir, map-argument: {#x1 => }; bUU` e 5 function telldir => tell, map-result: ; enUU`  struct struct dirent, zUU`  prefix: dt-, ineUU` ' exclude: {d_namlen, d_reclen}; mplUU` o end interface; UU`  dUU` f )define method main (program, #rest args) UU`  for (arg in args) UU`  let dir = opendir(arg); inUU` 1 for (entry = readdir(dir) then readdir(dir), gUU` in% until entry = null-pointer) {UU` st6 write-line(entry.dt-d-name, *standard-output*); UU` wh end for; pUU`  closedir(dir); : { UU` or end for; dir~UU` end method main; f}.UU  >tWe will then process this file through Melange to produce a file of pure Dylan code. If Melange is contained in the |:UU@ opEfile  melange.dbc , we would use the following command line: c{RUU` te.mindy -f melange.dbc dirent.intr dirent.dylan zjUU  dtThis command will process melange.intr and write a file named dirent.dylan. In this case, it will also silently yvUU@ enDwrite a file named dirent.inc, whose use will be explained later. et2o  2ogs  `0 di/ Provides the translations described above. (eH$  H$ u  y =ul`1  minimal-name-mapping i2$  2$$fo   2 ed, Same as above, but excludes the struct-ir@2 name$ prefixes. fH@  ts H@o  fi o`3 I c-to-dylan ain2@  la2@@ u  llong`4 R!Like miinimal-name-mapping, but: d C en/ Adds hyphens to reinforce CaseBased word roc*@C a separation. 8`7 n, Adds get- prefixes to slot accessors. H  c wHin ! et2`5  identity-name-mapping 2  2 t ! atis `6 (e Does no translation. d  u# # \ 1HH  HH''fo  # 'UU  apYou can compile dirent.dylan normally, via mindycomp, but in order to execute it, you must make sure that the UU wMindy interpreter will be able to load the appropriate routines from the library containing the dirent routines. IdeUU vally, you would simply let Mindy load the appropriate code dynamically. However, this is presently only available for *UU ocqa few machines. Therefore, we will follow a messier approach and build a new version of the interpreter which is 6UU@ aware of the desired functions. NUU  2oMove to the build directory for the Mindy interpreter, and edit the Makefile so the EXTERN-INCLUDES line menZUU s vtions your_dir_path/dirent.inc and then run make mindy. In this case, this is all that is required to build a new fUU@ 3interpreter which is aware of the dirent routines. ~UU` ]You can now put it all together, invoking the new interpreter on the compiled program, with: rUU` mpmindy -f dirent.dbc . UU` e @This should print a list of all files in the current directory. leUU  pr{Because of the difficulty of relinking the interpreter for each new library, it is expected that administrators will build y lUU e va set of standard library interfaces which are prelinked into the interpreter and exported as general Dylan library UU aptinterfaces. In the future, as Melange (and the Gwydion environment) are extended to support better linking and loadNUU@ Mo^ing capabilities, it should become easier to incorporate C libraries on an as-needed basis.  ` Z Basic Use ,UU  pazAlthough the define interface form provides a fairly rich sublanguage for specifying interfaces, it is often sufficient 8UU@ aUto use just the minimal form. For example, if gc.h contained the following code: iPUU` tetypedef char bool; ed \UU` typedef struct obj obj_t; hUU`Z typedef char *str; oultUU` al iUU` d,extern obj_t alloc(obj_t class, int bytes); heUU`% in#extern void scavenge(obj_t *addr); rarUU`& th.extern obj_t transport(obj_t obj, int bytes); UU`' an*extern void shrink(obj_t obj, int bytes); UU`( te nUU`) ra#extern void collect_garbage(void); inUU`* ut ,UU`+ heextern bool TimeToGC; UU`, or eUU`- oa3 #define ForwardingMarker ((obj_t)(0xDEADBEEF)) beUU` orwthen you could import it by creating a file named class.intr which includes arbitrary Dylan code and the following: e iUU`  videfine interface u(UU`! if#include gc.h; 4UU`" t  end interface; toLUU,$ imsYou would then run  melange class.intr , which would produce a file of Dylan code which contains approUXUU$ striate definitions for the classes   ,   ,   , and   ; the variable  TimeToGC ; and dUU$ %the functions  alloc ,  scavenge ,  transport ,  shrink , and  collect_garbage . (The constant ernd  $ $ ] )raHH  HHV##l TimeTo  $ #UU@$ -Q ForwardingMarker  will be excluded because it is not a simple literal.) hUU  t qIf you were running under the HPUX operating system and the named functions were already linked into Mindy, then *UU faythis might be all that you would need. After compiling the resulting Dylan file, you could call the functions as if they n6UU cl|had been written in native Dylan code, and you can access the  TimeToGC  variable by calling the function with that r BUU@ bo!name. For example you might run: jZUU` <if (TimeToGC() ~= 0) fUU` ; collect_garbage(); %rUU`  end if;  UU   yThis code fragment points out some of the hazards of simple imports. Melange has no way of knowing that  bool  UU $ sshould correspond to Mindys    class, so you are stuck with a simple integer. Likewise, the system TiUU ~wouldnt be able to guess that  char *  shoudl correspond to the Mindy class   . We will explain in UU@ ruslater sections how  map:  or  equate:  options may be used to provide this information to Melange. faHUTU h l  Loading and Finding Objects ngUU  anu As mentioned above, the include directive in the previous example will only work for files which have been previnUU@ imZously linked into Mindy. There are extra facilities available to handle other situations. UU, jwIf your machine is one for which we support dynamic loading , and you wish to load some declared objects from a  UU@  ~shared library, you can add one or more  object-file : options to the  #include  clause, as in the following: 4UU` shdefine interface M@UU` n>#include gc.h, LUU`  mp'object-file: /usr/lib/mindy/gc.sl; XUU` dn end interface; hatpUU   shtThis would cause the code from gc.sl to be loaded into Mindy at run-time and make its functions and objects avail |UU@  0able just as they were in the previous example. nfUU  e.x If you are running on a non-HPUX machine, you will have to statically link Mindy with the appropriate library and a ctUU@ s ilist of mappings from names to addresses. This can be accomplished most easily by following these steps: eUU c iegAdd a  mindy-include-file:  option to your interface definition. This specifies the name of an dyUUc hinterface description file which will be written by Melange, and which can later be linked into Mindy onUU@c ec%along with the appropriate library. dUU e infRun Melange on the source file in the normal manner. You may wish to move the newly created interface UU@e je2description file into your Mindy build directory. UU d rfoChange the Makefile in the Mindy build directory, by adding the imported library to  LIBS  and the inter itUU@d je3face description file to  EXTERN-INCLUDES . ere UU`f xaJ Run  make  to rebuild Mindy with the new library information. UU`b ta8 Compile and run the generated Dylan code as normal. 0UU`g li? A typical interface definition for this approach might be: mosH   H in e-fe:TUTUd_ uriAt present, function types are not fully supported. You should not depend upon them to work as expected. wd  c l% % ^ onHH  eibHHse'' source % rm'UU`h mdefine interface eUU`i #include gc.h, UU`j ur6mindy-include-file: /usr/local/mindy-build/gc.inc *UU`k in end interface; y aM ` Importing Header Files d tlUU  rYou import C definitions into Dylan by specifying one or more header files in an #include clause. This may take xUU@ tone of two different forms: UU`  define interface hUU` co#include file1.h; UU` A end interface; deUU` apor h mUU` define interaface UU` "#include {file1.h, file2.h}; UU` _end interface; fuUU  ottMelange will parse all of the named files in the specified order, and produce Dylan equivalents for (i.e. import) lUU usome fraction of declarations in these files. By default, Melange will import all of the declarations from the named UU 'files, and any declarations in recursively included files (i.e. those specified via  #include  directives in the  .h  ,UU rfile) which are referenced by imported definitions. It will not, however, import every declaration in recursively 8UU ioyincluded files. This insures that you will see a complete, usable, set of declarations without having to closely control oDUU uthe importation process. If you wish to exert more control over the set of objects to be imported, you may do so via ;PUU@ Nthe  import ,  exclude , and  exclude-file  options.. hUU  ilzIf you only need a small set of definitions from a set of imported files, you can explicitly specify the complete list of tUU@ od`declarations to be imported by using the  import:  option. You could, for example, say: tUU` audefine interface pUU` la#include gc.h, UU` -import: {scavenge, transport => move}; yUU` .e end interface; UU  irThis would result in Dylan definitions for  scavenge ,  move ,   , and   . The latter types ecUU ivxwould be dragged in because they are referenced by the two imported functions. Again, if you equated  obj_t  to avUU trr  then neither of the types would be imported. The second import in the above example performs a renamUU o |ing at the same time as it specifies the object to be imported. Other forms specify global behaviors.  Import: all  ilUU alwillcause Melange to import every top level definition which is not explicitly excluded.  Import: all-UU aryrecursive  causes it to import definitions from recursively included files as well.  Import: none  restricts tUU@ himportation to those declarations which are explicitly imported or are used by an imported declaration. (UU` inpYou may also use the  import:  option to specify importation behavior on a per-file basis. The options  @UU` %import: file.h => {import1, ...} LUU` woimport: file.h => all thXUU` byimport: file.h => none .pUU` atmwork like the options described above, except that they only apply to the symbols in a single imported file. od  em& & _ atheHH   poHHQif$$Import:& $UU  e uThe  exclude:  and  exclude-file:  options may be used to keep one or more unwanted definitions from rUU@ au,being imported. For example, you could use: in*UU` lldefine interface 6UU` #include gc.h, BUU` d&exclude: {scavenge, transport}, NUU` n exclude-file: gc1.h; ZUU` Yo end interface; rUU  n tThis would prevent the two named functions and everything in the named file from being imported, while still includ1Ӣ~UU {ing all of the other definitions from  gc.h . Note that these options should be used with care, as they can easily ns UU xcxresult in incomplete interfaces in which some declarations refer to types which are not defined. This could result in UU atqerrors in the generated Dylan code. (The  import: file => none  option described above is a safer way of UU@ 7achieving an effect similar to  exclude-file:  -fiUU  ayvYou may also prevent some type declarations from being imported by using the  equate:  option (described in a UU later section). If, for example, you equated  obj_t  to   , then Melange would ignore the definition for UU@ cld obj_t  and simply assume that the existing definition for    was sufficient. ntUU  ctxYou may have any number of  import: ,  exclude: , and  exclude-file:  options, and may name the dUU same declarations in multiple clauses.  Exclude:  options take priority over  import: s. If no  import:  tUU@ omwoptions are specified, the system will import all non-excluded symbols, just as if you had said  import: all . Dy% ` Specifying Object Names opDUU  ver Because naming conventions differ between C and Dylan, Melange attempts to translate the names specified in C PUU@ pBdeclarations into a form more appropriate to Dylan. This involves hUU` n - Adding angle brackets around type names. ttUU` pl< Adding dollar signs at the beginning of constant names. geUU` de7 Translating (non-initial) underlines into hyphens. siUU` he6 Adding struct-name$ prefixes to slot accessors. UU  s In many cases, this default behavior will be precisely what you want. However, Melange provides mechanisms for namUU@ Gspecifying different translations for some or all of the declarations. ns :UTU ` Mapping functions UU  t The translations described above are provided by calls to a built-in name mapping function named  minimal-aiUU  ename-mapping-with-structure-prefix . You may specify other mapping functions via a  name-maptUU@ n Cper:  option. Our example interface might then look like this: PUU` dedefine interface o*UU` e #include gc.h, 6UU`  &object-file: /usr/lib/mindy/gc.o, BUU`  name-mapper: c-to-dylan; ar NUU`  ni end interface; ged!  iti' ' ` s.siHH"  m HHusos In ' hiUUhB \ Table 1 describes the four standard mapping functions that are provided by Melange. ifUU` nsm Users may link new mapping functions into Melange. In the Mindy implementation, this is done as follows: UU`8 de Create a new module which imports module  name-mappers  from library  c-parse . UU`9 -mbDefine methods on the  map-name  generic function which accepts the following parameters: UU ; peimapper  -- a    which is typically specialized by a singleton to select a specific name oUU@; e mapper method. , UU < fcategory  -- a    which will always be one of:  #type ,  #constant , UU@< in)#variable , or  #function . ,UU`= Y prefix  -- a    which is typically prepended to the result string. 8UU`> G name  -- a    which supplies the original C name. le DUU ? ur`sequence-of-classes  -- a sequence of simple names for the classes which logically contain y PUU? unZthe given object. For example, if we were processing the declaration  struct str {int \UU? n^size; char *chars , one of the calls to the mapping function would have with  name hUU@? neCbound to  size  and  classes  bound to  #[str]. fotUU`@ : ] and returns a    which will be used as the Dylan name for the declaration. lUU`: pejCompile this module and link it into Melange by concatenating it to the end of the  melange.dbc . UU A bmMapping functions may call  hyphenate-case-breaks  which performs the same CaseBased separation as UUA ris done by  c-to-dylan . The trivial  identity-name-mapping  described above might be implemented UU@A by: g>UU B s define method map-name DUU@B seG(mapper == #identity-name-mapping, category, prefix, name, classes) loUU`D y => (result :: ) giUU`E amname; e wUU`F d end method map-name; {UU H ?xYou may specify different name mappers to be applied to the slots of container types. This capability is described in boUU@H a later section. :U=TU `G st Prefixes ZUU I  z As noted above, the name mapping function is passed a prefix argument. By default, it is an empty string, but users fUUI kvmay specify a different value by adding a  prefix:  option to the interface definition. For example, we might rUU@I e- expand the previous example to: e H#  AHc-   TTUTU$ enThe definition may be implicit, as in char ** int or struct foo *bar. Simply by being present these code fragments supply implicit RUTUD (6definitions for char *, char ** and struct foo. d$  elt( ( a EHH%  nmeHH}))ecify di( ap ) aUU`J s define interface өUU`K is#include gc.h, UU`L a &object-file: /usr/lib/mindy/gc.o, *UU`M name-mapper: c-to-dylan, th6UU`O ctprefix: gc-; eBUU`N de end interface; stZUU P f{ This would cause Melange to tack  gc-  onto the beginning of every translated symbol. Because the system knows , wfUUP rabout the standard Dylan naming conventions, it can do this intelligently. You would, therefore, get names like rUU@P I  ,  gc-time-to-gc , and  gc-scavenge . tUU Q mpoNote that the interpretation of the prefix is entirely up to the name mapping routine.  Identity-name-map **UUQ . yping , for example, completely ignores the prefix. All of the other standard mapping functions prepend it to the name nUU@Q Xbefore adding brackets or dollar signs, but after performing all other transformations. deUU R | Facilities for adding localized prefixes to slot accessors, enumeration literals, etc. will be described in later secapUU@R thtions. UFUTU `S : Explicit Renaming UU T ins Although the automatic name mapping described above is sufficient for most objects named within a header file, slaUUT e xthere are cases in which you might wish to explicitly control the name of one or more specific objects. You can do this wUUT etythrough a  rename:  option. This options specifies a list of translations between raw C names and Dylan identifi(UU@T e !ers. For example, we might have: n@UU`U amdefine interface LUU`V ap#include gc.h, XUU`W r &object-file: /usr/lib/mindy/gc.o, dUU`X taname-mapper: c-to-dylan, nd pUU`Y prefix: gc- be|UU`\ tsArename: {struct obj => , collect_garbage => GC}; eUU`Z  end interface; addUU [ efy Note that the target of the renaming is an ordinary Dylan variable and is therefore case-insensitive. However, the UU[ iczsource is an alien name, which is (like all C code) case sensitive. Alien names should refer to an object, function, or UU[ fstype in exactly the same way you would refer to them in C. We therefore say  struct obj  instead of simply pecUU[ ca obj , and might also say  enum foo  or  union bar . Alien names are actually parsed according to the stanes UU@[ ndard lexical conventions of C, so you may use arbitrary spacing and even include comments if you really wish. UU a c.qNote that rename: options supply names for new objects (and types) that are being imported into Dylan. You can UUa not, therefore, simply rename  bool  to    to make it equivalent to the existing type -- this would sim UUa ddrply result in a name conflict. For these purposes, you would instead use the equate and map operations, which UUa ve|will be described later. (In fact, if the C declaration had defined a type name  boolean , you might have to explico UUa n,witly rename it to something else in order to avoid name conflicts with the existing type. Of course, in the above exam i$UU@a ecLple, the  gc-  prefix would be sufficient to make the name unique.) .UETU `] AAnonymous types uabUU ^ ngt The alien names described above can also be used to refer to Cs so-called anonymous types. You can therefore cnUU^ llrefer to  char * ,  int [23] , or even  int (*) (char *foo)  (i.e. a pointer to function which takes a ylazUU ^ wstring and returns an integer). The ability to refer to anonymous types is useful because it allows you to use the ypedy  lre) ) b orheHHz  a HH~wh''|will b ) te 't,UU^ ioprename option to provide explicit names for such types. Normally Melange would simply generate a an arbitrary meUU^ r panonymous identifier for the type. Without knowing the name of this type, you could not define new operations UU^ ullupon it. However, by saying, for example,  rename: {char * => } , you can provide a conTh*UU@^ ri2venient handle to use in defining new operations. M `l .  Type Definitions lUU,m re{ When Melange encounters a type definition within a header file, it will typically create a new Dylan class which ylaxUUm rcorresponds to that C type. Usually, this will be a subclass of   , which encapsuUUm dvlates the raw C pointer value (i.e an object address). Each statically typed pointer class will have exactly the same UUm wh|structure (i.e. a single address), but the class itself can be used to determine what operations are supported on the data. r UUm lyThis could include slot accessors for  struct s and  union s, dereference operations for pointer types, or gen UU@m co/eral information about the objects size, etc. ulUU  , uThere are times when you will find that some of the types defined in a header file are not really new. It might be nUU dwthat they are completely identical to some type defined in another interface definition, or they might be isomorphic typUU wisto some existing type which has more complete support. Melange provides support for both of these cases. The first ypeUU llscase is handled by equating the two types, while the second is handled by mapping (i.e. transforming) one type ue UU@ reinto the other. lyUU n ss}For example, many header files contain definitions use the types  char *  and  boolean . The declarations of iUUn a}these types dont provide any semantic interpretations --  char *  is simply the address of a character, and boolean UUn iois nothing but a one-byte integer. However, by equating  char *  to the predefined    type, we can tell e ,UUn w}Melange that it is actually a    and should inherit all of the operations defined upon   s. Like 8UUn alwise, we can map the integral  boolean  values into  #t  and  #f  to get a   . These integral values moDUUn t.}will be automatically translated into   s when they are returned by a C function, and   s will ePUU@n d Jbe translated back into integers when passed as arguments to C functions. >UqTU ho lyImplicit class definitions , mUU  on{ Unless otherwise specified, new classes will be created for each type defined in a C header file. When the header file doUU masprovides meaningful names for these types, then Melange will pass those names to the mapping functions to generate notUU e snames for the Dylan classes. Otherwise, an anonymous name will be generated, limiting your ability to refer to the nUU inew type. For example,  struct foo  would typically generate the class   , while  struct foo ***  alUU ttmight generate the class   . In either case, you can explicitly specify the name for the new ueUU@ n=class by using the  rename:  option described above. wUU  nez Different sorts of C declarations will yield different sorts of Dylan classes as well as different sets of operations UU@ . Hdefined upon them. Therefore, we will consider each variety separately: onUU  wiPrimitive types  -- The types  int ,  char ,  long ,  short  and their unsigned counterparts are simply aniUU es|translated into   , while  float  and  double  are translated into   . However, clUU anjMelange knows the sizes of each of these types so that pointers and native C vectors of them (described *UU@ stEbelow) will work properly. No new types are created for these types. 6UU`  ӅBUU  yPointer types -- Declarations like  int *  or  struct foo ***  generate new subclasses of   . Note that  struct foo *  is actually treated as a synonym for  struct dH  yn Hfe ofpeTUTU$ At present, the only set of definitions provided will be those appropriate for the HPUX OS. However, it is straightforward to add difRUTUD 'ferent sets of definitions to Melange. d  yni* * c sledHH  aHHe ((at> .* (UU@ kniincluded in the  superclasses:  option, then it will be added at the end of the superclass list. UU  ilvAs demonstrated in the above example, you are still responsible for specifying whatever functions are required to sat*UU l{isfy the contract for the declared superclasses.    will be declared as a sequence, but you must specify a nte6UU@ ^forward iteration protocol before any of the standard sequence operations will work properly. NUU` yzThe  superclasses:  option may currently be used within  struct ,  union , and pointer clauses. q `` or#Translating Object Representations forUU Y yWhenever a native C object is returned from a function or a Dylan object is passed into a C function, it is necessary to UUY Httranslate between the object representations used by the two languages. From Melanges standpoint, native C objects UUY tconsist of an arbitrary bit pattern which can be translated to or from a small number of low level Dylan types -- UUY emunamely , , or any subclass of . This translation is handled automatically, UUY tsalthough the user may explicitly specify which of the possible Dylan types should be chosen for any given C object nteUUY rtype. In some cases, a further translation may take place, converting the low level Dylan value to or from some UUY asxarbitrary high level Dylan type. (For example, an    might be translated into a    or a orUUY ct} , and a    might be translated into a   .) These high level translations tUUY isare automatically invoked at the appropriate times, but both the target types and the methods for performing the lanUU@Y at+translation must be specified by the user. ofEUTU ` pa%Specifying low level transformations m:UU p tThe target Dylan type for low level translations is typically chosen automatically by Melange. Integer and enumerteFUUp onation types are translated into   ; floating point types are translated to   ; and all other types are e cRUUp n ltranslated into newly created subclasses of   . However, you may explicitly ow^UU@p e Vdeclare the target Dylan type for any C type by means of an  equate:  option: vUU`s  define interface UU q n>#include gc.h, UU@q ra$equate: {char * => }; ghUU`r to end interface; UU t el|This declaration makes the very strong statement that any values declared in C as  char *  are identical in form to meUUt ngxthe predefined type    (which is described in Appendix I). The system will therefore not define a disnsUUt }tinct type for  char *  and will ignore any structural information provided in the header file. You migh also use an eUUt pqequate: option to equate a type mentioned in one interface definition with an identically named type which was dUU@t re,defined in an earlier interface definition. y UU u onYou should use caution when equating two types. Since Melange has no way of knowing when two types are equivaUUu tyylent, it must trust your declarations. No type checking can or will be done, so if you incorrectly equate two types, the UUu rayresults will be unpredictable. In some cases, you may wish to go with the less efficient but slightly safer technique of mUUu ngwletting Melange create a new type and then mapping that new type into the desired type. (This is described in detail ned*UU@u ngbelow.) icBUU v ApwNote also that two types with identical purposes will not necessarily have identical representations. For example, Cs norNUUv nfxboolean types are simple integers and are not equivalent to Dylans   . Again, explicit mapping may be neZUU@v d5used to transform between these two representations. rUU w de In the current implementation, an  equate:  option only applies within a single interface definition. Other interface ~UUw whydefinitions will not automatically inherit the effects of the declaration. In future versions, we may add the ability to sd   + + d wi bHH  ho HHie//chnique + /UU crzfoo , and does not get a distinct class, although any extra levels of indirection (i.e.  struct foo ** ) will UU@ Sgenerate new pointer classes. Three operations are supported upon pointer classes: aveUU` nt o*UU` s3 pointer-value (pointer, #key index) => (value) teg6UU  [This function dereferences the pointer and returns the value. If index is supplied, then usBUU@ tw\ pointer  is treated as a vector of values and the appropriate element is returned. ZUU` oncontent-size (cls) => integer fUU  . jReturns the size of the value referenced by instances of  cls . If the size is not known, this is rUU@ si0. we UU  y rNote that these types are  not  automatically treated as vectors. You may, however, make them so by using a UU@ HA superclasses:  option to make them   s. UU`  UU  d yVector types  -- Declarations like  char [256]  are treated almost identically to pointer types, but they are UU prautomatically defined as subclasses of   , so that all vector operations will be defined on them. UU e hHowever, because many systems depend upon the lack of bounds checking in C, vector types have a default urUU@ ndjsize of  #f . You may explicitly define  size  functions to provide a more accurate size. UU` s  uUU  mStructure types  -- Declarations like  struct bar {int a; char *b;}  also generate new subclasses nUU kof   . Melange will define all of the operations defined for pointer valre UU tisues (described above), as well as accessors for each of the structure slots. Structure objects are always accessed ionUU UU  nUnion types  -- Declarations like  union bar {int a, char *b;}  are treated the same as struct decJUU@ Qlarations, except that the slot accessors all refer to the same areas in memory. tVUU` cc tbUU  gEnumeration types  -- Declarations like  enum foo {one, two, three};  are simply aliased to b;}nUU@ e T . However, constants are defined for each of the enumeration literals. wzUU` th pUU` oroTypedefs  -- Declarations like  typedef struct foo bar  simply define new names for existing types. . S5UTU h re!Specifying class inheritance UU  ntoWhen Melange creates new    classes, it typically creates them as simple subUU bjoclasses of   , with no other superclasses. However, you might sometimes need UU 2smore control over the class hierarchy. For example, you might wish to specify that a C type should be considered a areUU@ asnsubtype of the abstract class   . You could accomplish this via the following declarations: UU` define interface UU` io#include sequence.h; s UU` {(struct struct cons_cell => , to$UU` superclasses: {}; 0UU` d !function c_list_size => size; s<UU` end interface; UHUU`   -~TUU` e ;define method forward-iteration-protocol (seq :: ) exi}`UU` .... |xUU  ifvNote that the type    will still be a subclass of    -- we have sim{UU thvply added    to the list of superclasses. If    is not explicitly d#  , , e r e HH$  ho HHsh,, , ,UUw s  use  other interface definitions (just as you would  use  another module withing a module definition) and thus UU@w e bpick up the effects of the  equate : (and  map :) options within those interfaces. RU3TU `x {<&Specifying high level transformations PUU y =>tSometimes you may wish to use instances of some C type as if they were instances of some existing Dylan class, even er\UUy q sthough they have different representations. In this case, you can specify a secondary translation phase which semi- a hUUy stvautomatically translates between a low level and a high level Dylan representation. In order to do this, you must tUU@y tiprovide a map: option: sUU`{ define interface UU`| #include gc.h, UU } H$equate: {char * => }, hUU@} map: {bool => }; UU`~  end interface; UUU   vThis clause will cause any functions defined within the interface to call transformation functions wherever the origiUU@ e gnal C functions accept or return values of type  bool . Two different functions may be called: U UU` ifHimport-value (high-level-class :: , low-level-value :: ) shUU  ofs This function is called to transform result values returned by C functions into a high level Dylan class. It ffeUU@ ns@should always return an instance of  high-level-class . h UU` Hexport-value (low-level-class :: , high-level-value :: ) (UU  onj This function is called to transform high level argument values passed to C functions into the low 4UU ilevel representations which will be meaningful to native C code. It should always return an instance of @UU@ l low-level-class . ~XUU  rf|Default methods, which simply call  as , are provided for each of these functions. This will be sufficient to transnsdUU iform Cs integral  char s into   s,   s into other   s, or one pointer type into pUU al|another. There is also a predefined method which will transform   s into   s. However, if you r|UU neswish to perform arbitrary transformations upon the values, you may need to define additional methods for either or hUU@ nboth of these functions. For example, the default methods for transforming to and from    are: UU` fBdefine method export-value (cls == , value :: ) UU` t => (result :: ); leUU` nsif (value) 1 else 0 end if; tUU` ulend method export-value; UU`  ӊUU` Bdefine method import-value (cls == , value :: ) UU` p => (result :: ); ctiUU` su value ~= 0; nUU`  end method import-value; aUU z chIt is important to note that, unlike  equate:  options,  map:  options dont prevent Melange from creating new is $UUz mentypes. You may, in fact, both equate and map the same type. This will cause low level values to be created as 0UUz trvinstances of the equated type and then transformed into instances of the target type of the mapping. For example, <UU@z on[you might take advantage of the defined transformations between string types by declaring: TUU` nedefine interface e`UU` , '#include /usr/include/sys/dirent.h, =lUU` ge$equate: {char * => }, uexUU` t% map: {char * => }; -~UU`  end interface; Ud/  =bo- - f ) HH0  ;tiHHv,,` - od,UU` define interface oUU` , #include demo.h; ӨUU` :function bar, p*UU` m seal: open, 6UU` meequate-result: , th BUU` smap-result: , leNUU` re,input-argument: first,// passed normally ңZUU` thAoutput-argument: 2,// nothing passed in, second result value FfUU` // will be erUU` deBinput-output-argument: third;// passed in as second argument, ~UU` ne // returned as third result #UU` ud,function baz => arbitrary-function-name, uaUU` c-seal: sealed,// default tUU  ignore-result: #t, UU@  )equate-argument: {second => }, UU` =%map-argument: {2 => }; UU`  end interface; ti `  Struct and Union Clauses UU  oduStruct clauses and union clauses (referred to collectively as container clauses) are used to specify naming in tUU {inclusion of class slots in exactly the same way that the options in the file clause control the handling of global definict> UU xtions. Like the function clauses described above, they consist of the reserved word struct or union, a string which on,UU fxgives the full C name of the container declaration, an optional renaming, and a list of options. If we have a structure rg8UU@  defined by //PUU  rtypedef struct cons { \UU az int index; -fhUU struct object *head; tUU ulstruct cons *tail; UU@ # } cons_cell; UU` 1we could use the following interface definition: =UU` {2define interface UU` #include cons.h; tiUU` #struct struct cons => , UU` ucsuperclasses: {}, UU` tiprefix: c-list-, sUU` pe&name-mapper: identity-name-mapping, UU` loexclude: {index}; UU` s  end interface; ntrUU  gValid options for container clauses include:  import: ,  prefix: ,  exclude: ,  rename: ,  seal-functions: , , a(UU ,read-only: ,  equate: , and  map:. These options act like the equivalent options which may be specified in a file u4UU zclause, but they apply to the slots of a single class rather than to globally defined objects. Options specified within @UU@ heqa container clause override any global defaults that might have been specified in the  #include  clause. uXUUl nt`Container clauses also permit the superclasses: option described in section  6.2. hӁpUU  wAlthough the recommended method for specifying a container type is to use the full C name (i.e.  struct foo ), ref|UU lyou may also use an alias defined by a typedef. Thus, in the above example, you could have specified either dg  . . g ntneHHh  f:HH %%-functio . (%UU  y:This causes the system to automatically translate  char *  pointers into   s (i.e. a particular variety of UU thwstatically typed pointer) and then to call  import-value  ot translate the    into a   . If we did not provide the  equate:  option, then we would have to explicitly provide a function to Co*UU so~transform pointers to characters into   s. The  equate:  option lets us take advantage of all of 6UU@ cgthe predefined functions for   s, which includes transformation into other string types. o uY ` d Other File Options n txUU  yo~ There are a few other options that may be specified within an  #include  clause, but which do not fit into any of UU xthe above categories. These options are  define: ,  undefine: ,  seal-functions:  and  read-seUU@ to only: . slUU  The  define:  and  undefine:  options control the C preprocessor definitioins which will be implicitly defined allUU  {during parsing of the header files. If you specify neither of these options, Melange will use a default set of definitions eqUU  txwhich correspond to those used by a typical C compiler for the machine you are running on.  The define options takes 4.3}, s UU@ undefine: {HPUX}; ,UU` : end interface; DUU  in{ The  seal-functions:  option controls whether the various imported functions and slot accessors will be sealed UPUU armor open. By default, functions are sealed, but you may explicitly specify this by using  seal-functions: s\UU zsealed  or reverse it by using  seal-functions: open . Melange does not support the Creoles  inline  hUU@ sealing option. taUU  ok} The  read-only:  option specifies whether setter functions should be defined for slot and object accessors. They cUU@ ildwill be defined by default, but if you specify  read-only: #t , no setters will be defined. UU  on{ The effects of the  seal-functions:  and  read-only:  options can be modified for particular container UU@ PM;types. We will explain how to do this in a later sections. ine `  Function Clauses nUU  u Imported functions can be easily invoked, in almost every case, without any additional declarations. However, by rUU uexerting explicit control over argument handling, the interfaces to some functions may be made cleaner. This control - UU xis exerted via function clauses. The primary purpose of these clauses is to specify additional type information for speUU tcific parameters or to specify alternative argument passing conventions. For example, if we had two alternate read-ct"UU@ in5integers functions with the following declarations: :UU` neGint ReadInts1(int **VectorPtr); /* result is a count of integers */ beFUU` J int *ReadInts2(int *Count); /* result is a vector of integers */ ^UU` s 5 we might use the following interface definition: d  ts / / h  HH  HH% f((nvoked, / y (UU` aldefine interface vUU` #include readints.h, t UU` en#rename: {int * => int-vector}; nct*UU` lefunction ReadInts1 6UU` isoutput-argument: 1; BUU` /function ReadInts2 => Read-Integers-Vector, typNUU` spoutput-argument: Count; iZUU` to end interface; argrUU  env This would produce two functions, both of which take 0 arguments but return two values. The first would return an ~UU {  following by an   , while the second would return the    first and the intUU@ re  second. ersUU  2let (count :: , values :: ) UU@ d= Read-Ints1(); UU  6 let (values :: , count :: ) UU@ = Read-Integers-Vector(); UU  okz The function clause consists of a function name (which is a string), an optional renaming (as illustrated above), and UU@ naFan optional sequence of options. The options include the following: UU  seal:  -- specifies whether the resulting method should be sealed. Possible values are  sealed  or  open , and the UU@ Zidefault is taken from the value specified in the initial file clause. (The default default is sealed.) UU  enuequate-result:  -- overrides the default interpretation of the result type. The named type is assumed to be fully r&UU@ se defined. r2UU` -vmmap-result:  -- specifies that import-value should be called to map the result value to the named type. >UU  ::tignore-result:  -- specifies that the functions result value should be ignored, just as if the function had been : JUU@ `declared void. Although you may specify any boolean literal, the only meaningful value is #t. oVUU  (woequate-argument:  -- overrides the default interpretation of some arguments type. The argument may be spec obUU@ nsified by name or by position. nUU  :mmap-argument:  -- specifies that export-value should be called to map the given argument into the named zUU@ Ctype. Again, the argument may be specified by position or by name. l fUU` deminput-argument:  -- indicates that the specified argument should be passed by value. This is the default. UU  hesoutput-argument:  -- indicates that the specified argument should be be treated as a return value rather than a s tUU snparameter. The effect is to declare that the C parameter will be passed by reference and that the reference UU nsqvariable need not be initialized to any object. This option assumes that the C parameter will have been declared UU y sas a pointer type, and will strip one * off of the argument type. Thus, if the parameter declaration specifies lt UU@ soh int ** , the actual value returned will have the Dylan type corresponding to  int * . UU  arpinput-output-argument:  -- indicates that the specified argument should be considered both an input argument UU aiuand that its (potentially modified) value should be returned as an additional result value. The effect is similar to UU@ mejthat of output-argument except that the reference variable will be initialized with the argument value. UU` at The following (nonsensical) example demonstrates all of the options, as they might be applied to the functions: clUU` amIextern struct object *bar(int first, int *second,struct object **third); s"UU` t 3 extern baz(char first, struct object *second); t td5  0 0 i rypHH6  ntyHH9et lt 0 soUU  tuyseal:  -- specifies whether the getter and setter functions should be sealed. Possible values are  sealed  or :UU thx open , and the default is taken from the  seal-functions:  option in the  #include  clause (or diUU@ b* sealed  if not specified there). *UU` r Rmap:  -- specifies the high-level type to which the variable should be mapped. 6UU` izeequate:  -- specifies the low-level type to which the raw C value should be implicitly converted. aH'  tH'% amexTUTU$S *In fact, a C header file may contain arbitrary C code which Melange is unprepared to handle. By convention, however, .h files conRUTUS  tain only interface declarations -- type declarations, function prototypes, global variable declarations, and preprocessor constants. PUTUS Since Melange can meaningfully process all of these, it is capable of handling the vast majority of header files which will be encounNU#TUDS  tered in practice. d  k f1 1 j s:HH   odiHH&&ecified 1 &UU@ spF struct cons  or  cons_cell , with identical results. ) ` eqPointer Clauses fiHUU  ypxPointer clauses modify the definitions of pointer declarations such as int * or struct foo ***, or vector declara'TUU amytions such as char [256]. Like all such clauses, they may be used to specify renamings for the classes. This is partico`UU pularly useful for pointer types since they are not automatically assigned user-meaningful names. It also allows , lUUL clbspecification of the superclasses: option described in  6.2. A typical use might be: UU` isdefine interface gUU  o#include vec.h; wilUU@ "pointer int * => , UU` superclasses: {}; UU` )pointer struct person ** => , UU` Hsuperclasses: {}; UU` )pointer char [256] => ; UU` end interface;  杪UU  rzThis clause is particularly useful for declaring pointer types to be subclasses of    so that they can be UU vindexed via  element . (Note that this is not necessary for vector declarations, since they are automatically UU@ to%declared to be   .) s+ ` Constant Clauses yJUU  r rConstant clauses are used to override the values of constants specified in header files (i.e.  #define MAXINT VUU pe}27 ). The  value:  option, which is the only one supported, specifies a Dylan literal which will be taken as the bUU@ ec5value of the named constant. A typical use might be: vzUU` define interface aUU  ; #include const.h; pUU so.constant MAXINT => $maximum-fixed-integer, UU@ orvalue: 9999999; UU` arend interface; -st ` Variable Clauses fUU  yGlobal variables declared within C header files are translated into getter functions which retrieve the value of the C yUU {variables and optional setter functions to modify those values. In effect, they are treated as slots of a null object -ly UU tox-the getter function takes no arguments and returns the value of the variable, while the setter function takes a single uUU e svalue which will be the new value of the variable. Type mapping takes place for the arguments and results of these e:UU@ i0functions, just as it would for slot accessors. l 4UU`  n 0Variable clauses support the following options: onLUU`  _getter:  -- specifies a Dylan variable name which will be used to hold the getter function. XUU   c|setter:  -- specifies either a Dylan variable name which will be used to hold the setter function, or  #f  to indidUU@  Va.cate that there should be no setter function. pUU   thwread-only:  -- specifies whether the variable should be settable.  read-only: #t  is equivalent to  setes |UU@  erter: #f . d8  ad 2 2 k y HH9   tesHHorn&&ble, whi2 fu& ` Low level support facilities i*UU   e xThe high level functions for calling C routines or for accessing global variables are all built upon a relatively small as6UU  asnumber of built-in primitives which perform specific low-level tasks. You should seldom have any need to deal with --BUU@  vcthese primitives directly, but they are nonetheless available should you need to make use of them. speZUU`J labTo use these types and operations, you should use the module extern from the Dylan library. PU{TU ` t Predefined types sUU` p#[class] pecUU  vaoUnless otherwise specified, C pointers are implicitly equated to newly created subclasses of   . This class is contains a single implicit slot which contains the raw C pointer. Because of impleUU gmentation limitations in Mindy, you may not add any extra slots to subclasses of   , nor can such a subclass inherit slots from other classes. You may, however, create classes which are subUU@ erpclasses of both    and other (presumably abstract) classes which have no slots. BUU  thThe  make  method for takes three keywords. The  pointer:  keyword tells it to initialize the new variable with heUU tixthe given value, which must be a    or an   . If the no pointer value is UU tyxspecified, space will be allocated based upon the content-size of the specific type and upon the  extra-bytes:  atUU pand  element-count:  keywords. These keywords, which default to 0 and 1 respectively, tell how many ai(UU ersobjects are going to be stored in the memory and how many bytes of extra memory (beyond that specified by  cones 4UU@ -t6tent-size ) should be allocated for each element. LUU` t [class] sesdUU  , l  is a subclass of    which inherits operations from . thpUU tr}Because systems often depend upon Cs lack of bounds checking, the default size for   s is  #f . How|UU i{ever, subclasses of    may provide a concrete size if desired. Types corresponding to declarations such as  攪UU erc har [256]  are automatically declared as subclasses of   , but pointer declarations such as  char ecUU@ t*  are not. s:UU` [class] emeUU  wog  is a subclass of    which also inherits operations from ectUU sts . It is implemented as a C pointer to a null-terminated vector of characters, and provides a method on t-sUU e mforward-iteration-protocol  which understands this implementation. This class may, therefore, be used for UU  s accepts the  size:  and  fill:  keywords. a0UU  revThere are a few surprising properties of    which may users should be aware of, both of which result <UU |from the null-terminated implementation. Firstly, the  size  of the string is computed by counting from the begino HUU s rning of the string, and is therefore not nearly as efficient as you might expect. Secondly, you should expect odd TUU m}results if you try to store  as(, 0)  into such a string. Finally, the  element  and  element-r`UU wsetter  methods must scan the string in order to do bounds checking, and may therefore be fairly slow. If you wish nsilUU@ d Rto (unsafely) bypass this checking, you must use  pointer-value  instead. d;   r 4 4 l rocod&   r 3 3 Z e HH'   a0HHe  perties 3 ng UU ulsnot be accepted by Melange) You should, therefore, not expect Creole interface declarations to work within Melange sUU@ riwithout some modification. om 5 ` A Concrete Example thTUU  hexIn order to get a feel for using Melange, it is probably best to start with a concrete example. This section contains a ry`UU [class] oUU  ral s, like   s, encapsulate a raw C pointer. However,   s also encode information about the calling conventions of the function which is (presumably) located at 6UU@ ryZthe given address. They may, therefore, be directly invoked just like any other function. NUU` ie[class] fUU  n wThe class is used to store information about the contents of a particular object file. It is created by xrUU lavload-object-file, and may be passed as an option to find-c-function and find-c-pointer. (All of these functions ~UU@ e are described below.) LUTU ` whLocating native C objects UU  ttThere are several functions provided which search for C functions or variables and return Dylan objects which refer UU uto them. Note that Mindy does not have sufficient information to determine whether any given C object is a function, yUU@ eiand therefore it depends upon the user (or, more often, Melange) to provide it with correct information. nUU`  c;load-object-file(files :: , #key symbols)[function] 6UU ) thpThis function (which is presently only works on HPUX machines) attempts to dynamically load a given object file eiUU) u(i.e. .o or .a) into the current Mindy process and load its symbol table to allow its contents to be located by iUU) byx find-c-pointer  or  find-c-function . If it successfully loads the file, it will return a    encapsulating the symbol table information. Otherwise, it will return  #f . @UU * ThuIf you are not running on an HPUX machine, you will have to statically link object files into Mindy, as described in LUU@* to Appendix II. tdUU` veFfind-c-pointer(name :: string, #key file ::   and returns it. Otherwise, it returns  #f . UU`" dy9find-c-function (name :: , #key file)[function] oUU`$ 7constrain-c-function (fun :: , [function] -fuUU`% s,specializer :: , rest? :: , UU`# results :: )  UU ( sy~The function  find-c-function  is like  find-c-pointer , except that the result is a    (or UU( stp#f ). The resulting function is specialized to  fun(#rest args) ::  . However, it may be confiUU( ::ystrained to a different set of specializers via  constrain-c-function . This function accepts lists of types for h UU( essthe arguments and for the return values, and a boolean value which states whether optional arguments are accepted. venUU( swThe result declarations are particularly important, since they are used to coerce the raw C result value into an approurn$UU( t }priate low level Dylan type. The possible types are   ,   , or any subclass of   . Note that although a list of result types is accepted, only the first can be meaningful since C <UU@( t>)does not support multiple return values. TUU`& ]Note : The functions in this section are likely to change drastically in the near future. d>  ois5 5 m re aHH?  ofiHHust))t of spe5 )TU TU `/  Pointer manipulation operations yp&UU 0 wEach encapsulates a pointer to some area of memory (i.e. a raw machine address). In itself, ed.2UU0 (tthis does little good, except as an arbitrary token. However, Mindy provides a number of primitive operations which a>UU@0 rmanipulate the contents of these addresses, or do basic comparisons and arithmetic upon the addresses themselves. VUU`1 -rKsigned-byte-at (ptr :: , #key offset)[function] tybUU`2 nlMunsigned-byte-at (ptr :: , #key offset)[function] mnUU`3 ueLsigned-short-at (ptr :: , #key offset)[function] o zUU`4 iNunsigned-short-at( ptr :: , #key offset)[function] UU`5 aKsigned-long-at (ptr :: , #key offset)[function] UU`6 ofMunsigned-long-at (ptr :: , #key offset)[function] nUU`7 0;pointer-at (ptr :: , [function] to UU`9 y #key offset, class) rUU 8 d.yThese operations return an object which represents the value stored at the address corresponding to ptr. The first six eUU8 >voperations all return s -- the different versions are required because the same number may be represented in UU8 $ta variety of formats (differing in length and interpretation of the high-order bit) and because Mindy has no way of gnUU8 encapsulating the address referenced by the origninal pointer. You may use the class: keyword to UU8 sixspecify that the new object should be an instance of some particular subclass of . (Thus, for < UU@8 oifexample pointer-at(foo, class: ) would be roughly equivalent to as(, pointer-at(foo)).) "UU : vThe offset parameter (if provided) is added to the integer corresponding to the machine address before the pointer is .UU@: ssZdereferenced. This is useful, for example, in loading an object from within a C struct. FUU`; t dSetter functions are provided corresponding to each of the above functions. You can therefore, say f^UU`< insigned-short-at(ptr) := 32767; hijUU`= bepointer-at(ptr1) := ptr2; vUU`H < eUU`M ghFas(cls == , ptr :: )[G.F. Method] UU`> lyIas(cls == , ptr :: ) eUU`P p[G.F. Method] se UU`O rdEas(cls == , int:: )[G.F. Method] aUU N ultMethod upon as are provided for converting from to any statically typed pointer class and from any statwoUU@N ivVically typed pointer class to or to another statically typed pointer class. UU`? toG\+ (ptr :: , int :: )[G.F. Method] .UU`@ deK\- (ptr1 :: ) sUU`Q [G.F. Method] funUU`I d K\= (ptr1 :: ) UU`A ed[G.F. Method] 32*UU`B qThese functions do arithmetic upon the integers corresponding to the given pointers. The following code fragment iBUU`C r>let new-ptr = ptr1 + 3; NUU`D = let difference = ptr2 + ptr3; ZUU`K edlet same? = (ptr2 = ptr3) rUU`E d]is equivalent to H o   t:H ho TUTUd po9This requires you to have PERL installed on your system. ad  awo6 6 n lyypHH  atHH!laG\+ (pt6 lyUU`F nt>let new-ptr = as(ptr1.object-class, as(, ptr1) + 3); UU`G r,<let difference = as(, ptr2) - as(, ptr3); [UU`L 8let same = (as(, ptr2) = as(, ptr3)); trH$     H$  l =ionHM      dg HM  l >Ud3  7 7 p p2 HH4   p2 HH~EH 7  `' HStatic linking mechanisms *UU  sBecause object file formats vary widely by architecture, Mindy does not support dynamic loading of object files or 6UU yautomatic symbol table look up for all architectures. In the general case, it is necessary to depend upon a less elegant BUU@ >technique for explicitly making certain C objects available. ZUU, xSimple instructions for using this mechanism from within Melange are given in section  3.1.  This appendix simply , fUU@ r>7provides more information on the underlying mechanism. ~UU  uIn order to make sure that the desired symbols can be located, it is necessary to build an explicit table which maps UU ubetween the symbols name and its address. This table is automatically created by running the  make-init.pl  UU  pnscript upon a list of interface definition files. This will create two files  ,extern1.def  and UU s | ,extern2.def , which should then be renamed to  extern1.def  and  extern2.def  respectively. These t UU@ sfiles are automatically included by  ext-init.c  so that the table will be created after Mindy is rebuilt. on UU  BsThe interface definition files consist of zero or more lines of text, each of which should contain the name of one ionUU ecvobject. If the object is a function, it should be immediately followed by a set of parentheses. For example, the file UU@ uowhich defines the memory allocation routines used by Melanges support code contains the following four lines: s nUU` anfree() taUU` malloc() UU` sy strcmp() UU`. hi strlen() a2UU [ edwThe only other step required to make the objects available is simply to ensure that the library which contains them is s w>UU[ esxlinked into Mindy. The easiest way to accomplish all of this is to simply modify the  Makefile  in Mindys source  JUU[ n2}directory. If you add the names of the required libraries to  LIBS  and the names of the interface definition files to eVUU[ ftuEXTERN-INCLUDES ,  make  will do the necessary work for you. You should be sure to leave . ./compat/libhbUU@[ ondcompat.a  or  -lm  in  LIBS  and  malloc.inc  in  EXTERN-INCLUDES . atd  xpl8 8 q uHH   n uHHrtwing fou8  ` taDifferences from Creole oc*UU \ tIt would be difficult to produce an exhaustive list of the differences between Creole and Melange. We can, however, a6UU@\ t^include a brief examination of the most important incompatibilities between the two systems. NUU`] cooCreoles  type:  options have been replaced by Melanges  equate:  and  map:  options. If ZUU d ofcCreoles access path options have been replaced by  object-file:  and  mindy-include-UfUU@d NC file: . mrUU`b e cThe interface to  import-value  and  export-value  differ between the two systems. a ~UU`^ LMelange does not inherit type mappings from other define interface forms. UU _  lCreole does not import definitions from recursively included header files, even if they are referenced by UU@_ (definitions which  are  imported. UU`` NCreole does not support C vectors or sub-structures as first class objects. UU a ve]Melange does not presently support callbacks,  export-temporary-value ,   ,  with-stack-structure ,  with-stack-block , or  alien-method . ҞUU c iovCreole will never consider instances of two distinct statically typed pointer classes to be  = , even if they UU@c avrefer to the same address. t-fd  9 9 r rHH   vueHHuvathe two 9 ~ `+ doKnown limitations *UU e r iAlthough mostly complete, the current implementation of Melange is missing a few elements which might be u6UU@e eyrequired for some applications. The following capabilites probably  should  be present, but are not yet supported: eNUU`f C Floating point numbers. ZUU`i ec Callbacks. UfUU h doaFunction types. (It is, however, possible to import a function as a simple    and then manipulate it like any other object.) dK  oCr: : s nsncHHL   asHHg e!!@c av:  s! `, dProposed modifications *UU - 9 qAlthough Melange seems to be fairly useful in its present form, we are currently considering a number of ways in 6UU- uwhich it may be made more useful. This section contains a brief discussion of several potential changes which may be nBUU@- isimplemented in the future. miQUcTU `g Enumeration clauses sUU k ThvAt present, there is no way to modify the default handling of a C enumeration declaration. It is clear that you might UUk Zxwish a mechanism to specify several different explicit options: prefixes for the enumeration constants; respecification siUU@k ly_of constant values; and, of course, explicit  import:  and  exclude:  options. LUTU `l  *Inheritance of map and equate options UU m pThere are some cases in which a set of types imported within one interface definition might be used extensively !UUm dpwithin another. In the present implementation, the two interface definitions would be handled independently and weUU@m sijequivalences between types would not be recognized in the abscence of explicit  equate:  options. UU n f zOne proposed solution would involve the ability to explicitly  use  one interface definition within another. This UUn would result in all identically named types being implicitly equated and all top-level  map:  options being inherited. ht UUn ZThe  use  clause could support roughly the same syntax as the  use  clauses in library and module definitions.In *UUn onworder to make this work, it would be necessary to assign arbitrary names to interface definitions. This would have the anc6UU@n uaZadded benefit of making them more consistent with other standard Dylan definition forms. NUU`o efiIf this change were implemented, a typical interface definition might look something like the following: efUU`p indefine interface date rUU`q we#include date.h; eq~UU`r t$use time, import: {struct time}; scUU`s  end interface date; . UU j f qA less ambitious version might remain compatible with the current syntax by replacing the interface name with an eUU@j Qinterface-name option, which would default to the root of the file name. Thus, aUU` madefine interface nUU` #include date.h, UU` cinterface-name: date; UU` end interface; inUU` e 5would yield the same effect as the previous example. s6U#TU `t n.Remerging of the equate: and map: options @UU u wotIt has been pointed out that the current method of specifying low-level and high-level mappings, while sufficiently n LUU@u lexpressive, is somewhat verbose and confusing. It would therefore be good to find an alternative notation. indUU`v p-It has been suggested that definitions like: eH  tuHuc  scTUTU$ en}Currently support is primarily for HPUX machines, but some work has been done on Macintoshes and ELF systems. Contact us for RUTUD wmore details. d}  hou; ; t thfiHH~   entHH), ;  cUU`w ; define interface UU x in#include dirent.h, UUx e$equate: {char * => }, *UU@x rg$map: {char * => }; s 6UU`y woend interface; nteNUU`z re%might be replaced by something like: ifUU`{ wdefine interface rUU`| #include dirent.h, ~UU` us=equate-and-map: {char * => => }; .UU`} vend interface; suUU` itor likUU` define interface UU` #include dirent.h; UU  transform char *, pUU@ orlow-level: , rUU` Mhigh-level: ; tUU` end interface; e dUU` d &UU`~  HH   HHHl ?H+      cH+  l @xH       eH  l AHH   HHl BplaHH  wdeHHl C~HH!  *=>HHl3 DerfHH"  HHl3 # DdirHH#  h *HHl" $ DUHH$  HHl# % DHH%   HHl$ & DHH&    HHl% ' DHH'    HHl& ( DHH(   HHl' ) DHH)   HHl( + DHH*   HHl+ , DHH+   HHl) * DHH,   HHl* . DHH-   HHl/ 1 DHH.   HHl, / DHH/   HHl. - DHH0   HHl1 2 DHH1    HHl- 0   DHH2    HHl0 4   DHH3    HHl! "   DHH4    HHl2 5 DHH5   HHl4 6 DHH6   HHl5 7   DHH7    HHl6 8   DHH8    HHl7 9   DHH9    HHl8 :   DHH:    HHl9 ;   DHH;    HHl:   DU u o dU LeftdV W RightdW V " FirstdX  ReferencedY Z FirstdZ Y [  Hd[ Z \  d\ [ ] d] \ ^ Hd^ ] _ d_ ^ ` ld` _ a  da ` b  d b a d d c d e 8 d d b c d e c g df h j  d g e h  dh g f Hdi j k : dj f i  dk i l  Hdl k m  dm l n dn m p Hdp n q  dq p r  dr q s  ftdds r t  dt s  " Ed f  * AbstractBody.  f  *  -u In 1 Bullet \t. f  *Centered. f E * Equation NumE:(). f F *  Figure Capt F:Figure . f  *Footnote.  f HQ *  Heading 1H:. Body. 1 f P *\ In 1 Number1 P:.\t. f T *  TableTitleT:Table : . f  * CellHeading. f  *CellBody.  f HQ *  Heading 3H:... Body. f HQ *  Heading 4H:.... Body.  f   -u In 1 Bullet\t. 6$$f  *6 In 2 Bullet\t.  T $ 6l CodeCode. 66$ f  *In 2. 66$ f  *In 2. f  *In 1. 61$ f P *6 In 2 Number P:< >.\t. 61$ f P *6 In 2 Number1 P:< >.\t. QQ6 f  *In 3. Q?6 f  *Q In 3 Bullet\t. Q1:6 f P *Q In 3 NumberP:< >< >.\t. Q1:6 f P *Q In 3 Number1P:< >< >.\t. llH f  *In 4. lZH f  *l In 4 Bullet\t. l1UH f P *l In 4 NumberP:< >< >< >.\t. l1UH f P *l In 4 Number1P:< >< >< >.\t.  f T *  Table Capt T:Table .  f P * TitleCentered.  t $6lCodeCode. f  In 1. 1f P * In 1 Number P:.\t. 1f P * In 1 Number P:.\t.  f P * TitleCentered. Pf  *Centered. 0 f  *  AbstractHead. f  * AbstractBody.  f HQ *  Heading 1>H:. Body.  T  N$6n.\l  TableTitleCode.  T $6lCellBodyCode. f  *Body.  f HQ *  Heading 2 H:.. Body. f  *Body. f  *  Body. f  *  Body.  f HQ *  Heading 2 H:.. Body. f  *CellBody. f  *CellBody.  f AQ *  Appendix 2 A:.. Body.  f AQ *  Appendix 2 A:.. Body.  T z Interface Interface.  T ~z Interface Interface.  T z Interface Interface.  f AQ * AppendixA:Appendix -- Body.  f AQ * AppendixA:Appendix -- Body.  f  *  - u In 1 Bullet\t.  f  * - In 1 Bullet\t.   D $6lCode EndBody.  T H Interfaced Interfacex. 6$$f  *6 In 2 Bullet\te. R+1f P * In 1 Number1 P:.\t. f  *In 1. 1f P * In 1 Number1 P:.\t.  T $6l CodeCode.   D $ 6lCode EndBody.  T z InterfaceCode. f   *Footnote.   Vz * Vz *  *  Emphasis 2  *  *  * Big 1  * Big 2 * Big 3 h * _  * *Body *Emphasis *  Emphasis 2  Fixed-Width  Fixed-Width Bold Fixed-Width Italic *Italic *Small * SubscriptVz * Superscript )Symbol* Vz *Bodyh *h *Body _  Fixed-Width *  *EquationVariablesVz * h *Emphasis_  Fixed-Width - $       e  !  "  #  i  Thin Medium Double* malThick@  Very Thin bs    !  H H H hH H Format A  H H H H H Format B  H H H H H eFormat A   !   - " H]         *Ho        H$     ble   H@   ! Tn     H!    !  ! uvu  CommentU e Y U H V  iW A FoX B Y C  d Black !T White ddA HRed dd Greenodd Blued Cyan d Magenta d Yellow W.Times.I.400 Times-Italic W.Times.R.400 Times-Roman W.Times.R.700 Times-BoldW.Courier.R.400CourierW.Courier.R.700 Courier-BoldW.Courier.I.400 Courier-ObliqueW.Symbol.R.400Symbol7Courier)Symbol*Times Regular Regulare BoldItalicRegularObliqueY22le:.UrPvlL-mwtSDzOeS\h5O!wʺ?i\`"J.13nj^& s _DWkۥ\FlBv/[!b85bCX*Jp/7~r;A` ̑)&D 99o$bH3x?v[cX|dJăMa Zm>gk2?&S2 ot $'3\.4?N7%B˻1i7 ncɖv(evh"g IDK{v ܿiyLV~JS[Cǘۋ= Y2q t{,绊 ңI4Eu{,v$}=NlS UK% &=b);i0:JΊ0͂.zWRIzkE!wa`lU>ߌ ;L$b