Chapter 9

to include a new directive, PREFIX:

MODULE = Gnome::MIME   PACKAGE = Gnome::MIME  PREFIX = gnome_mime_

XS will automatically remove the specified prefix, gnome_mime_, from the front of the 

Perl interface. After this change, test.pl needs changes to use the new interface:

# test some simple mime type recognitions

is(Gnome::MIME::type("foo.gif"),   image/gif ,  "recognizes .gif");

is(Gnome::MIME::type("foo.jpg"),   image/jpeg , "recognizes .jpg");

is(Gnome::MIME::type("foo.html"),  text/html ,  "recognizes .html");

Writing Your Own CODE

Changing the XSUB name from gnome_mime_type() to type() with PREFIX is certainly 

an improvement, but it isn't very flexible. Modifying the XSUB name beyond 

removing a fixed prefix will require a new technique writing the actual code to 

call the underlying C function with the CODE keyword. For example, to rename the 

XSUB to file_type(), I could use this XS code:

const char *

file_type(filename)

     const gchar * filename

CODE:

     RETVAL = gnome_mime_type(filename);

OUTPUT:

     RETVAL

This example shows a new wrinkle in the XS syntax: keywords that come after 

the function definition and declare blocks of C code. This is a pattern that you'll 

see repeated by most of XS. In this case, two keywords are used, CODE and OUTPUT.

The CODE keyword allows you to override the default XSUB call with your own 

custom call.

The CODE block shown previously makes use of the automatic RETVAL variable. 

RETVAL is an automatic variable with the same type as the return type in the XSUB 

definition. In this case, RETVAL is a const char * variable. The CODE block simply 

calls gnome_mime_type() and places the return value in RETVAL.

The OUTPUT block tells xsubpp which variable (or variables) should be returned 

back to Perl. In most cases, your CODE blocks will be immediately followed by an 

OUTPUT block exactly like the one shown earlier.

After this change, the tests would need to be updated to reflect the new 

function name, but underneath the call is still going to gnome_mime_type():

218