5. Defining Functions

One of the main reasons you would ever write a module is to provide one or more functions for the user or the editor to use. The term function is a bit overloaded here, as it refers to both a C function and the way it appears to Lisp, which is a subroutine, or simply a subr. A Lisp subr is also known as a Lisp primitive, but that term applies less to dynamic modules. See (internals)Writing Lisp Primitives section ‘Writing Lisp Primitives’ in XEmacs Internals Manual, for details on how to declare functions. You should familiarize yourself with the instructions there. The format of the function declaration is identical in modules.

Normal Lisp primitives document the functions they defining by including the documentation as a C comment. During the build process, a program called ‘make-docfile’ is run, which will extract all of these comments, build up a single large documentation file, and will store pointers to the start of each documentation entry in the dumped XEmacs. This, of course, will not work for dynamic modules, as they are loaded long after XEmacs has been dumped. For this reason, we require a special means for adding documentation for new subrs. This is what the macro CDOCSUBR is used for, and this is used extensively during ellcc initialization mode.

When using DEFUN in normal XEmacs C code, the sixth “parameter” is a C comment which documents the function. For a dynamic module, we of course need to convert the C comment to a usable string, and we need to set the documentation pointer of the subr to this string. As a module programmer, you don’t actually need to do any work for this to happen. It is all taken care of in the docs_of_module function created by ellcc.

5.1 Using DEFUN

The full syntax of a function declaration is discussed in the XEmacs internals manual in greater depth. (internals)Writing Lisp Primitives section ‘Writing Lisp Primitives’ in XEmacs Internals Manual. What follows is a brief description of how to define and implement a new Lisp primitive in a module. This is done using the DEFUN macro. Here is a small example:

DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
Sample Emacs primitive function.

The specified FILE is frobnicated before it is fnozzled.
*/
    (file))
{
  char *filename;

  if (NILP(file))
    return Qnil;

  filename = (char *)XSTRING_DATA(file);
  frob(filename);
  return Qt;
}

The first argument is the name of the function as it will appear to the Lisp reader. This must be provided as a string. The second argument is the name of the actual C function that will be created. This is typically the Lisp function name with a preceding capital F, with hyphens converted to underscores. This must be a valid C function name. Next come the minimum and maximum number of arguments, respectively. This is used to ensure that the correct number of arguments are passed to the function. Next is the interactive definition. If this function is meant to be run by a user interactively, then you need to specify the argument types and prompts in this string. Please consult the XEmacs Lisp manual for more details. Next comes a C comment that is the documentation for this function. This comment must exist. Last comes the list of function argument names, if any.

5.2 Declaring Functions

Simply writing the code for a function is not enough to make it available to the Lisp reader. You have to, during module initialization, let the Lisp reader know about the new function. This is done by calling DEFSUBR with the name of the function. This is the sole purpose of the initialization function syms_of_module. See section Required Functions, for more details.

Each call to DEFSUBR takes as its only argument the name of the function, which is the same as the second argument to the call to DEFUN. Using the example function above, you would insert the following code in the syms_of_module function:

DEFSUBR(Fmy_function);

This call will instruct XEmacs to make the function visible to the Lisp reader and will prepare for the insertion of the documentation into the right place. Once this is done, the user can call the Lisp function my-function, if it was defined as an interactive function (which in this case it was).

That’s all there is to defining and announcing new functions. The rules for what goes inside the functions, and how to write good modules, is beyond the scope of this document. Please consult the XEmacs internals manual for more details.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.