Introduction

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






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.







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.



Handling of Block Mode Line-Command Macros


As of version 8.0, when a "built-in" SPFLIte line command is longer than 1 character, the "block mode" name of the command is formed by repeating the last letter.  For example, the command UC becomes UCC.  In the past, we also supported the "command doubling" method, where UC would become UCUC.  By supporting two different forms, this complicated the documentation for line commands unique to SPFLite, and causes issues for user-defined line commands implemented as macros.  To avoid those issues , we have chosen to simplify this, and only allow one way to make a command a "block mode" command, by repeating the last letter of the command name.


Be aware that when this change was made to SPFLite, the same change to line-command name processing was applied to macros used as line commands.  Thus, if you create a line-command macro called AX.MACRO, you can use it in block mode by specifying it as AXX but you can no longer specify it using the form AXAX.  The documentation that formerly indicated that the AXAX form was permitted has been updated to reflect this change.


Created with the Personal Edition of HelpNDoc: Free PDF documentation generator