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.


Macro support is available in both normal Edit / Browse / View sessions, and in the File Manager tab as well.  This provides the ability to extend the possible activities in the both types of tabs by using the powerful functions provided by the thinBasic script engine.  thinBasic provides a wide range of file related functions, it is well worth your time to do some exploratory reading.


Operating Modes


Whether a macro is an FM related macro, an Edit macro, a Line command macro or a Primary command macro, the structure and support provided to macro writers is as similar as we could make it.


But there are some differences in support for FM related macros and Edit/Browse/View related macros.:


    • Som functions are only supported in the FM environment, and they all start with FMxxxxx to easily identify them. These FM related macros will not function in a normal Edit tab.
    • Similarly, many of the old macro functions will not operate in the FM environment.  If a macro attempts to use a function in the 'wrong place', the macro will be terminated with an error message identifying which function is in error. The Function Overview section indicates which functions will operate in which environment.
    • Many of the existing functions, like those which access the environment variables, the global storage areas etc. will of course work in either environment.
    • The timing of macro invocation differs as well - This is an important distinction!:


      • In an Edit tab, line macros are processed before primary command macros or primary commands.
      • In an FM Tab, Primary Macros are executed first, followed by Line command macros, followed by built-in line commands.


Primary commands can utilize operands coded on the command line following the macro name and can use any of the supported methods for assisting in the parsing of the operands  


In the Edit tabs, primary commands can also access and reference built-in line commands. e.g. in Edit, a primary macro can reference line ranges marked with CC/CC markers.


In the FM tab, primary macros can examine and alter or delete line commands that may already be present.  They can also add line commands for execution if desired.


In Edit mode, 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 in Edit, 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, you install release 1.10.7.


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. 


This document is organized into the following sections.


The SPFLite interface. This contains the reference documentation for each of the SPFLite interface calls. It also 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: Full-featured EBook editor