Including simplelib in a Project
Contents
Dofile Call
The simplelib.lua file belongs in the lib/ subdirectory of the openeuo root directory. To use simplelib, include the following line at the top of the dependent script:
local sl = dofile(getinstalldir()..'lib/simplelib.lua')
That's all it takes to begin using simplelib. This initializes the library and assigns its interface to the local variable sl. In order to avoid usage errors, the interface is a special table which guards against user modification. Attempting to add new keys to the table or referencing non-existent keys will result in an error.
Version
You can check the version of simplelib with the interface method slversion():
local v = sl.slversion()
Version will always be a monotonically increasing real number. Current version is 0.07 as of 20110103.
Case of Member Names
In version 0.06, a pattern matching metamethod is incorporated which allows any partial, unique specification of a library member name to call the correct method. Additionally, while the default case of all methods is lower case, any case specified will match properly. E.g.,
local v1 = sl.SLVers() local v2 = sl.slVersion() local v3 = sl.ioN() -- pretty obtuse, but a unique pattern match print(tostring(v1 == v2 and v2 == v3))
--> true
This matching feature is incorporated to enable user to choose the case of member names as desired; it shouldn't be used to obfuscate code.
A Note on the Object Model
See Programming in Lua -- Private Objects to understand the employed object model. Objects are implemented as closures, so the colon calling syntax typically seen in object oriented lua code e.g. object:method() is never valid to use with simplelib objects or tables. Just use the dot operator, e.g. object.method(). This applies to the object returned by the initial dofile call, as well.
Further, private metatables are set on all interfaces to deny any accidental deletion and overwriting and to raise errors if invocation is attempted on non-existent (or misspelled) methods. For this reason bulk importation of the library names into the _G environment is discouraged as capture of logical errors is diminished and case and partial name matching aren't available.
Intermediary Library Authors
Calling dofile() on simplelib.lua multiple times is unnecessary but will cause no harm unless the global environment guard variable simple_lib_soliton__ is overwritten. That's the only value/variable defined by simplelib in _G (the global environment) by default. Calling simple_lib_soliton__ returns the unique interface table of simplelib, it can otherwise be ignored as it serves no direct purpose to the end user.
