unmaintained/alien/inline/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 alien.inline ;
   4 IN: alien.inline.syntax
   5
   6 HELP: ;C-LIBRARY
   7 { $syntax ";C-LIBRARY" }
   8 { $description "Writes, compiles, and links code generated since previous invocation of " { $link POSTPONE: C-LIBRARY: } "." }
   9 { $see-also POSTPONE: compile-c-library } ;
  10
  11 HELP: C-FRAMEWORK:
  12 { $syntax "C-FRAMEWORK: name" }
  13 { $description "OS X only. Link to named framework. Takes effect when " { $link POSTPONE: ;C-LIBRARY } " is called." }
  14 { $see-also POSTPONE: c-use-framework } ;
  15
  16 HELP: C-FUNCTION:
  17 { $syntax "C-FUNCTION: return name ( args ... )\nbody\n;" }
  18 { $description "Appends a function to the C library in scope and defines an FFI word that calls it." }
  19 { $examples
  20   { $example
  21     "USING: alien.inline.syntax prettyprint ;"
  22     "IN: cmath.ffi"
  23     ""
  24     "C-LIBRARY: cmathlib"
  25     ""
  26     "C-FUNCTION: int add ( int a, int b )"
  27     "    return a + b;"
  28     ";"
  29     ""
  30     ";C-LIBRARY"
  31     ""
  32     "1 2 add ."
  33     "3" }
  34 }
  35 { $see-also POSTPONE: define-c-function } ;
  36
  37 HELP: C-INCLUDE:
  38 { $syntax "C-INCLUDE: name" }
  39 { $description "Appends an include line to the C library in scope." }
  40 { $see-also POSTPONE: c-include } ;
  41
  42 HELP: C-LIBRARY:
  43 { $syntax "C-LIBRARY: name" }
  44 { $description "Starts a new C library scope. Other " { $snippet "alien.inline" } " syntax can be used after this word." }
  45 { $examples
  46   { $example
  47     "USING: alien.inline.syntax ;"
  48     "IN: rectangle.ffi"
  49     ""
  50     "C-LIBRARY: rectlib"
  51     ""
  52     "C-STRUCTURE: rectangle { \"int\" \"width\" } { \"int\" \"height\" } ;"
  53     ""
  54     "C-FUNCTION: int area ( rectangle c )"
  55     "    return c.width * c.height;"
  56     ";"
  57     ""
  58     ";C-LIBRARY"
  59     "" }
  60 }
  61 { $see-also POSTPONE: define-c-library } ;
  62
  63 HELP: C-LINK/FRAMEWORK:
  64 { $syntax "C-LINK/FRAMEWORK: name" }
  65 { $description "Equivalent to " { $link POSTPONE: C-FRAMEWORK: } " on OS X and " { $link POSTPONE: C-LINK: } " everywhere else." }
  66 { $see-also POSTPONE: c-link-to/use-framework } ;
  67
  68 HELP: C-LINK:
  69 { $syntax "C-LINK: name" }
  70 { $description "Link to named library. Takes effect when " { $link POSTPONE: ;C-LIBRARY } " is called." }
  71 { $see-also POSTPONE: c-link-to } ;
  72
  73 HELP: C-STRUCTURE:
  74 { $syntax "C-STRUCTURE: name pairs ... ;" }
  75 { $description "Like " { $snippet "C-STRUCT:" } " but also generates equivalent C code."}
  76 { $see-also POSTPONE: define-c-struct } ;
  77
  78 HELP: C-TYPEDEF:
  79 { $syntax "C-TYPEDEF: old new" }
  80 { $description "Like " { $snippet "TYPEDEF:" } " but generates a C typedef statement too." }
  81 { $see-also POSTPONE: define-c-typedef } ;
  82
  83 HELP: COMPILE-AS-C++
  84 { $syntax "COMPILE-AS-C++" }
  85 { $description "Insert this word anywhere between " { $link POSTPONE: C-LIBRARY: } " and " { $link POSTPONE: ;C-LIBRARY } " and the generated code will be treated as C++ with " { $snippet "extern \"C\"" } " prepended to each function prototype." } ;
  86
  87 HELP: DELETE-C-LIBRARY:
  88 { $syntax "DELETE-C-LIBRARY: name" }
  89 { $description "Deletes the shared library file corresponding to " { $snippet "name" } " . " }
  90 { $notes
  91   { $list
  92     { "Must be executed in the vocabulary where " { $snippet "name" } " is defined. " }
  93     "This word is mainly useful for unit tests."
  94   }
  95 }
  96 { $see-also POSTPONE: delete-inline-library } ;
  97
  98 HELP: <RAW-C
  99 { $syntax "<RAW-C code RAW-C>" }
 100 { $description "Insert a (multiline) string into the generated source file. Useful for macros and other details not implemented in " { $snippet "alien.inline" } "." } ;