basis/alien/syntax/syntax-docs.factor

   1 IN: alien.syntax
   2 USING: alien alien.c-types alien.parser alien.libraries
   3 classes.struct help.markup help.syntax see ;
   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 hexadecimal 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 { $subsections
  18     POSTPONE: ALIEN:
  19     POSTPONE: DLL"
  20 } ;
  21
  22 HELP: LIBRARY:
  23 { $syntax "LIBRARY: name" }
  24 { $values { "name" "a logical library name" } }
  25 { $description "Sets the logical library for consequent " { $link POSTPONE: FUNCTION: } ", " { $link POSTPONE: C-GLOBAL: } " and " { $link POSTPONE: CALLBACK: } " definitions, as well as " { $link POSTPONE: &: } " forms." }
  26 { $notes "Logical library names are defined with the " { $link add-library } " word." } ;
  27
  28 HELP: FUNCTION:
  29 { $syntax "FUNCTION: return name ( parameters )" }
  30 { $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, ..." } } }
  31 { $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."
  32 $nl
  33 "The new word must be compiled before being executed." }
  34 { $examples
  35 "For example, suppose the " { $snippet "foo" } " library exports the following function:"
  36 { $code
  37     "void the_answer(char* question, int value) {"
  38     "    printf(\"The answer to %s is %d.\n\",question,value);"
  39     "}"
  40 }
  41 "You can define a word for invoking it:"
  42 { $unchecked-example
  43     "LIBRARY: foo\nFUNCTION: void the_answer ( char* question, int value ) ;"
  44     "USE: compiler"
  45     "\"the question\" 42 the_answer"
  46     "The answer to the question is 42."
  47 } }
  48 { $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:"
  49 { $code
  50     "FUNCTION: void glHint ( GLenum target, GLenum mode ) ;"
  51     "FUNCTION: void glHint GLenum target GLenum mode ;"
  52 } } ;
  53
  54 HELP: TYPEDEF:
  55 { $syntax "TYPEDEF: old new" }
  56 { $values { "old" "a C type" } { "new" "a C type" } }
  57 { $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } " if ." }
  58 { $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." } ;
  59
  60 HELP: C-ENUM:
  61 { $syntax "C-ENUM: words... ;" }
  62 { $values { "words" "a sequence of word names" } }
  63 { $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." }
  64 { $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 " { $link "words.symbol" } " or " { $link "singletons" } " instead." }
  65 { $examples
  66     "Here is an example enumeration definition:"
  67     { $code "C-ENUM: red green blue ;" }
  68     "It is equivalent to the following series of definitions:"
  69     { $code "CONSTANT: red 0" "CONSTANT: green 1" "CONSTANT: blue 2" }
  70 } ;
  71
  72 HELP: C-TYPE:
  73 { $syntax "C-TYPE: type" }
  74 { $values { "type" "a new C type" } }
  75 { $description "Defines a new, opaque C type. Since it is opaque, " { $snippet "type" } " will not be directly usable as a parameter or return type of a " { $link POSTPONE: FUNCTION: } " or as a slot of a " { $link POSTPONE: STRUCT: } ". However, it can be used as the type of a pointer (that is, as " { $snippet "type*" } ")." $nl
  76 { $snippet "C-TYPE:" } " can also be used to forward-declare C types to enable circular dependencies. For example:"
  77 { $code """C-TYPE: forward
  78 STRUCT: backward { x forward* } ;
  79 STRUCT: forward { x backward* } ; """ } }
  80 { $notes "Primitive C types are also displayed using " { $snippet "C-TYPE:" } " syntax when they are displayed by " { $link see } "." } ;
  81
  82 HELP: CALLBACK:
  83 { $syntax "CALLBACK: return type ( parameters ) ;" }
  84 { $values { "return" "a C return type" } { "type" "a type name" } { "parameters" "a comma-separated sequence of type/name pairs; " { $snippet "type1 arg1, type2 arg2, ..." } } }
  85 { $description "Defines a new function pointer C type word " { $snippet "type" } ". The newly defined word works both as a C type and as a wrapper for " { $link alien-callback } " for callbacks that accept the given return type and parameters. The ABI of the callback is decided from the ABI of the active " { $link POSTPONE: LIBRARY: } " declaration." }
  86 { $examples
  87     { $code
  88         "CALLBACK: bool FakeCallback ( int message, void* payload ) ;"
  89         ": MyFakeCallback ( -- alien )"
  90         "    [| message payload |"
  91         "        \"message #\" write"
  92         "        message number>string write"
  93         "        \" received\" write nl"
  94         "        t"
  95         "    ] FakeCallback ;"
  96     }
  97 } ;
  98
  99 HELP: &:
 100 { $syntax "&: symbol" }
 101 { $values { "symbol" "A C global variable name" } }
 102 { $description "Pushes the address of a symbol named " { $snippet "symbol" } " from the current library, set with " { $link POSTPONE: LIBRARY: } "." } ;
 103
 104 HELP: typedef
 105 { $values { "old" "a C type" } { "new" "a C type" } }
 106 { $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } "." }
 107 { $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." } ;
 108
 109 { POSTPONE: TYPEDEF: typedef } related-words
 110
 111 HELP: c-struct?
 112 { $values { "c-type" "a C type" } { "?" "a boolean" } }
 113 { $description "Tests if a C type is a structure defined by " { $link POSTPONE: STRUCT: } "." } ;
 114
 115 HELP: define-function
 116 { $values { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } }
 117 { $description "Defines a word named " { $snippet "function" } " in the current vocabulary (see " { $link "vocabularies" } "). The word calls " { $link alien-invoke } " with the specified parameters." }
 118 { $notes "This word is used to implement the " { $link POSTPONE: FUNCTION: } " parsing word." } ;
 119
 120 HELP: C-GLOBAL:
 121 { $syntax "C-GLOBAL: type name" }
 122 { $values { "type" "a C type" } { "name" "a C global variable name" } }
 123 { $description "Defines a new word named " { $snippet "name" } " which accesses a global variable in the current library, set with " { $link POSTPONE: LIBRARY: } "." } ;