The AFWI Command Lua Library.

The purpose of this distribution is NOT to create a useful Lua Library for Command.
I'll leave that to you.

The purpose of this distributaion is to showcase a method for organizing the extensive
Lua code that goes into building a useful library in a way that allow the developer to
build, test, maintain, and distribute the library in an easy way that allows for
versioning. 

The first key to this is organizing the code.

All Lua functions are organized into namespaces, and sub namespaces (lua tables)
The directory structure of the code base reflects this structure, and each function is 
in its own file. THe leaves no question as to where to find errant code.

In addition to this test files are created in a parallel directory structure (Test)
with all tests for a single function go into a single file. This allows easy location
of the tests for a specific funciton.

This directory structure is allowed by the linking functions found in the main AFWI.lua script.
These function link the disparate files together within the Lua execution memory of Command
by calling ScenEdit_RunScript appropriately for the files in a consistant manner. The effect
of teh AFWI.Load funciton is to drop the body of the file into the memory at the location of
the call. The load funciton, will optionally load the test code (if AFWI.Test is > 0)

For the developper the process of loading the library into the Command memory of a scenario
is a matter of executing a single line of code (one time):

    ScenEdit_RunScript('../../Scenarios/AFWI/Lua/AFWI.lua')

Once this call is made in the console, the code generates an event to reload the code upon 
loading the scenario.

The developper may execute the tests for the code by setting the test flag to 1 (or greater)
just prior to loading the scenario, and all the tests will be executed upon loading the library
(when loadingthe scneario).  This allows the developper to retain confidence in the correctness
of the code base, as errors are immediately visible. (Assuming complete code coverage)

Note: this distribution does not have complete code coverage: many of the test files are empty 
except for a comment indicating that the test file was reached by the system during testing.  
It is up to the developper to create test code at the time of coding any function. In this 
distribution the Wx module has 90% code coverage, and the Verify module has 100% coverage, while 
the Side module has 0% coverage. (coverage means % of code base exercised by the test code).

Installation instructions for Developers:
1. locate the installation directory of your command installation (version 1.14.2 or higher)
  This should be C:\Program Files (x86)\Command, or something like that.

2. Browse to the Scenarios Directory under the Command installation directory.

3. unzip the contents of the AFIW_lua_lib.zip into the Scenario Directory.
   (This should put an AFWI Directory directly under the Scenarios directory)
   (under the AFWI diretory should be a Lua Directory and a Komodo Dragon directory.)
   (Under the Lua directory should be a Side directory and a Wx directory)

4. Open your command installation, and create a new scenario in edit mode.
5. Follow the instruction in AFWIinit.lua (found in the new Lua directory)



Discussion:

The Library contains 2 main files:
AFWIinit.lua  --the module responsible for loading the library into the scenario.
AFWItest.lua  --the module that defines the testing mechanism

The AFWI Lua is a build of many indvidual lua function files, that are tied together 
using the library's RunScript function. This allows for individual development and 
testing of the functions as they are developped.

In the AFWI.lua file, there are two (2) flags that control debugging and testing.

AFWI.Debug.
AFWI.Test.

To execute the unit tests and prove correctness, set AFWI test to 1 (or higher)
To see debugging information, set AFWI.DEbug to 1 (or higher)
Then load the libarary using the instructions in AFWIinit.lua.

If you save your new scenario, as per the directions, then the library will load when you
open the scenario. For this to happen, the files must be on the installation. The lua 
functions are not stored with the scenario.  When loading a scenario with the AFWI library,
ou should shut down the COmand program and force a new Lua State. You should not trust the
Lua state in the GUI, as there is no telling what the previous user did in the state.




DISTRIBUTION OF THE LIBRARY

So you do not want to sent a bunch of files to the end-user because this could be fraught
with unending troubles. I agree.

Command has a scenario attachments, which can be used very well to hold your code, only it
was built to hold a single file. To allow for this, the distribution has two batch files.

    writeFile.bat
    generate.bat

Think of the writeFile.bat as a pseudo make file. It is a batch file that brings together the
other files. It is really a simple batch file derivation of teh main AFWI.lua file.  In fact
when you add modles or functions to the main lua file (in this case AFWI.lua) you should make
comparable changes to the writeFile.bat. Alternately, just maintain the luia script, then when
you want to istribute the library, recreate the writeFile.bat. THe logic is siple enough.

The following batch commands were used to create the writeFile.bat file:
echo     write a line to the screen.
type     writes a file to the screen.
SETLOCAL makes variables in the script local (they go away at the end of the script)
SET      sets a variable
REM      remark (comment) -- preserved for ease of comparing to the original lua file.

If you were comfortable with batch files and DOS commands, this file is all that is needed
as it actually combines the text of teh script (echo statemnts) with the files into one stream
(sent to teh screen).


To make life easier, I have also created the generate.bat file.
Here is it in its entirety:

@echo off
SETLOCAL
SET LIB_VERSION=0.1.0.0
echo Setting Library Version to: %LIB_VERSION%
echo Writing Library: AFWILuaLibrary_%LIB_VERSION%.lua
call writeFile.bat %LIB_VERSION% > AFWILuaLibrary_%LIB_VERSION%.lua
echo done

line-by-line explanation:
turns off the command echo
sets all variables local
sets the LIB_VERSION variable to 0.1.0.0
writes to the screen: Setting Library Version to: 0.1.0.0
writes to the screen: Writing Library: AFWILuaLibrary_0.1.0.0.lua
calls the writeFile.bat, passing in 0.1.0.0 as the first parameter, redirects the screen output to
   AFWILiaLibrary_0.1.0.0.lua


In short, executing generate will create a single file based upon the version number.
YOu should modify the generate.bat file as needed to set the library name to your library.


Once you have a single lua file, with the version as part of the name, you are primed for
using the atttachment process of Comand to distribute your library.  THe library itself,
upon load will re-load.

When creating a scenario that uses the library, the library must be recognized as an attachment
in your installation of Command.
Then you must actually enable that attachment within your scenario.
Then you must execute the lua line: ScenEdit_UseAttachment('Lua Script: AFWILuaLibrary.lua')
(alter with your library name, as needed)
At this point your library is fully active and available in teh scenario.
Further, if you save the scenario, it becomase available upon scenario load thereafter.
--the event to load the library is autobenerated by the library)
Then execute the command: Scen








