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

  1! Copyright (C) 2009 Jeremy Hughes.
  2! See http://factorcode.org/license.txt for BSD license.
  3USING: help.markup help.syntax kernel strings effects quotations ;
  4IN: 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 ;
 11PRIVATE>
 12
 13HELP: 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
 19HELP: 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
 27HELP: 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
 41HELP: 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
 55HELP: 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
 62HELP: 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
 68HELP: 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
 76HELP: 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
 84HELP: 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
 91HELP: 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
 98HELP: 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
105HELP: 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
111HELP: 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" } "." } ;