diff --git a/cogent/doc/antiquotes.org b/cogent/doc/antiquotes.org index a1ec8818b..84d2cc2db 100644 --- a/cogent/doc/antiquotes.org +++ b/cogent/doc/antiquotes.org @@ -27,6 +27,7 @@ closely otherwise debugging could be a huge pain. ~$esc~: macros that should not be preprocessed before antiquoted C is compiled + * Overview Cogent is a restricted language; there are many things that Cogent cannot @@ -48,22 +49,25 @@ correctly "guess" the generated names---antiquotations. That's why the C components one write for a Cogent program is generally referred to as *antiquoted C* (it's because we borrow the syntax of antiquotes; see G. Mainland, -[[https://www.cs.tufts.edu/comp/150FP/archive/geoff-mainland/quasiquoting.pdf][Why -it's nice to be quoted: quasiquoting for Haskell]). +[[https://www.cs.tufts.edu/comp/150FP/archive/geoff-mainland/quasiquoting.pdf][Why it's nice to be quoted: quasiquoting for Haskell]]). And for accessing Cogent code from C, programmers also need a way to refer to the Cogent names. In a nutshell, in antiquoted C, programmers can write Cogent snippets (e.g. Cogent types, polymorphic function names, and many other things) and the Cogent compiler will compile each snippet in the same way as it compiled the Cogent program, resulting in a coherent set of names generated. + * Modes in the compiler + We have two different modes for handling antiquotation. One is /type mode/, with command-line argument ~--infer-c-type~. In this mode, users can only define abstract parametric Cogent types. The output will be placed to pre-defined directory, one file per monomorphised type. Each file is ~#include~'ed by the generated ~.h~ file. Another mode is /function mode/, which is enabled by ~--infer-c-func~ flag to the compiler (note: these two modes are not mutually exclusive). This mode is for everything else, and the output filename is derived from the input filename. + * Function definitions + We can define an abstract function which has been declared in Cogent. For example, in Cogent we have: #+BEGIN_SRC @@ -119,6 +123,7 @@ One thing also worth mentioning here is that, antiquoted functions (no matter fi exactly one argument, as in Cogent. Otherwise it will generate totally non-sensical code and the error message from the C compiler will not help in general. We are trying to implement some sanity checks in the antiquotation part. + * Type declarations / Typedef's Similarly, we can define *abstract* Cogent types using antiquotation. For example, @@ -161,6 +166,7 @@ struct C { ... }; // correct! * Escape sequences + Any C code which is beyond the reach of the Haskell C parser (http://hackage.haskell.org/package/language-c-quote) should be wrapped by a ~$esc~. In particular, if you have any ~#include~'ed files that don't want to be preprocessed (usually for the reason that they contain some language extensions which our C parser does not support), use ~$esc~ antiquoter to escape. @@ -171,5 +177,6 @@ For statement level directives, you need the alternative ~$escstm~ antiquote spe * Expressions + We can antiquote any valid Cogent expressions, using ~$exp~ antiquote. They will be turned to *statement-expression* in C.