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:

SINT

integer in C, exact number in Scheme

SUNS

unsigned in C, exact number in Scheme

SREAL

real in C, real in Scheme

SBOOL

unsigned in C, boolean in Scheme

SSTRINGC

const char * in C, string in Scheme

SSYMBOLC

const char * in C, symbol in Scheme

SSTRINGS

string (special kernel type) in C, string in Scheme

SSYMBOLS

string (special kernel type) in C, symbol in Scheme

SANCHOR

pointer to struct anchor in C, anchor proxy in Scheme

SHANGER

pointer to struct hanger in C, hanger proxy in Scheme

SO_type

pointer to struct type, which is descendant of struct o in VRR object hierarchy, in C, go or obj proxy in Scheme.

SW_type

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");
     
          TRANS_BEGIN(err_buf)
                group_relink_selected_go((struct go_group *) in_SO (ar0),
                                         (struct go_group *) in_SO (ar1),
                                         (struct go *) in_SO (ar2));
          TRANS_FAILED
                throw_transaction_failed (err_buf);
          TRANS_END
     
          return retval;
     }

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