core/compiler/alien/syntax.facts

   1 IN: syntax
   2 USING: alien help ;
   3
   4 HELP: DLL"
   5 { $syntax "DLL\" path\"" }
   6 { $values { "path" "a path name string" } }
   7 { $description "Constructs a DLL handle at parse time." }
   8 { $see-also dlopen } ;
   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." }
  15 { $see-also <alien> } ;
  16
  17 HELP: LIBRARY:
  18 { $syntax "LIBRARY: name" }
  19 { $values { "name" "a logical library name" } }
  20 { $description "Sets the logical library for consequent " { $link POSTPONE: FUNCTION: } " definitions that follow." } ;
  21
  22 HELP: FUNCTION:
  23 { $syntax "FUNCTION: return name ( parameters )" }
  24 { $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, ..." } } }
  25 { $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."
  26 $terpri
  27 "The new word must be compiled before being executed." }
  28 { $examples
  29 "For example, suppose the " { $snippet "foo" } " library exports the following function:"
  30 { $code
  31     "void the_answer(char* question, int value) {"
  32     "    printf(\"The answer to %s is %d.\n\",question,value);"
  33     "}"
  34 }
  35 "You can define a word for invoking it:"
  36 { $example
  37     "LIBRARY: foo\nFUNCTION: void the_answer ( char* question, int value ) ;"
  38     "USE: compiler"
  39     "\\ the_answer compile"
  40     "\"the question\" 42 the_answer"
  41     "The answer to the question is 42."
  42 } }
  43 { $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:"
  44 { $code
  45     "FUNCTION: void glHint ( GLenum target, GLenum mode ) ;"
  46     "FUNCTION: void glHint GLenum target GLenum mode ;"
  47 } } ;
  48
  49 HELP: TYPEDEF:
  50 { $syntax "TYPEDEF: old new" }
  51 { $values { "old" "a C type" } { "new" "a C type" } }
  52 { $description "Alises the C types " { $snippet "old" } " and " { $snippet "old*" } " under the names " { $snippet "new" } " and " { $snippet "new*" } ", respectively." }
  53 { $see-also (typedef) typedef } ;
  54
  55 HELP: BEGIN-STRUCT:
  56 { $syntax "BEGIN-STRUCT: name" }
  57 { $values { "name" "a new C type name" } }
  58 { $description "Begins reading a C struct definition. This word must be followed by one or more " { $link POSTPONE: FIELD: } " declarations, terminating in " { $link POSTPONE: END-STRUCT } "." } ;
  59
  60 HELP: FIELD:
  61 { $syntax "FIELD: type name" }
  62 { $values { "type" "a C type" } { "name" "a field name" } }
  63 { $description "Adds a field to the C structure currently being read. This word can only be used inside a " { $link POSTPONE: BEGIN-STRUCT: } "/" { $link POSTPONE: END-STRUCT } " pair." } ;
  64
  65 HELP: END-STRUCT
  66 { $syntax "END-STRUCT" }
  67 { $description "Ends a structure definition. Only valid after a " { $link POSTPONE: BEGIN-STRUCT: } "." } ;
  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 { $examples { $code "C-UNION: event  active-event keyboard-event mouse-event ;" } } ;
  74
  75 HELP: C-ENUM:
  76 { $syntax "C-ENUM: words... ;" }
  77 { $values { "words" "a sequence of word names" } }
  78 { $description "Creates a sequence of compound definitions in the current vocabulary. Each word pushes an integer according to its index in the enumeration definition. The first word pushes 0." }
  79 { $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." }
  80 { $examples
  81     "The following two lines are equivalent:"
  82     { $code "C-ENUM: red green blue ;" ": red 0 ;  : green 1 ;  : blue 2 ;" }
  83 } ;