unmaintained/alien/marshall/syntax/syntax-docs.factor

   1 ! Copyright (C) 2009 Jeremy Hughes.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations words
   4 alien.inline alien.syntax effects alien.marshall
   5 alien.marshall.structs strings sequences alien.inline.syntax ;
   6 IN: alien.marshall.syntax
   7
   8 HELP: CM-FUNCTION:
   9 { $syntax "CM-FUNCTION: return name args\n    body\n;" }
  10 { $description "Like " { $link POSTPONE: C-FUNCTION: } " but with marshalling "
  11     "of arguments and return values."
  12 }
  13 { $examples
  14   { $example
  15     "USING: alien.inline.syntax alien.marshall.syntax prettyprint ;"
  16     "IN: example"
  17     ""
  18     "C-LIBRARY: exlib"
  19     ""
  20     "C-INCLUDE: <stdio.h>"
  21     "C-INCLUDE: <stdlib.h>"
  22     "CM-FUNCTION: char* sum_diff ( const-int a, const-int b, int* x, int* y )"
  23     "    *x = a + b;"
  24     "    *y = a - b;"
  25     "    char* s = (char*) malloc(sizeof(char) * 64);"
  26     "    sprintf(s, \"sum %i, diff %i\", *x, *y);"
  27     "    return s;"
  28     ";"
  29     ""
  30     ";C-LIBRARY"
  31     ""
  32     "8 5 0 0 sum_diff . . ."
  33     "3\n13\n\"sum 13, diff 3\""
  34   }
  35 }
  36 { $see-also define-c-marshalled POSTPONE: C-FUNCTION: POSTPONE: M-FUNCTION: } ;
  37
  38 HELP: CM-STRUCTURE:
  39 { $syntax "CM-STRUCTURE: name fields ... ;" }
  40 { $description "Like " { $link POSTPONE: C-STRUCTURE: } " but with marshalling of fields. "
  41     "Defines a subclass of " { $link struct-wrapper } " a constructor, and slot-like accessor words."
  42 }
  43 { $see-also POSTPONE: C-STRUCTURE: POSTPONE: M-STRUCTURE: } ;
  44
  45 HELP: M-FUNCTION:
  46 { $syntax "M-FUNCTION: return name args ;" }
  47 { $description "Like " { $link POSTPONE: FUNCTION: } " but with marshalling "
  48     "of arguments and return values."
  49 }
  50 { $see-also marshalled-function POSTPONE: C-FUNCTION: POSTPONE: CM-FUNCTION: } ;
  51
  52 HELP: M-STRUCTURE:
  53 { $syntax "M-STRUCTURE: name fields ... ;" }
  54 { $description "Like " { $link POSTPONE: C-STRUCT: } " but with marshalling of fields. "
  55     "Defines a subclass of " { $link struct-wrapper } " a constructor, and slot-like accessor words."
  56 }
  57 { $see-also define-marshalled-struct POSTPONE: C-STRUCTURE: POSTPONE: CM-STRUCTURE: } ;
  58
  59 HELP: define-c-marshalled
  60 { $values
  61     { "name" string } { "types" sequence } { "effect" effect } { "body" string }
  62 }
  63 { $description "Defines a C function and a factor word which calls it with marshalling of "
  64     "args and return values."
  65 }
  66 { $see-also define-c-marshalled' } ;
  67
  68 HELP: define-c-marshalled'
  69 { $values
  70     { "name" string } { "effect" effect } { "body" string }
  71 }
  72 { $description "Like " { $link define-c-marshalled } ". "
  73      "The effect elements must be C type strings."
  74 } ;
  75
  76 HELP: marshalled-function
  77 { $values
  78     { "name" string } { "types" sequence } { "effect" effect }
  79     { "word" word } { "quot" quotation } { "effect" effect }
  80 }
  81 { $description "Defines a word which calls the named C function. Arguments, "
  82      "return value, and output parameters are marshalled and unmarshalled."
  83 } ;
  84