ExplicitGlobals Module

With regard to the handling of "undeclared" variables, Lua follows a rather "unusual" approach: every assignment to a Lua "name" (as defined by the Lua syntax [1]), which has not yet been explicitely declared as the name of a local variable, automatically creates a global variable. This behaviour is rather unpleasant insofar as "local" typing mistakes result in global consequences - normally, a scripting language without the capability to check for such mistakes should at least try to keep their side effects as local as possible...

The ExplicitGlobals module helps to locate mistyped variable names in assignments and expressions (at run-time) by the detection of accesses to not explicitely declared global variables. In this way typing mistakes immediately cause the application to be aborted (indicating the location within the source code where this problem occured) rather than to continue running - and producing defective results or crashing sometime later (with the need for time-consuming debugging sessions).

Technical Description

The idea for the ExplicitGlobals module came from a section found in the Lua FaQ ("How do I declare variables?", [2]) which also indicated the principal implementation.

The ExplicitGlobals module keeps (the names of) all registered global variables in a local table called declaredGlobals. Initially, this table is loaded with the names of any already existing global variable - in that way, these variables become "predeclared". The (global) function global then allows to "declare" further variables by a simple registration of their names.

Additionally, ExplicitGlobals registers two tag methods (one for each of the events "getglobal" and "setglobal") for the value nil (since non-existing global variables implicitly contain that value). As a consequence, any attempts to access a non-existing global variable will now lead to an invocation of one of these tag methods. When trying to set a non-existing global, the corresponding tag method will check for a proper registration of the requested variable and - if such a registration exists - perform the requested assignment. If the global has not been registered before, the method will issue an error message and abort the chunk. Similarly, when trying to read a non-existing global, its value (namely nil - because the tag method has been registered for nil values only) will only be returned if the global's name appears within the (internal) list of declared globals.

As soon as a given global has been set to any other value than nil, further accesses to that variable will not lead to the invocation of any of the described tag methods. Thus, the observation of undeclared globals will not result in a permanent performance penalty.

Function Reference

Upon successful execution, the ExplicitGlobals module will have registered the following global function:

global (...)

registers any given argument (which must be of type "string") as the name of a global variable (or function). Multiple registrations are allowed, the given names are not checked to be valid Lua names;

Additionally, it will have registered two tag methods (one for each of the events "getglobal" and "setglobal") for the nil value tag (i.e., the result of "tag(nil)").

Usage Notes

The script file for this module may just be executed from within an application by means of the built-in Lua function dofile (the script safely handles any attempts to run it multiple times). With the assistance of the author's LibrarySupport module, you may, however, prefer to import it:

--**** load any definitions required by this script ****

  if (type(import) ~= "function") then
    dofile("LibrarySupport.lua");  -- provides a simple library import mechanism
  end;

  import("BasicDefinitions");      -- provides basic definitions for Lua scripts
  import("ExplicitGlobals");  -- requires global var.s to be explicitly declared

In that case, please keep in mind that

• the LibrarySupport script file must be copied into the same directory where the application resides;

• the ExplicitGlobals script file must reside in a directory where it can be found by the import function, i.e., a directory which is part of the LuaLibList;

Source Code

The source code of this module is available for download:

• ExplicitGlobals.lua (ASCII file, 6080 bytes)

References