Difference between revisions of "Including simplelib in a Project"
m (→Intermediary Library Authors) |
m (→Version) |
||
| (21 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
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: | 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()..' | + | 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. | + | 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 [http://en.wikipedia.org/wiki/Obfuscated_code obfuscate code]. | ||
| + | |||
| + | == A Note on the Object Model == | ||
| + | |||
| + | See [http://www.lua.org/pil/16.4.html Programming in Lua -- Private Objects] to understand the employed object model. Objects are implemented as [http://en.wikipedia.org/wiki/Closure_%28computer_science%29 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 == | == 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]] by default. Calling [[simple_lib_soliton__]] returns the unique interface table of simplelib. | + | 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. |
| + | |||
| + | == See Also == | ||
| + | |||
| + | * [http://www.easyuo.com/openeuo/wiki/index.php/Simplelib simplelib] | ||
| + | |||
| + | * [[dofile]] | ||
| + | |||
| + | * [[slredirect]] | ||
| + | |||
| + | * [[slversion]] | ||
| + | |||
| + | * [[slverbosity]] | ||
Latest revision as of 15:42, 3 January 2011
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.
