Merge branch 'jpellegrini-doc-ffi'

egallesio · Aug 23, 2024 · f17baf5 · f17baf5
2 parents 19cfff9 + dc6f41a
commit f17baf5
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 4 deletions.
diff --git a/doc/HTML/stklos-ref.html b/doc/HTML/stklos-ref.html
@@ -1351,8 +1351,27 @@ <h3 id="_procedures">2.2. Procedures</h3>
 </div>
 </div>
 <div class="paragraph">
-<p>Returns <code>&#35;t</code> if <code>obj</code> is a procedure created with the <code>lambda</code> syntax and
-<code>&#35;f</code> otherwise.</p>
+<p>Returns <code>#t</code> if <code>obj</code> is a procedure created with the <code>lambda</code>
+syntax and <code>#f</code> otherwise.</p>
+</div>
+<div class="paragraph">
+<p>Note that primitive procedures (those which are written in C) are
+<strong>not</strong> closures:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="rouge highlight"><code data-lang="scheme"><span class="p">(</span><span class="k">define</span> <span class="p">(</span><span class="nf">cube</span> <span class="nv">x</span><span class="p">)</span> <span class="p">(</span><span class="nb">*</span> <span class="nv">x</span> <span class="nv">x</span> <span class="nv">x</span><span class="p">))</span>
+<span class="p">(</span><span class="nf">closure?</span> <span class="nv">cube</span><span class="p">)</span>               <span class="nv">=&gt;</span> <span class="no">#t</span>
+
+<span class="p">(</span><span class="k">define</span> <span class="nv">square-root</span> <span class="nv">sqrt</span><span class="p">)</span>
+<span class="p">(</span><span class="nb">eq?</span> <span class="nv">square-root</span> <span class="nv">sqrt</span><span class="p">)</span>        <span class="nv">=&gt;</span> <span class="no">#t</span>
+<span class="p">(</span><span class="nf">closure?</span> <span class="nv">square-root</span><span class="p">)</span>        <span class="nv">=&gt;</span> <span class="no">#f</span>
+
+<span class="p">(</span><span class="nf">closure?</span> <span class="mi">10</span><span class="p">)</span>                 <span class="nv">=&gt;</span> <span class="no">#f</span>
+<span class="p">(</span><span class="nf">closure?</span> <span class="nv">display</span><span class="p">)</span>            <span class="nv">=&gt;</span> <span class="no">#f</span>
+<span class="p">(</span><span class="nf">closure?</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nf">x</span><span class="p">)</span> <span class="p">(</span><span class="nb">-</span> <span class="nv">x</span><span class="p">)))</span> <span class="nv">=&gt;</span> <span class="no">#t</span>
+<span class="p">(</span><span class="nf">closure?</span> <span class="nv">any</span><span class="p">)</span>                <span class="nv">=&gt;</span> <span class="no">#t</span></code></pre>
+</div>
 </div>
 <div class="paragraph">
 <p><a id='P_case-lambda'></a>
@@ -19818,6 +19837,14 @@ <h3 id="_misc">4.22. Misc</h3>
 If <code>proc</code> formal parameters are not available, <code>procedure-formals</code>
 returns <code>#f</code>.</p>
 </div>
+<div class="listingblock">
+<div class="content">
+<pre class="rouge highlight"><code data-lang="scheme"><span class="p">(</span><span class="nf">compiler:keep-formals</span> <span class="no">#t</span><span class="p">)</span>
+
+<span class="p">(</span><span class="k">define</span> <span class="p">(</span><span class="nf">f</span> <span class="nv">x</span> <span class="nv">y</span><span class="p">)</span> <span class="p">(</span><span class="nb">+</span> <span class="p">(</span><span class="nb">*</span> <span class="mi">3</span> <span class="nv">x</span><span class="p">)</span> <span class="nv">y</span><span class="p">))</span>
+<span class="p">(</span><span class="nf">procedure-formals</span> <span class="nv">f</span><span class="p">)</span>           <span class="nv">=&gt;</span> <span class="p">(</span><span class="nf">x</span> <span class="nv">y</span><span class="p">)</span></code></pre>
+</div>
+</div>
 <div class="paragraph">
 <p><a id='P_procedure-source'></a>
 </p>
@@ -19838,6 +19865,14 @@ <h3 id="_misc">4.22. Misc</h3>
 &lt;&lt;"compiler:keep-source"&gt;&gt; is set at its creation. If <code>proc</code> source is
 not available, <code>procedure-source</code> returns <code>#f</code>.</p>
 </div>
+<div class="listingblock">
+<div class="content">
+<pre class="rouge highlight"><code data-lang="scheme"><span class="p">(</span><span class="nf">compiler:keep-source</span> <span class="no">#t</span><span class="p">)</span>
+
+<span class="p">(</span><span class="k">define</span> <span class="p">(</span><span class="nf">f</span> <span class="nv">x</span> <span class="nv">y</span><span class="p">)</span> <span class="p">(</span><span class="nb">+</span> <span class="p">(</span><span class="nb">*</span> <span class="mi">3</span> <span class="nv">x</span><span class="p">)</span> <span class="nv">y</span><span class="p">))</span>
+<span class="p">(</span><span class="nf">procedure-source</span> <span class="nv">f</span><span class="p">)</span>           <span class="nv">=&gt;</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nf">x</span> <span class="nv">y</span><span class="p">)</span> <span class="p">(</span><span class="nb">+</span> <span class="p">(</span><span class="nb">*</span> <span class="mi">3</span> <span class="nv">x</span><span class="p">)</span> <span class="nv">y</span><span class="p">))</span></code></pre>
+</div>
+</div>
 <div id="ansicolor" class="paragraph">
 <p><a id='P_ansi-color'></a>
 </p>
@@ -26233,6 +26268,26 @@ <h3 id="_external_functions">11.1. External functions</h3>
 </div>
 </div>
 <div class="paragraph">
+<p>In order to pass a <code>NULL</code> pointer to an external C function, the
+<code>#void</code> Scheme value can be used.</p>
+</div>
+<div class="paragraph">
+<p>As an example, the second argument to the <code>strtol</code> function can be
+<code>NULL</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="rouge highlight"><code data-lang="scheme"><span class="p">(</span><span class="nf">define-external</span> <span class="nv">strtol</span><span class="p">(</span><span class="nf">:string</span> <span class="nv">:pointer</span> <span class="nv">:int</span><span class="p">)</span>
+  <span class="nv">:return-type</span> <span class="nv">:long</span><span class="p">)</span></code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="rouge highlight"><code data-lang="scheme"><span class="p">(</span><span class="nf">strtol</span> <span class="s">"1001"</span> <span class="o">#</span><span class="nv">void</span> <span class="mi">10</span><span class="p">)</span> <span class="nv">=&gt;</span> <span class="mi">1001</span>
+<span class="p">(</span><span class="nf">strtol</span> <span class="s">"1001"</span> <span class="o">#</span><span class="nv">void</span> <span class="mi">2</span><span class="p">)</span>  <span class="nv">=&gt;</span> <span class="mi">9</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
 <p>Functions on C pointers are described in the next section.</p>
 </div>
 </div>

diff --git a/doc/refman/ffi.adoc b/doc/refman/ffi.adoc
@@ -157,6 +157,22 @@ the FFI better!):
                             => "ring"
 ```
 
+In order to pass a `NULL` pointer to an external C function, the
+`#void` Scheme value can be used.
+
+As an example, the second argument to the `strtol` function can be
+`NULL`:
+
+```scheme
+(define-external strtol(:string :pointer :int)
+  :return-type :long)
+```
+
+```scheme
+(strtol "1001" #void 10) => 1001
+(strtol "1001" #void 2)  => 9
+```
+
 Functions on C pointers are described in the next section.
 
 ### C pointers
@@ -178,5 +194,3 @@ errors, crashes...
 {{insertdoc 'cpointer->string}}
 {{insertdoc 'allocate-bytes}}
 {{insertdoc 'free-bytes}}
-
-