Module Variables

Roxen modules have other common denominators than those mentioned on the previous pages - the concept of administrator configurable variables for whatever module configuration data your module might depend on. Besides the variable types mentioned here, you may extend Roxen with user-defined data types, for which you create the widgetry, define storage methods and so on.

The module variables accessable from the administration interface are defined using defvar(), queried using query() or QUERY(), can be undefined using killvar(), may be altered run-time using set() or tweaked with using the variable object's own methods, after getting hold of the variable object with getvar().

Each roxen module may or may not choose to define any number of variables, each having a name unique to the module (to identify it when referring to it, polling or modifying its value, visibility or similar). The variable definition is shared among all instances of your module, but each module may have been set up with different operating parameters by the administrator, so their values may differ. The configuration data resides with the configuration data of the virtual server that the module is loaded in, where each instance of a module has its own region.

As a technical curiosity, it can be noted that module variables are quite memory conservative - even a huge roxen server setup with thousands of virtual servers, each with several modules loaded, won't gnaw away as much memory as would an older roxen (or any caudium) server. This is possible, since module variables that have not changed from their preset values (which is typically the case, since most variables have reasonable defaults), may fall back on that value, which can be found in the module's definition, instead of among its data.

In short: if you encounter some situation where there is reason to provide an administrator a choice of operating parameters, don't make constant declarations in your code - define module variables instead. It's easy, both for you as a programmer and for the administrator, more fault-tolerant (not having anybody meddling with your code), as robust as you care to make it (you may equip your variable objects with hooks to verify input validity, should the datatype be too lax for your own taste and purposes), it provides an easy way to document your variables, only show those variables that are relevant given the circumstances and finally - it even looks nice! (Never underestimate the value of readable code. :-)

Variable.Variable defvar(string name, Variable.Variable var)

Defines a module variable var, giving it the unique identifier name (this name is used when accessing the variable with query(), set() and friends). The recommended place to put your defvar() declarations is in your module's create() callback, such as:

void create(Configuration|void conf)
{
  defvar("location", Variable.Location("/cgi-bin/",
	 0, "CGI-bin path", "This is where the "
	 "module will be inserted in the virtual "
	 "namespace of your server."));

  defvar("errors", Variable.Flag(0, 0,
         "Report errors visibly", "If this flag "
	 "is set, errors will not only show up "
	 "in the debug log file."));
}

For info on the available variable types, and the full host of API methods available in the variable objects themselves, see the docs for Variable.Variable.

In roxen versions 2.0 and older, the defvar() API looked a bit differently (and the old-style API is still legal, for backwards compatibility) - it is mentioned here only for ease of reading and understanding legacy code:

Variable.Variable defvar(string var, mixed value, string name, int type, string doc, array|void misc, int|function|void hide_if_true)

A deprecated (although it will be supported for the forseeable future) compatibility version of the function. This is how you read its parameters:

string var

The variable identifier

mixed value

The default value

string name

The name of the variable that gets presented in the admin interface

int type

The type of the variable (one of the TYPE_ defines defined in module.h). These constants correspond to the various Variable.Variable classes (similarly named minus the TYPE_ prefix) used in the new API.

string doc

The variable documentation string

array|void misc

Additional type-dependent data

int|function|void hide_if_true

The constant 1 to always hide the variable from the administrator, 0 to never hide it, or a function returning 1 when the variable should be hidden and 0 otherwise.

mixed query(string var, int|void ok)

Query the value of the variable var. If ok is true, it is not an error if the specified variable does not exist. Instead, UNDEFINED (the value 0 with zero_type()==1) is returned.

QUERY(var)

Compatibility/convenience macro defined in module.h that is synonym to query(), apart from its syntax. If you prefer the syntax QUERY(var) to query("var"), feel free to use that instead. There used to be a speed difference in older versions of roxen, where the QUERY() method was slightly faster (didn't perform any error checking), but that is no longer the case.

int killvar(string var)

Undefine the previously defined variable var. This is useful mainly when inheriting another module (filesystem.pike, for instance), and all of its variables do no apply to your extended or otherwise modified version.

void set(string var, mixed value)

Set the variable var to the specified value. Typically used when you have invisible variables where you save some form of module state that should survive a server restart, but that is not meaned to be modified by an administrator.

Variable.Variable getvar(string name)

Return the variable object associated with the specified variable.