The Edit Macro support in SPFLite provides a means to automate complex or repetitive editing tasks, and to create functions not available with SPFLite's existing built-in edit commands.



Operating Modes


SPFLite supports running macros in two modes.


First, as Primary commands. As primary commands macros can utilize operands coded on the command line following the macro name and can also utilize line ranges marked via the built-in line commands. e.g. a primary macro can reference line ranges marked with CC/CC markers.


Second, as Line commands. Line command macros can utilize either single line or block mode line marking. Being line commands, these macros usually have short names. Whether a line command is considered a single line or a block mode line command is discussed in the next section "Macro Format and Structure".



For Line command macros, because of their nature,  there are some additional restrictions on usage


    • Line command macros cannot be entered at the same time as commands on the command line.


    • Only one line command macro at a time may be entered; and only one instance of that macro. e.g. for the macro AX you could not enter a series of individual AX line commands. A pair of block mode AXX lines is considered one instance.


    • Line command macros can not be entered at the same time as other built-in line commands which are considered 'source' line markers, like CC or MM, since line command macros are themselves always treated as a source range.



Script Engine


The script engine chosen to support the macro facility is called thinBasic (www.thinBasic.com).


Don't let the word "thin" fool you. thinBasic is no "toy" language. This is a very capable script engine written in, and modeled after, PowerBasic (www.PowerBasic.com). Since SPFLite itself is written in PowerBasic, the interface between SPFLite and thinBasic is quite straightforward, which makes possible a highly efficient implementation. All of our test scripts have run very quickly, and you should see similar good performance as you write your own scripts.


Being a BASIC variant, users with experience in typical programming or scripting languages should recognize most of the thinBasic syntax. Many sample macros have been provided to help you get started.


As you will quickly notice, keywords and syntax in thinBasic, like SPFLite, are case-insensitive. When you read the documentation and sample code that follows, the choice of capitalization you see is simply a style choice. You are free to capitalize (or not) any way you see fit.


thinBasic components are included in the normal SPFLite install, so no separate install of thinBasic itself is required. If however you would like to explore thinBasic as a normal scripting language, then you should obtain their full install package and install it. We recommend, as of this writing (May 2013), you install release 1.9.6.


If you go that route, be prepared for a lot of reading. The full thinBasic help document is included in the basic SPFLite install, and can be accessed from the Start Menu SPFLite program group, or from within SPFLite itself by entering HELP THINBASIC.  You will be surprised how much is in it. By way of full disclosure, you may also find that some of the documentation is incomplete. The developers of thinBasic tend to develop first and document later. It's a nice package, but it is what it is.


This document is organized into the following sections.


    • The SPFLite interface. This contains the reference documentation for each of the SPFLite interface calls.


    • Working with the interface.  This contains tutorials on interface techniques:  How to handle command parameters, how to search for and manipulate text lines, how to create a new Line command, how to control the edit cursor location, etc.


    • Sample macros. Several of the included sample macros are shown with full comments.


    • thinBasic essentials.  This is a simplified introduction to thinBasic. It is not a complete and definitive description of all thinBasic capabilities and functions, but should be enough to get you by. For more than that, refer to the thinBasic Help file as described above.



Working with the thinBasic Interpreter


As interpreters go, thinBasic is quite sophisticated. However, it remains a true interpreter. What that means to you is that it does not perform a "full program parse" before beginning to execute your script. Instead, it reads, parses and executes a line at a time. So, if you have a macro that's 10 lines long, and there is an error in line 10, it will perform the first 9 statements, then halt with an error-detected message. You will have to correct your errors one at a time until you get past this.


In practical terms, you may find it beneficial to write larger macros in pieces, starting small and testing a bit at a time, and adding more code as you go along, to minimize any problems from syntax errors you might introduce into your code.


You can also develop "pieces" of thinBasic code and #INCLUDE them into your macro. Doing this is a way to 'modularize' your code, so that you can deal with tested pieces of thinBasic code that you know will work correctly. This is a technique that might help you if your macro is quite large. See the thinBasic documentation regarding the #INCLUDE statement. Note:  At this point, the #INCLUDE statement does not appear to handle unqualified file names consistently. Until this is resolved, it would be prudent to fully qualify the included filenames.



Created with the Personal Edition of HelpNDoc: Generate Kindle eBooks with ease