6. Defining Variables

Rarely will you write a module that only contains functions. It is common to also provide variables which can be used to control the behavior of the function, or store the results of the function being executed. The actual C variable types are the same for modules and internal XEmacs primitives, and the declaration of the variables is identical.

See (internals)Adding Global Lisp Variables section ‘Adding Global Lisp Variables’ in XEmacs Internals Manual, for more information on variables and naming conventions.

Once your variables are defined, you need to initialize them and make the Lisp reader aware of them. This is done in the vars_of_module initialization function using special XEmacs macros such as DEFVAR_LISP, DEFVAR_BOOL, DEFVAR_INT etc. The best way to see how to use these macros is to look at existing source code, or read the internals manual.

One very important difference between XEmacs variables and module variables is how you use pure space. Simply put, you never use pure space in XEmacs modules. The pure space storage is of a limited size, and is initialized properly during the dumping of XEmacs. Because variables are being added dynamically to an already running XEmacs when you load a module, you cannot use pure space. Be warned: do not use pure space in modules. Repeat, do not use pure space in modules. Once again, to remove all doubts: DO NOT USE PURE SPACE IN MODULES!!!

Below is a small example which declares and initializes two variables. You will note that this code takes into account the fact that this module may very well be compiled into XEmacs itself. This is a prudent thing to do.

Lisp_Object Vsample_string;
int sample_boolean;

void
vars_of_module()
{
  DEFVAR_LISP ("sample-string", &Vsample_string /*
This is a sample string, declared in a module.

Nothing magical about it.
*/);

  DEFVAR_BOOL("sample-boolean", &sample_boolean /*
*Sample user-settable boolean.
*/);

  sample_boolean = 0;
  Vsample_string = build_ascstring ("My string");
}

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