basis/alien/syntax/syntax-docs.factor

   1 IN: alien.syntax
   2 USING: alien alien.c-types alien.structs alien.syntax.private
   3 help.markup help.syntax ;
   4
   5 HELP: DLL"
   6 { $syntax "DLL\" path\"" }
   7 { $values { "path" "a pathname string" } }
   8 { $description "Constructs a DLL handle at parse time." } ;
   9
  10 HELP: ALIEN:
  11 { $syntax "ALIEN: address" }
  12 { $values { "address" "a non-negative integer" } }
  13 { $description "Creates an alien object at parse time." }
  14 { $notes "Alien objects are invalidated between image saves and loads, and hence source files should not contain alien literals; this word is for interactive use only. See " { $link "alien-expiry" } " for details." } ;
  15
  16 ARTICLE: "syntax-aliens" "Alien object literal syntax"
  17 { $subsection POSTPONE: ALIEN: }
  18 { $subsection POSTPONE: DLL" } ;
  19
  20 HELP: LIBRARY:
  21 { $syntax "LIBRARY: name" }
  22 { $values { "name" "a logical library name" } }
  23 { $description "Sets the logical library for consequent " { $link POSTPONE: FUNCTION: } " definitions that follow." } ;
  24
  25 HELP: FUNCTION:
  26 { $syntax "FUNCTION: return name ( parameters )" }
  27 { $values { "return" "a C return type" } { "name" "a C function name" } { "parameters" "a comma-separated sequence of type/name pairs; " { $snippet "type1 arg1, type2 arg2, ..." } } }
  28 { $description "Defines a new word " { $snippet "name" } " which calls a C library function with the same name, in the logical library given by the most recent " { $link POSTPONE: LIBRARY: } " declaration."
  29 $nl
  30 "The new word must be compiled before being executed." }
  31 { $examples
  32 "For example, suppose the " { $snippet "foo" } " library exports the following function:"
  33 { $code
  34     "void the_answer(char* question, int value) {"
  35     "    printf(\"The answer to %s is %d.\n\",question,value);"
  36     "}"
  37 }
  38 "You can define a word for invoking it:"
  39 { $unchecked-example
  40     "LIBRARY: foo\nFUNCTION: void the_answer ( char* question, int value ) ;"
  41     "USE: compiler"
  42     "\"the question\" 42 the_answer"
  43     "The answer to the question is 42."
  44 } }
  45 { $notes "Note that the parentheses and commas are only syntax sugar and can be omitted; they serve no purpose other than to make the declaration slightly easier to read:"
  46 { $code
  47     "FUNCTION: void glHint ( GLenum target, GLenum mode ) ;"
  48     "FUNCTION: void glHint GLenum target GLenum mode ;"
  49 } } ;
  50
  51 HELP: TYPEDEF:
  52 { $syntax "TYPEDEF: old new" }
  53 { $values { "old" "a C type" } { "new" "a C type" } }
  54 { $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } " if ." }
  55 { $notes "This word differs from " { $link typedef } " in that it runs at parse time, to ensure correct ordering of operations when loading source files. Words defined in source files are compiled before top-level forms are run, so if a source file defines C binding words and uses " { $link typedef } ", the type alias won't be available at compile time." } ;
  56
  57 HELP: TYPEDEF-IF:
  58 { $syntax "TYPEDEF-IF: word old new" }
  59 { $values { "word" "a word with stack effect " { $snippet "( -- ? )" } } { "old" "a C type" } { "new" "a C type" } }
  60 { $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } " if " { $snippet "word" } " evaluates to a true value." }
  61 { $notes "This word differs from " { $link typedef } " in that it runs at parse time, to ensure correct ordering of operations when loading source files. Words defined in source files are compiled before top-level forms are run, so if a source file defines C binding words and uses " { $link typedef } ", the type alias won't be available at compile time." } ;
  62
  63 HELP: C-STRUCT:
  64 { $syntax "C-STRUCT: name pairs... ;" }
  65 { $values { "name" "a new C type name" } { "pairs" "C type / field name string pairs" } }
  66 { $description "Defines a C struct layout and accessor words." }
  67 { $notes "C type names are documented in " { $link "c-types-specs" } "." } ;
  68
  69 HELP: C-UNION:
  70 { $syntax "C-UNION: name members... ;" }
  71 { $values { "name" "a new C type name" } { "members" "a sequence of C types" } }
  72 { $description "Defines a new C type sized to fit its largest member." }
  73 { $notes "C type names are documented in " { $link "c-types-specs" } "." }
  74 { $examples { $code "C-UNION: event \"active-event\" \"keyboard-event\" \"mouse-event\" ;" } } ;
  75
  76 HELP: C-ENUM:
  77 { $syntax "C-ENUM: words... ;" }
  78 { $values { "words" "a sequence of word names" } }
  79 { $description "Creates a sequence of word definitions in the current vocabulary. Each word pushes an integer according to its index in the enumeration definition. The first word pushes 0." }
  80 { $notes "This word emulates a C-style " { $snippet "enum" } " in Factor. While this feature can be used for any purpose, using integer constants is discouraged unless it is for interfacing with C libraries. Factor code should use symbolic constants instead." }
  81 { $examples
  82     "The following two lines are equivalent:"
  83     { $code "C-ENUM: red green blue ;" ": red 0 ;  : green 1 ;  : blue 2 ;" }
  84 } ;
  85
  86 HELP: typedef
  87 { $values { "old" "a string" } { "new" "a string" } }
  88 { $description "Alises the C type " { $snippet "old" } " under the name " { $snippet "new" } "." }
  89 { $notes "Using this word in the same source file which defines C bindings can cause problems, because words are compiled before top-level forms are run. Use the " { $link POSTPONE: TYPEDEF: } " word instead." } ;
  90
  91 { POSTPONE: TYPEDEF-IF: POSTPONE: TYPEDEF: typedef } related-words
  92
  93 HELP: c-struct?
  94 { $values { "type" "a string" } { "?" "a boolean" } }
  95 { $description "Tests if a C type is a structure defined by " { $link POSTPONE: C-STRUCT: } "." } ;
  96
  97 HELP: define-function
  98 { $values { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } }
  99 { $description "Defines a word named " { $snippet "function" } " in the current vocabulary (see " { $link "vocabularies" } "). The word calls " { $link alien-invoke } " with the specified parameters." }
 100 { $notes "This word is used to implement the " { $link POSTPONE: FUNCTION: } " parsing word." } ;