unmaintained/alien/inline/inline-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 strings effects quotations ;
   4 IN: alien.inline
   5
   6 <PRIVATE
   7 : $binding-note ( x -- )
   8     drop
   9     { "This word requires that certain variables are correctly bound. "
  10         "Call " { $link POSTPONE: define-c-library } " to set them up." } print-element ;
  11 PRIVATE>
  12
  13 HELP: compile-c-library
  14 { $description "Writes, compiles, and links code generated since last invocation of " { $link POSTPONE: define-c-library } ". "
  15   "Also calls " { $snippet "add-library" } ". "
  16   "This word does nothing if the shared library is younger than the factor source file." }
  17 { $notes $binding-note } ;
  18
  19 HELP: c-use-framework
  20 { $values
  21     { "str" string }
  22 }
  23 { $description "OS X only. Adds " { $snippet "-framework name" } " to linker command." }
  24 { $notes $binding-note }
  25 { $see-also c-link-to c-link-to/use-framework } ;
  26
  27 HELP: define-c-function
  28 { $values
  29     { "function" "function name" } { "types" "a sequence of C types" } { "effect" effect } { "body" string }
  30 }
  31 { $description "Defines a C function and a factor word which calls it." }
  32 { $notes
  33   { $list
  34     { "The number of " { $snippet "types" } " must match the " { $snippet "in" } " count of the " { $snippet "effect" } "." }
  35     { "There must be only one " { $snippet "out" } " element. It must be a legal C return type with dashes (-) instead of spaces." }
  36     $binding-note
  37   }
  38 }
  39 { $see-also POSTPONE: define-c-function' } ;
  40
  41 HELP: define-c-function'
  42 { $values
  43     { "function" "function name" } { "effect" effect } { "body" string }
  44 }
  45 { $description "Defines a C function and a factor word which calls it. See " { $link define-c-function } " for more information." }
  46 { $notes
  47   { $list
  48     { "Each effect element must be a legal C type with dashes (-) instead of spaces. "
  49       "C argument names will be generated alphabetically, starting with " { $snippet "a" } "." }
  50     $binding-note
  51   }
  52 }
  53 { $see-also define-c-function } ;
  54
  55 HELP: c-include
  56 { $values
  57     { "str" string }
  58 }
  59 { $description "Appends an include line to the C library in scope." }
  60 { $notes $binding-note } ;
  61
  62 HELP: define-c-library
  63 { $values
  64     { "name" string }
  65 }
  66 { $description "Starts a new C library scope. Other " { $snippet "alien.inline" } " words can be used after this one." } ;
  67
  68 HELP: c-link-to
  69 { $values
  70     { "str" string }
  71 }
  72 { $description "Adds " { $snippet "-lname" } " to linker command." }
  73 { $notes $binding-note }
  74 { $see-also c-use-framework c-link-to/use-framework } ;
  75
  76 HELP: c-link-to/use-framework
  77 { $values
  78     { "str" string }
  79 }
  80 { $description "Equivalent to " { $link c-use-framework } " on OS X and " { $link c-link-to } " everywhere else." }
  81 { $notes $binding-note }
  82 { $see-also c-link-to c-use-framework } ;
  83
  84 HELP: define-c-struct
  85 { $values
  86     { "name" string } { "fields" "type/name pairs" }
  87 }
  88 { $description "Defines a C struct and factor words which operate on it." }
  89 { $notes $binding-note } ;
  90
  91 HELP: define-c-typedef
  92 { $values
  93     { "old" "C type" } { "new" "C type" }
  94 }
  95 { $description "Define C and factor typedefs." }
  96 { $notes $binding-note } ;
  97
  98 HELP: delete-inline-library
  99 { $values
 100     { "name" string }
 101 }
 102 { $description "Delete the shared library file corresponding to " { $snippet "name" } "." }
 103 { $notes "Must be executed in the vocabulary where " { $snippet "name" } " is defined. " } ;
 104
 105 HELP: with-c-library
 106 { $values
 107     { "name" string } { "quot" quotation }
 108 }
 109 { $description "Calls " { $link define-c-library } ", then the quotation, then " { $link compile-c-library } ", then sets all variables bound by " { $snippet "define-c-library" } " to " { $snippet "f" } "." } ;
 110
 111 HELP: raw-c
 112 { $values { "str" string } }
 113 { $description "Insert a string into the generated source file. Useful for macros and other details not implemented in " { $snippet "alien.inline" } "." } ;