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

http://github.com/abeaumont/factor · Factor · 113 lines · 97 code · 14 blank · 2 comment · 0 complexity · d35a2acddf8447f1e56b150e04c9cfed MD5 · raw file

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