BasicDefinitions Module

The set of intrinsic Lua functions has been deliberately kept small by the designers of that language. As a consequence, there is a certain need for extensions, which - however - vary from programmer to programmer. The BasicDefinitions module presented here contains those functions the author needs for his daily work with Lua.

Function Reference

Upon successful execution, the BasicDefinitions module will have registered the following global functions (listed in alphabetical order):

assert (Condition, Message)

like its homonymous intrinsic counterpart (which the new function replaces), "assert" checks the validity of a given assertion, aborting the program with an error message in the case of a failure. Unlike the original, however, the error message is not prefixed with the text "Assertion failed";

encodedString (Value) -> string

replaces any non-printable (control) characters found in Value (which must be of type "string") by corresponding escape sequences. The result may then be output to stdout without risking side effects because of the interpretation of any control characters;

isBoolean (Candidate) -> boolean

checks if the given Candidate is either set to "true" or to "false" and, thus, denotes a "boolean" value in the sense defined by the author (see below for explanation);

isFileHandle (Candidate) -> boolean

checks if the given Candidate denotes a "file handle" (as returned by some Lua file functions);

isList (Candidate) -> boolean

checks if the given Candidate denotes a "list", i.e., a table with numerically indexed elements only (exept the element "n" which is foreseen to store the "size" of this "list");

print (...)

unlike its homonymous intrinsic counterpart (which the new function replaces), "print" also "knows" how to print (plain or nested) tables and "objects" with their own "toString" (or "tostring") method;

strabbrev (Candidate, Template, minLength [, ignoreCase]) -> boolean

checks if Candidate (which must be of type "string") contains a valid abbreviation of Template (also a "string") with a length of at least minLength (a "number") characters. The optional ignoreCase ("boolean") specifies if Candidate has to respect the case given by Template or not;

strtrim (Argument) -> string

returns a copy of Argument (which must be of type "string") after removal of any leading or trailing blanks;

tostring (Argument [,NestLevel]) -> string

yields a literal representation of Argument. How this representation is constructed, depends on the type of Argument: nil values yield the string "nil", numbers are converted as usual, strings yield themselves, and userdata or function items yield the text "(userdata)" or "(function)", resp.. Tables with their own "toString" (or "tostring") method will be converted by that function. "Lists" (i.e., tables with numerically indexed elements only - except their size field "n") are represented by a comma-separated sequence of elements (in the ascending order of their indices), "tables" (with non-numerical indices) by an unordered sequence of key-value pairs. Table "keys" are directly converted, table and list "elements" by a recursive call of "tostring". The deepest allowable recursion level is given by the global variable toString_DefaultNestLevel (which is set to 4 by default);

toTk (Value)

The Lua interface to Tcl/Tk (TkLua) seems not very robust when transferring strings to and from Tcl - certain string contents may crash the tkeval functoin (and, thus, the whole application). The toTk method therefore returns a copy of the given (string) value in which any "dangerous" characters have been replaced by corresponding escape sequences (Note: for the time being, the method just returns the given string unmodified - but it is planned to implement it as soon as possible);

validSymbol (Candidate)

checks if Candidate (which must be of type "string") denotes a valid Lua identifier;

write (...)

after conversion to a string (using the tostring function described above) write outputs any given arguments on stdout (without trailing newline character - several calls to write will therefore output their arguments in the same line);

writeln (...)

after conversion to a string (using the tostring function described above) write outputs any given arguments on stdout - and finally proceeds to the next output line. writeln therefore equals the print function described above;

Additionally, the script will have defined the following global data fields (in alphabetical order):

false

as the author is used to explicit boolean values, this "variable" simply represents the logical (Lua) value for "false". (Note: since Lua does not distinguish between non-existing fields and those set to nil, but nil represents the logical value for "false", the homonymous global variable actually does not exist! Thus, the "definition" of such a data field should simply be regarded as a "convention" to describe a boolean value);

toString_DefaultNestLevel

limits the nest level of recursive calls to the tostring (or toString) function. It is currently set to 4;

true

as the author is used to explicit boolean values, this "variable" simply represents (one possible) logical (Lua) value for "true" (Note: since any Lua value other than nil is regarded as "true", the homonymous global variable should never be used for comparisons but only for assigments or, e.g., as an argument for return etc.;

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

In that case, please keep in mind that

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

• the BasicDefinitions 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:

• BasicDefinitions.lua (ASCII file, 15740 bytes)

References