Supporting tools for Reflexis Flow
by Ashwin Hirschi, Reflexis, October 2009 (updated: July 2014).
Having the right tool at hand, can make a world of difference when you're trying to get things done. We created our Reflexis Flow platform with this particular idea in mind. But, nothing stands alone. So...
This note describes various tools that can assist you while you develop your flows or try out Lua code. It is not meant as a manual. But it does contain descriptions of useful tools, some configuration tips and download links, to help you on your way.
Keep in mind that, as with many a tool, the use you get out of it may well depend on the time you put into it. We hope these tools will help you become more productive (or have fun while noodling).
I is the commandline equivalent of Indigo, the runtime we developed for Reflexis Flow. Though small in size, it contains a full Lua 5.2 interpreter and support for databases (SQLite), networking (sockets) and XML. It can help you develop standalone Lua programs, create library scripts to support the Flow environment, or write little utilities to perform useful tasks.
The i tool consists of an executable (i.exe), a package (i.rfx) and a boot script (i.lua). To install i, place these files in the same directory. If you put them somewhere in your PATH, i will be available whenever you open a command prompt. Since i makes no changes to your system, to uninstall it you simply delete the 3 files.
The i tool can operate in 2 modes: The standalone mode uses the i package (i.rfx) as its source for tools and scripts. The instance mode uses an instance (folder structure) to fetch its logic and data. You can switch between these modes by setting (or clearing) the INDIGO_ROOT at the top of i.lua.
If you're running Reflexis Flow on your local machine, the instance mode is handiest. Simply set the boot script root variable to your instance folder and i will know where your Flow scripts & files are. This enables you to use library functions from your own scripts and can save you lots of typing.
If you want to use i on a machine with no (or multiple) Reflexis Flow instances, it's usually best to simply clear the boot script root variable. This will put i into standalone mode and force it to fetch its logic from the i package (i.rfx).
Luac is the standard Lua compiler. It is a straight-forward commandline tool that compiles Lua source code into a binary format. We use the .lua extension for Lua source code and .lc for compiled scripts. This makes it easy to keep them apart.
Strictly speaking, luac is not necessary, since Lua (and thus Indigo and the i tool) will automatically compile a script when loading it. However, sometimes it is convenient to simply check the syntax of your script (or flow definition) without running it.
In the section on SciTE we will see how both i and luac can be integrated into a convenient editting environment so you can easily check and run your own Lua scripts. To ease configuration, place luac.exe in the same folder that you placed i.
SciTE is a well-known, free source code editor, based upon the Scintilla editting component. It provides features like a tabbed interface and code folding, can syntax highlight Lua code, and allows you to add functions using Lua script.
After you've downloaded SciTE, install it by extracting the archive and placing the SciTE folder in, for instance, your Program Files folder. If you want quick access to the editor, simply put a shortcut to scite.exe on your desktop. Like most tools in this note, you can uninstall SciTE by deleting all its files.
SciTE's "Lua-awareness" makes it easy to customise and enhance the editor. We provide three support files to get you up to speed: user.props, abbrev.props and scite.lua.
The user.props file contains settings that you can use as a base to create your own preferences. To install it, start SciTE, select "Open User Options File" from the Options menu, and then copy-paste the contents of user.props into the window. Lastly, press Ctrl+S to save, and the new settings will take effect.
File abbrev.props contains abbreviations that you can expand from within SciTE. Installing it is very similar to installing the user preferences described above. But instead of selecting "Open User Options" you select "Open Abbreviations" from the Options menu. After installing the abbreviations, try them out by pressing Ctrl+N, type "part" (without the quotes), and then press Shift+Enter.
The scite.lua script contains various primitives (think: macros) that help you navigate and build flows. If you already installed the user settings and placed the files from the i-section under Program Files, SciTE should already be able to see the helper functions. Alternatively, place scite.lua somewhere on your machine, and edit the ext.lua.startup.script entry in your user settings to match its location.
To test if all went well, press Ctrl+N to open een new edit window, and then press Ctrl+F5. The date should appear. If not, you may have to restart SciTE for the support script to actually be recognised.
The 3 support files we mention above can be found under Indigo/dev/etc (from the i tools archive). Don't forget to install them, since they make life a lot easier!
Finally, make sure the tooldir entry in your user settings points to a folder containing i and luac. This will ensure you can run and compile Lua scripts from within SciTE!
SysInternals' DebugView utility intercepts and displays Windows debug output. Since i (and Indigo) can generate debug output using the printdbg function, this can be an easy way to keep an eye on what is happening.
This facility is especially useful when running Flow on your local machine: even though all interaction goes through your browser, you can get a trace of the flow steps that were executed. And, if something goes awry, an alert will be shown.
You can install DebugView by extracting its archive and installing the files somewhere on your machine. Since Microsoft has acquired the SysInternals company, you will need to agree to its license the first time you start DebugView.
Lastly, it's worth your while to read up on the various options (and command keys). I suggest you also set a decent display font, like Tahoma, since the default one is not so great. Also, it makes sense to check the Auto Scroll, Force Carriage Returns and Show Milliseconds options.
Also, make sure both Capture Win32 and Capture Events are checked (in the Capture menu), or it's unlikely you'll ever see anything appear in the listview.
SQLiteSpy is a simple and compact GUI utility to work with SQLite databases. You can use it to inspect database schemas or run queries (and other statements) and see the results. SQLiteSpy has several handy features:
For example, when you perform a query, the time it has taken to run is shown in the status bar. When viewing entire tables, selecting a cell and pressing F2 will bring up an in-place edit dialog. By pressing Ctrl+N you open a new SQL editor and can take advantage of the tabbed interface. Also, note that several functions are available when right-clicking on nodes in the schema tree on the left.
You can install SQLiteSpy by, once again, extracting its archive and putting its contents somewhere on your machine. SQLiteSpy keeps its settings (mostly window dimensions and a list of recently opened databases) in a database file, called SQLiteSpy.db3.
Finally, if it's not already taken, you may want to associate .db files with SQLiteSpy. That way you can open Flow databases by simply double-clicking them in Windows Explorer.
Perhaps it deserves its own entry, but if you want something less conspicuous, there is also a commandline sqlite tool. Since it is officially part of SQLite (as sqlite3), its manual can be found here. Note that it has several interesting and/or useful commands that are not available in SQLiteSpy!
The sqlite commandline tool is part of the archive mentioned in the I(ndigo) section. If you copy it to somewhere in your PATH, you can use it easily from any command prompt.