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

  1! Copyright (C) 2009 Jeremy Hughes.
  2! See http://factorcode.org/license.txt for BSD license.
  3USING: help.markup help.syntax alien.inline ;
  4IN: alien.inline.syntax
  5
  6HELP: ;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
 11HELP: 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
 16HELP: 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
 37HELP: 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
 42HELP: 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
 63HELP: 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
 68HELP: 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
 73HELP: 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
 78HELP: 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
 83HELP: 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
 87HELP: 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
 98HELP: <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" } "." } ;