Subject: [clisp-list] RE: FFI with complex numbers?

From: "Goffioul Michael" <[email-masked]>
Date: Wed May 12 09:09:05 2004

> Did you look here: <http://clisp.cons.org/impnotes/modules.html>?
> If you did, I don't see how you can call it "undocumented".

I did.

> If you did not, you might want to say "I cannot find the 
> documentation"
> instead of "undocumented" next time.

I meant a documentation about the interface as found in clisp.h,
which is not documented in the implementation notes, or at least
I couldn't find any doc that could have led me to the code example
that was proposed a few hours ago.

Michael.

---

From: Sam Steingold <[email-masked]>
Date: Wed May 12 10:54:08 2004

> * Goffioul Michael <[email-masked]> [2004-05-12 18:06:10 +0200]:
>
> I meant a documentation about the interface as found in clisp.h, which
> is not documented in the implementation notes, or at least I couldn't
> find any doc that could have led me to the code example that was
> proposed a few hours ago.

I see - I misunderstood you.

Indeed, there is no documentation about <clisp.h>, you have to read the
code.

Maybe you could record your experiences putting together your
module which could be later turned into <clisp.h> documentation?

Here is a start:

--- impext.xml	11 May 2004 17:45:25 -0400	1.225
+++ impext.xml	12 May 2004 13:52:40 -0400	
@@ -1945,7 +1945,7 @@
 <itemizedlist>
   <listitem><simpara><filename>modules.d</filename></simpara></listitem>
   <listitem><simpara><filename>modules.c</filename></simpara></listitem>
-  <listitem><simpara><filename>clisp.h</filename></simpara></listitem>
+  <listitem><simpara><link linkend="clisp-h"><filename>clisp.h</filename></link></simpara></listitem>
 </itemizedlist>
 <command>clisp-link</command> expects to find these files in a
 subdirectory <filename>linkkit/</filename> of the current directory.
@@ -2197,6 +2197,33 @@
   <link linkend="gc-safety">GC-safety</link>.</para></warning>
 </section>
 
+<section id="clisp-h"><title>clisp.h</title>
+
+<para>If your module is written in &c-lang;, you will probably want
+ to <literal>#include "clisp.h"</literal> to access &clisp; objects.
+ You will certainly need to read <filename>clisp.h</filename> and
+ <link linkend="included-modules">included modules</link>, but here are
+ some important hints that you will need to keep in mind:
+<itemizedlist>
+ <listitem><simpara>Lisp objects have type <type>object</type>.
+ </simpara></listitem>
+ <listitem><simpara>Variables of this type are invalidated by
+   <link linkend="gc-safety">memory allocation</link> and must be saved
+   on the &STACK; using macros <function>pushSTASH()</function>,
+   <function>popSTACK()</function> and <function>skipSTACK()</function>.
+ </simpara></listitem>
+ <listitem><simpara>Access object slots using the
+   approprate <function>TheFoo()</function> macro, e.g.,
+   <function>TheCons(my_cons)-&gt;Car</function>, but check the type
+   first with <function>consp()</function>.</simpara></listitem>
+ <listitem><simpara>Arguments are passed on the &STACK;, as illustrated
+   in the <link linkend="modprep">above example</link>.</simpara></listitem>
+ <listitem><simpara></simpara></listitem>
+</itemizedlist>
+</para>
+
+</section>
+
 <section id="exporting"><title>Exporting</title>
 <para>If your module uses &ffi-pac; to interface to a &c-lang; library,
  you might want to make your module package

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Microsoft: announce yesterday, code today, think tomorrow.