diff --git a/docs/api/cyclone/foreign.md b/docs/api/cyclone/foreign.md new file mode 100644 index 00000000..50673ac7 --- /dev/null +++ b/docs/api/cyclone/foreign.md @@ -0,0 +1,40 @@ +# Foreign Library + +The `(cyclone foreign)` provides a convenient interface for integrating with C code. It is based in concept on the `(chicken foreign)` module from CHICKEN Scheme. Similarly to that module, this library manipulates the C code directly before it is compiled to a native binary. It is not possible to call these forms at runtime. + +TODO: list of type specifiers + +- [`c-code`](#c-code) +- [`c-value`](#c-value) +- [`c-define`](#c-define) + +# c-code + +*Syntax* + + (c-code CODE ...) + +Insert C code directly into the compiled program. Each `CODE` parameter must be a string containing C code. + +# c-value + +*Syntax* + + (c-value CODE TYPE) + +Generate code that takes the C code specified by the string `CODE` and converts it to a Scheme object of type `TYPE`. + +# c-define + +*Syntax* + + (c-define SCM-FUNC RETURN-TYPE C-FUNC TYPE ...) + +Define a Scheme function `SCM-FUNC` returning an object of type `RETURN-TYPE`. The function will call C function specified by the string `C-FUNC` passed parameters of type specified by any `TYPE` arguments. + +For example, to define a function that calls `strlen`: + + (c-define scm-strlen int "strlen" string) + +Note that these definitions are introduced at the top-level. +