using Lua Plugin

What is Lua Plugin?

Lua Plugin is a REALbasic plugin that allows execution of Lua scripts from within a REALbasic app. For documentation on the Lua language please see www.lua.org. The API is similar to the RBScript API. There is a Print event that is called when Lua wants to print something, and an Input event when Lua needs input from the user. Lua Plugin has been built with Lua 4.0.

Using Lua Plugin

Drag Lua Plugin to the Plugins folder in the REALbasic folder that contains the REALbasic app. Launch REALbasic. A new Lua class is now available. There are two ways to instantiate Lua. Either make a subclass that will appear in the project window. Or, command-click in a window and make a new Lua directly. I prefer the second way as Lua will appear in the window's list of controls and creation and deletion is handled automatically. There are two Lua events: Print and Input. Print will be called in response to the print() Lua method. Input will be called in response to a new Lua method that I have added called input(). Note that, at present, the Lua IO library has not been included in the plugin. I plan to include it in the future, but, for technical reasons, I have decided to ship Lua Plugin without IO library support.

For those interested in the technical details of the IO library situation, here goes. I have an app I have released in the past called Stella, which is a Lua development environment. I do support some of the IO library in Stella. But that support is a horrible hack. I did it by creating my own console functions to be called by Lua's standard IO calls. The problem with that approach is that when Lua calls a standard IO function, such as fputs(), and control reaches my console function, I have no way to know which instantiation of the Lua class in REALbasic is responsible for the IO call. So I squirrel away in a static variable (VeryBad™) a pointer to the currently executing Lua. Then when my implemention of ReadConsoleChars() gets called, I assume that the saved Lua is the caller. But this just can't work if there are multiple Luas all executing concurrently. This may not be possible given the current state of the code, but it just isn't safe and I don't like it. So in Lua Plugin, I punted on the IO stuff and instead created a new input() Lua method that will cause the Input Lua class event to fire. This mirrors the way RBScript does its thing.

Note that although I have modelled RBScript for Lua Plugin's Input and Print events, I have not implemented the other features of RBScript, such as the ability to execute only part of a script. I will look into that for a future release.

Source

If you have downloaded the version of the plugin that comes with source, here are a few notes:

Although the source is free to use, modify, and distribute as you see fit, amianduri holds the copyrights to it. Please read the COPYRIGHT file for details.
The project that comes with the source is for Metrowerk's CodeWarrior 7. I have not tested it with any other version of CodeWarrior (nor any other development tools, for that matter).
The plugin cannot be built right out of the box. It requires two other components. The first is the Lua source, which can be downloaded from the Lua website at www.lua.org. Make sure to get the released version of Lua, which is version 4.0. The second component is the REALbasic Plugins SDK, which can be obtained from REAL Software at http://webster.realsoftware.com/realbasic/about/plugins.html. Make sure to get the 4a1 SDK. Place both the Lua source folder and the REALbasic Plugins SDK folder in the Lua Plugins project folder, which is located in the Lua Plugin folder. Open the LuaPlugin.mcp project file in CodeWarrior 7 and build the Create FAT Plugin target. This will create the "Lua Plugin" in the same folder as the project. Lua Plugin is a FAT plugin in the sense that it contains two versions of the plugin in one file. One version works with the PPC version of REALbasic and one version works with the Carbon/MacOS X version of REALbasic. There is no 68K version of Lua Plugin.
There is one incompatibility between the Lua source and Apple's Universal Headers for Carbon, which I have attempted to solve. One of Apple's files is called Debugging.h, and it contains a macro called check. Unfortunately, there is a check() function in lparser.c in the Lua distribution. As a workaround, I have undef'd the check symbol in the file CommonCarbonPrefix.h. That should allow the Lua source to compile in the Carbon build of the plugin.
There are several incompatibilities between CodeWarrior 7 and the 4a1 REALbasic Plugins SDK. The primary problem is that two files that are included in PluginMain.cpp of the SDK are no longer part of the CodeWarrior installation. Those files are SetupA4.h and A4Stuff.h. Those two files do not provide any necessary functionality for either the PPC or the Carbon builds of a REALbasic plugin, but without them PluginMain.cpp won't build. I have provide of these files that will allow the Lua Plugin to build. It is important to note that these two files are not part of the REALbasic Plugins SDK.
One other issue that may be of some concern is the fact that the function __sinit() is not called for the Carbon version of the Lua Plugin. This should not be a problem. __sinit()'s job is to call the constructors of any static objects. Lua Plugin does have one static variable. But it is not an object. So the lack of a __sinit() call should not be a problem.

Acknowledgments