basis/alien/syntax/syntax-docs.factor

   1 IN: alien.syntax
   2 USING: alien alien.c-types alien.enums alien.libraries classes.struct
   3 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 the C library function with the same " { $snippet "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 ( c-string question, int value )"
  44     "\"the question\" 42 the_answer"
  45     "The answer to the question is 42."
  46 } }
  47 "Using the " { $link c-string } " type instead of " { $snippet "char*" } " causes the FFI to automatically convert Factor strings to C strings. See " { $link "c-strings" } " for more information on using strings with the FFI."
  48 { $notes "To make a Factor word with a name different from the C function, use " { $link POSTPONE: FUNCTION-ALIAS: } "." } ;
  49
  50 HELP: FUNCTION-ALIAS:
  51 { $syntax "FUNCTION-ALIAS: factor-name
  52     return c_name ( parameters ) ;" }
  53 { $values { "factor-name" "a Factor word name" } { "return" "a C return type" } { "name" "a C function name" } { "parameters" "a comma-separated sequence of type/name pairs; " { $snippet "type1 arg1, type2 arg2, ..." } } }
  54 { $description "Defines a new word " { $snippet "factor-name" } " which calls the C library function named " { $snippet "c_name" } " in the logical library given by the most recent " { $link POSTPONE: LIBRARY: } " declaration."
  55 $nl
  56 "The new word must be compiled before being executed." }
  57 { $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 easier to read." } ;
  58
  59 { POSTPONE: FUNCTION: POSTPONE: FUNCTION-ALIAS: } related-words
  60
  61 HELP: TYPEDEF:
  62 { $syntax "TYPEDEF: old new" }
  63 { $values { "old" "a C type" } { "new" "a C type" } }
  64 { $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } "." }
  65 { $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." } ;
  66
  67 HELP: ENUM:
  68 { $syntax "ENUM: type words... ;" "ENUM: type < base-type words..." }
  69 { $values { "type" { $maybe "a name to typedef to int" } } { "words" "a sequence of word names" } }
  70 { $description "Creates a c-type that boxes and unboxes integer values to symbols. A singleton is defined for each member word which allows generic dispatch on the enum's members. The base c-type can optionally be specified and defaults to " { $link int } ". A constructor word " { $snippet "<type>" } " is defined for converting from integers to singletons. The generic word " { $link enum>number } " converts from singletons to integers. Enum-typed values are automatically prettyprinted as their singleton words. Unrecognizing enum numbers are kept as numbers." }
  71 { $examples
  72     "Here is an example enumeration definition:"
  73     { $code "ENUM: color_t red { green 3 } blue ;" }
  74     $nl
  75     "The following expression returns true:"
  76     { $code "3 <color_t> [ green = ] [ enum>number 3 = ] bi and" }
  77     $nl
  78     "Here is a version where the C-type takes a single byte:"
  79     { $code "ENUM: tv_peripherals_1 < uchar"
  80             "{ appletv 1 } { chromecast 2 } { roku 4 } ;"
  81     }
  82     $nl
  83     "The same as above but four bytes instead of one:"
  84     { $code "ENUM: tv_peripherals_4 < uint"
  85             "{ appletv 1 } { chromecast 2 } { roku 4 } ;"
  86     }
  87     $nl
  88     "We can define a generic and dispatch on it:"
  89     { $code "ENUM: tv_peripherals_4 < uint"
  90             "{ appletv 1 } { chromecast 2 } { roku 4 } ;"
  91             ""
  92             "GENERIC: watch-device ( device -- )"
  93             "M: appletv watch-device drop \"watching appletv\" print ;"
  94             "M: chromecast watch-device drop \"watching chromecast\" print ;"
  95             ""
  96             "appletv watch-device"
  97     }
  98 } ;
  99
 100 HELP: C-TYPE:
 101 { $syntax "C-TYPE: type" }
 102 { $values { "type" "a new C type" } }
 103 { $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 " { $link pointer } "." $nl
 104 { $snippet "C-TYPE:" } " can also be used to forward declare C types, allowing circular dependencies to occur between types. For example:"
 105 { $code "C-TYPE: forward
 106 STRUCT: backward { x forward* } ;
 107 STRUCT: forward { x backward* } ;" } }
 108 { $notes "Primitive C types are displayed using " { $snippet "C-TYPE:" } " syntax when they are " { $link see } "n." } ;
 109
 110 HELP: CALLBACK:
 111 { $syntax "CALLBACK: return type ( parameters )" }
 112 { $values { "return" "a C return type" } { "type" "a type name" } { "parameters" "a comma-separated sequence of type/name pairs; " { $snippet "type1 arg1, type2 arg2, ..." } } }
 113 { $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." }
 114 { $examples
 115     { $code
 116         "CALLBACK: bool FakeCallback ( int message, void* payload )"
 117         ": MyFakeCallback ( -- alien )"
 118         "    [| message payload |"
 119         "        \"message #\" write"
 120         "        message number>string write"
 121         "        \" received\" write nl"
 122         "        t"
 123         "    ] FakeCallback ;"
 124     }
 125 } ;
 126
 127 HELP: &:
 128 { $syntax "&: symbol" }
 129 { $values { "symbol" "A C global variable name" } }
 130 { $description "Pushes the address of a symbol named " { $snippet "symbol" } " from the current library, set with " { $link POSTPONE: LIBRARY: } "." } ;
 131
 132 HELP: typedef
 133 { $values { "old" "a C type" } { "new" "a C type" } }
 134 { $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } "." }
 135 { $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." } ;
 136
 137 { POSTPONE: TYPEDEF: typedef } related-words
 138
 139 HELP: C-GLOBAL:
 140 { $syntax "C-GLOBAL: type name" }
 141 { $values { "type" "a C type" } { "name" "a C global variable name" } }
 142 { $description "Defines a getter " { $snippet "name" } " and setter " { $snippet "set-name" } " for the global value in the current library, set with " { $link POSTPONE: LIBRARY: } "." } ;
 143
 144 HELP: INITIALIZE-ALIEN:
 145 { $syntax "INITIALIZE-ALIEN: type ... ;" }
 146 { $description "Initializes a " { $snippet "type" } " using the provided definition." } ;
 147
 148 ARTICLE: "alien.enums" "Enumeration types"
 149 "The " { $vocab-link "alien.enums" } " vocab contains the implementation for " { $link POSTPONE: ENUM: } " C types, and provides words for converting between enum singletons and integers. It is possible to dispatch off of members of an enum."
 150 $nl
 151 "Defining enums:"
 152 { $subsection POSTPONE: ENUM: }
 153 "Defining enums at run-time:"
 154 { $subsection define-enum }
 155 "Conversions between enums and integers:"
 156 { $subsections enum>number number>enum } ;