|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
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
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
void create(Configuration|void conf)
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
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
- 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
- string doc
The variable documentation
- array|void misc
- 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.
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