Macro Format and Structure

Contents of Article

Introduction

The format of a macro is a standard text file of thinBasic source statements stored in the SPFLite MACROS folder.

For most users, the full path of this folder will be:

C:\Users\username\My Documents\SPFLite\MACROS

The macro should be named macname.MACRO, where macname is the name with which you will be invoking the macro.

The string "macname" is also what is returned by the Get_MacName$ function. As with everything else in SPFLite, macro names are case insensitive.

Note: Because the macro's name gets parsed as part of a primary command or line command, you cannot use all legal Windows file name characters in a macro name, but should generally limit them to letters, digits and underscore.

Further, for line-command macros, the name must be even more restricted; the name cannot contain any digits, because they will be confused with numeric line-command operands. For line commands, the macro name should normally only contain letters to avoid problems. A few special characters were found to be acceptable, such as $ and @. We have not exhaustively tested every possible character, but if you can create a legal Windows file name with it, it will usually be valid as a macro name, except for the characters + - * ? : . / and \.

Macro Names vs Actual Command Names

While macro names are usually chosen to be unique, you may name a macro the same as a normal, built-in SPFLite command. e.g. You could name a macro ALIGN. If you do so, your macro will replace the normal command. That is, there is no more access to the normal ALIGN internal command. EXCEPT - the normal internal command can always be accessed from within a macro via the SPF_CMD(command-name)

Edit mode Line Macro names and Block Mode

For single line macros (e.g. do THIS to a single line) there is no problem, the line command = the macro name.

When you want to create a macro that can act as a block mode command (like CC/CC) the following methods are used:

Repeating the last character of the line command. Using the same example as above, the block form of AX would be requested by entering AXX/AXX, and the macro still stored as AX.MACRO. This applies also to longer macro names. For example the block mode version of a macro called BOX would be BOXX, or for a macro called PRINT it would be PRINTT.

Specifically tell SPFLite in what mode a macro name is to be treated. This is done by issuing a SET command of the format:

SET MACROMODE.macname = BLOCK | LINE

If a SET MACROMODE has been issued for a macro name, the convention about repeating the last letter does not apply. Any length or format of macro name can be set unconditionally to a specific processing mode.

The only requirement SPFLite imposes on the format of a macro file is the macro prototype (or header), which must be the first line in the macro. Like everything else in SPFLite, the prototype is generally case-insensitive, unless it has default operands used as string values in FIND or CHANGE commands, for instance.

Macro Prototype

The first line of a macro must always be the macro prototype. This is a simple thinBasic comment statement of the format:

' macname.MACRO [ def-operand-1 def-operand-2 ... ]

The .MACRO part of the prototype is required. macname itself is optional, but should normally be the name of the macro. The brackets shown mean the list of operands is optional; don't actually code brackets here.

Currently, SPFLite does not demand that macname, if coded, match the actual file name of the macro. However, for documentation purposes, it is best that you do make the name agree, just to keep things straight as you develop and use your macros. It is possible that a later release of SPFLite will require that the prototype name agree with the file name, so it's best to make them agree now.

You may optionally enter default values for macro operands (if your macro uses command-line operands). These are simple space-delimited strings which provide defaults if the relative operand number is not overridden when the macro is called. For example, given the following prototype:

' sample.MACRO aaa bbb ccc

If the macro were invoked with the primary command line as Sample with no supplied arguments, then if the executing macro requested the number of operands via Get_Arg_Count it would receive 3. Get_Arg$(1) would be aaa, Get_Arg$(2) would be bbb, and Get_Arg$(3) would be ccc.

More details on retrieving macro operands and working with them will be found in Accessing Command Line Operands .

Macro Code structure

As described above, an SPFLite macro program is essentially "open code" in thinBasic and has no "structure" per se. By that, it means there is no MAIN Sub/Function, execution just starts at the first line and continues on.

As a result, there is, by default, no built in mechanism for SPFLite to 'pass in' the operands. This is easily correctable by making the mainline code into a thinBasic SUB routine. If this is done, then the command line operands can be made available as passed parameters.

Before making this decision you should evaluate how you wish to handle your declared variables. In Open Code, all DIM'd variables are effectively Global and are 'visible' throughout your program. If you convert to structured mode and make the mainline a SUB, then DIM'd variables are only 'visible' throughout the mainline SUB. If you use additional SUB routines, then they will need to be passed any working data they require.

More details of this support will be found in Accessing Command Line Operands.

Created with the Personal Edition of HelpNDoc: Effortlessly Support Your Windows Applications with HelpNDoc's CHM Generation