The new scripting feature of FlyingSticks allows a user authored script or program to take control of some aspects of the ballistics calculator. Scripts are written in the Lua scripting language.
Scripting requires some programming awareness. That said, simple scripts can be very simple and easily understood, especially when starting with example scripts. Lua has a linear learning curve, so simple tasks are simply authored, however more involved tasks may require some learning. As scripting languages go, Lua is quick to learn, yet has a surprising depth and capability. Lua is widely accepted as the best of class scripting language. FlyingSticks supports the full set of standard libraries for scripting. See the Lua 5.3 Short Reference Manual and the FlyingSticks' Lua Extensions page for more detailed information.
The scripting interface is simple and largely obvious. Files associated with the scripts and results are retained within the app's sandbox, but may be exported when needed. Script edits are saved automatically, so the script programmer needs to be aware that deleted code is lost for ever unless actively saved in another file. It is often best to edit a duplicated copy of a script.
The Scripts and Results area is a split view with a dividing bar that may be dragged up of down to make one panel more dominant than the other. The bottom panel is the script editing area and the top panel where the results of running the script are presented.
Should the divider bar not be visible, it is because it is at the top or bottom edge. The cursor will change to a one-way drag style when hovered over the hidden bar.
Note: there is a known bug in the Results view where some characters are not shown correctly. (This is associated with how UTF8 characters are piped from Lua into this view).
This is an editable text area with all the expected capability. In addition, when there is an insertion point or selected text, the "Action>Independent & Control Variables" and the "Action>Dependent Variables" main menu items allow you to select and insert variable names directly into the script text.
The simplest way to introduce externally generated files or code snippets is to copy and paste.
Files with a ".lua" extension may be imported via the File>Import>Script(s) menu action.
This allows selection, creation, duplication and deletion of scripts. Lua script files are listed in alphabetical order. Selecting one will save the current script then open the selected script.
Note that the two example scripts "xample1.lua" and "xample2.lua" may be edited and saved, but if deleted will be restored to their originals when FlyingSticks is re-launched. The "Reload Example Scripts" option will overwrite the example scripts with their originals. Best to duplicate then edit if you would like to retain your edits to these scripts.
Below the script list are four actions: "New Script ...", "Duplicate a Script ...", "Delete a Script ..." and "Reload Example Scripts" that are self-explanatory. The first three operations present a short dialog with the opportunity to name or select a file.
Provided there is one or more script file(s), one will be active. Obviously if there are no scripts, the duplicate and delete operations are not possible.
Executes the selected script after saving the file.
The printed script results (if any) are shown in this area. The results may be notated or edited before saving and exporting.
Saves the results text to an internal file from where it is then exported to a destination of your choosing. The results text may be edited and annotated in the usual way before exporting.
Access to FlyingSticks data is via a small set of custom Lua functions that are prefixed with "fly." and predefined global variables prefixed with "pv.". These can be seen here. The functions essentially mimic user actions within the calculator.
Most data fields can accept an expression preceded by the "=" character. The expression is transformed to a chunk of Lua code by prefixing and post-fixing some statements and replacing the "#" marker with the field's current value. By way of an example, the expression:
"= # * 1.01"
is transformed into a Lua chunk that is executed immediately:
"local cVal=fly.get(N,"CU"); local result=cVal * 1.01; fly.set(N, result, "CU")"
where "N" is the index of the
field. This simple example takes the current value of the field and
multiplies it by 1.01. There is no extended Lua environment beyond the
field's chunk. ("Chunk" is the official Lua technical term for a
collection of executable statements - it has a nice ring to it!).
The following is a list of approximately 350 variables that may be accessed via a script. Basically, any variable seen in a calculator panel may be inserted.
The content of this table is available in varName.html which is exported to the Reports folder.
The variables are also available from the "Action>Independent &
Control Variables" and the "Action>Dependent Variables" main menu items
for reference. This source allows you to select and insert variable names
directly into the script text field.
Note that if the script panel is not open, the "Action>..." results in
the name being copied to the clipboard.
Round names are available in a similar fashion to variables via "Action>Rounds". If the "option", "control" or "command" key is pressed when the round is selected, the current round is changed to the selected round without inserting the round name in the script or onto the clipboard.