Next: , Previous: Scheme bindings for VRR functions, Up: Scheme

13.4 Scheme snarfing

Files: build/snarf, scheme/glt_common.h, scheme/glt_kernel.h, scheme/glt_gui.h, scheme/scheme_def.h, kernel/guilelink.h, gui/guilelink.h

The snarf script scans the selected source headers for function prototypes written in a special manner, and for each such function it creates an encapsulation function (written to the generated source file) which is responsible for conversion of arguments and return value and which can be connected to Scheme. What does a specific header look like? snarf is looking for lines starting with SCHEME, the rest of each such line is searched for tokens – a token is a word starting with S, continuing with non-space symbols and terminated by a space symbol (which is not counted as part of the token). The string starting with the first non-space symbol after the first token and terminating with the first open parenthesis is considered to be the name of the function. The first (output) token specifies the return value of the function, the remaining (input) tokens specify arguments (in the given order).

Valid tokens are:

integer in C, exact number in Scheme
unsigned in C, exact number in Scheme
real in C, real in Scheme
unsigned in C, boolean in Scheme
const char * in C, string in Scheme
const char * in C, symbol in Scheme
string (special kernel type) in C, string in Scheme
string (special kernel type) in C, symbol in Scheme
pointer to struct anchor in C, anchor proxy in Scheme
pointer to struct hanger in C, hanger proxy in Scheme
pointer to struct type, which is descendant of struct o in VRR object hierarchy, in C, go or obj proxy in Scheme.
function accepts a pointer to a struct type, which is a descendant of struct window in VRR GUI object hierarchy; in C, a window proxy in Scheme.

There is the SVOID token representing void return value, which is valid only as an output token. The last token may be STRANS or SMETATRANS, which signalises that the given function must be called in an appropriate transaction. All these tokens are preprocessor macros (defined in scheme/scheme_def.h), so they are converted by the preprocessor to correct C source. for example:

     SCHEME SVOID group_relink_selected_go(SO_go_group source,
                                           SO_go_group target, SO_go after); STRANS

is converted by the preprocessor to:

     void group_relink_selected_go(struct go_group *source,
                                   struct go_group *target, struct go *after);

and the generated encapsulation is:

     static SCM sh_group_relink_selected_go (SCM ar0, SCM ar1, SCM ar2)
          volatile SCM retval = SCM_UNSPECIFIED;
          assert_SO (ar0, SCM_ARG1, "group-relink-selected-go", ID_go_group);
          assert_SO (ar1, SCM_ARG2, "group-relink-selected-go", ID_go_group);
          assert_SO (ar2, SCM_ARG3, "group-relink-selected-go", ID_go);
          ASSERT_GO_TRANS_SCHEME ("group-relink-selected-go");
                group_relink_selected_go((struct go_group *) in_SO (ar0),
                                         (struct go_group *) in_SO (ar1),
                                         (struct go *) in_SO (ar2));
                throw_transaction_failed (err_buf);
          return retval;

The header files kernel/guilelink.h and gui/guilelink.h are standard places to write simple functions accessible only from Scheme.