[PATCH 20/25] Document with-pointer macro

[KAction@gnu.org]

From: Dmitry Bogatov <KAction@gnu.org>

---
 doc/ref/api-foreign.texi | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi
index 6b0e34c..7114225 100644
--- a/doc/ref/api-foreign.texi
+++ b/doc/ref/api-foreign.texi
@@ -1140,6 +1140,54 @@ As demonstrated by example, values can be arbitrary, but in most common
 each value have only one bit set.
 @end deffn
 
+Often, when working with C functions, you will have to work with output
+arguments. Usually, following macro can make life easier.
+
+@deffn {Scheme Macro} with-pointer bindings foreign-statement body
+This macro establishes bindings, that are pointers, when evaluating
+@code{foreign-statement} and are decoded Scheme values, when evaluating
+@code{body}. Every binding have one of following forms
+@enumerate
+@item
+@code{(type name = value)} -- encode @code{value} according to
+@code{<foreign-type>} record @code{type} and bind @code{name} to pointer
+to encoded value in @code{foreign-statement} and bind @code{name} to
+value, decoded back according to @code{type} in @code{body}. This form
+is used for input-output arguments.
+
+@item
+@code{(type name)} -- same as previous, but value, pointed by
+@code{name} in @code{foreign-statement} is unspecified. This form is
+used for output-only argument. For example, previously mentioned
+@code{ask-time} procedure can be defined as following:
+@example
+(define ask-time
+  (let ()
+    (define-foreign-function c-time ((*: t)) :: long:)
+    (lambda ()
+      (with-pointer ((long: t))
+        (c-time t)
+       t))))
+@end example
+
+@item
+With form @code{(name *--> bytevector)} @code{name} points to memory,
+underlying of @code{bytevector} in @code{foreign-statement}, with
+possibility to change it in-place. In @code{body} @code{name} refers to
+@code{bytevector}, probably modified. This form is used for input-output
+string or raw memory C functions arguments.
+
+@item
+Form @code{(name *--> length)} behaves same, as previous, but uses newly
+created bytevector of size @code{length}. This form is used for
+output-only string or raw memory C functions arguments.
+@end enumerate
+
+If @code{foreign-statement} has form @code{(name = expr)}, @code{name}
+will be bound to value of @code{expr} during evaluation of @code{body}.
+Otherwise value of @code{foreign-statement} is lost.
+@end deffn
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
-- 
I may be not subscribed. Please, keep me in carbon copy.