From 48bd9aaacffa875e800d3fbd011c5bfc4a87b549 Mon Sep 17 00:00:00 2001
From: Jeremy Hughes <jedahu@gmail.com>
Date: Tue, 14 Jul 2009 22:36:59 +1200
Subject: [PATCH] alien.marshall.syntax: added documentation

---
 .../alien/marshall/syntax/syntax-docs.factor  | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 basis/alien/marshall/syntax/syntax-docs.factor

diff --git a/basis/alien/marshall/syntax/syntax-docs.factor b/basis/alien/marshall/syntax/syntax-docs.factor
new file mode 100644
index 0000000000..6b7d6bfa35
--- /dev/null
+++ b/basis/alien/marshall/syntax/syntax-docs.factor
@@ -0,0 +1,85 @@
+! Copyright (C) 2009 Jeremy Hughes.
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel quotations words
+alien.inline alien.syntax effects alien.marshall
+alien.marshall.structs strings sequences ;
+IN: alien.marshall.syntax
+
+HELP: CM-FUNCTION:
+{ $syntax "CM-FUNCTION: return name args\n    body\n;" }
+{ $description "Like " { $link POSTPONE: C-FUNCTION: } " but with marshalling "
+    "of arguments and return values."
+}
+{ $examples
+  { $example
+    "USING: alien.inline alien.marshall.syntax prettyprint ;"
+    "IN: example"
+    ""
+    "C-LIBRARY: exlib"
+    ""
+    "C-INCLUDE: <stdio.h>"
+    "CM-FUNCTION: char* sum_diff ( const-int a, const-int b, int* x, int* y )"
+    "    *x = a + b;"
+    "    *y = a - b;"
+    "    char* s = (char*) malloc(sizeof(char) * 64);"
+    "    sprintf(s, \"sum %i, diff %i\", *x, *y);"
+    "    return s;"
+    ";"
+    ""
+    ";C-LIBRARY"
+    ""
+    "8 5 0 0 sum_diff .s"
+    "\"sum 13, diff 3\""
+    "13"
+    "3"
+  }
+}
+{ $see-also define-c-marshalled POSTPONE: C-FUNCTION: POSTPONE: M-FUNCTION: } ;
+
+HELP: CM-STRUCTURE:
+{ $syntax "CM-STRUCTURE: name fields ... ;" }
+{ $description "Like " { $link POSTPONE: C-STRUCTURE: } " but with marshalling of fields. "
+    "Defines a subclass of " { $link struct-wrapper } " a constructor, and slot-like accessor words."
+}
+{ $see-also POSTPONE: C-STRUCTURE: POSTPONE: M-STRUCTURE: } ;
+
+HELP: M-FUNCTION:
+{ $syntax "M-FUNCTION: return name args ;" }
+{ $description "Like " { $link POSTPONE: FUNCTION: } " but with marshalling "
+    "of arguments and return values."
+}
+{ $see-also marshalled-function POSTPONE: C-FUNCTION: POSTPONE: CM-FUNCTION: } ;
+
+HELP: M-STRUCTURE:
+{ $syntax "M-STRUCTURE: name fields ... ;" }
+{ $description "Like " { $link POSTPONE: C-STRUCT: } " but with marshalling of fields. "
+    "Defines a subclass of " { $link struct-wrapper } " a constructor, and slot-like accessor words."
+}
+{ $see-also define-marshalled-struct POSTPONE: C-STRUCTURE: POSTPONE: CM-STRUCTURE: } ;
+
+HELP: define-c-marshalled
+{ $values
+    { "name" string } { "types" sequence } { "effect" effect } { "body" string }
+}
+{ $description "Defines a C function and a factor word which calls it with marshalling of "
+    "args and return values."
+}
+{ $see-also define-c-marshalled' } ;
+
+HELP: define-c-marshalled'
+{ $values
+    { "name" string } { "effect" effect } { "body" string }
+}
+{ $description "Like " { $link define-c-marshalled } ". "
+     "The effect elements must be C type strings."
+} ;
+
+HELP: marshalled-function
+{ $values
+    { "name" string } { "types" sequence } { "effect" effect }
+    { "word" word } { "quot" quotation } { "effect" effect }
+}
+{ $description "Defines a word which calls the named C function. Arguments, "
+     "return value, and output parameters are marshalled and unmarshalled."
+} ;
+