Accessing Macro Command Line Operands

Contents of Article

Introduction

Except for the simplest of macros, command line operands are necessary to tailor the actions performed by your macro. So, retrieving and 'sorting out' what operands have been entered is a necessary requirement for most macros. The SPFLite macro support provides three methods for handling the operands. Which is best for you? The deciding factors are the number, order and complexity of the operands, whether any are optional, and whether any are keywords which possibly are part of a "keyword group". The chart below will help you by summarizing the differences in the three levels of support.

FM Line Command Macro differences

When a macro is issued on a File Manager line command, SPFLite will insert a numeric operand immediately after the macro name to indicate which line of the FM list he macro was entered on. e.g. If MYMACRO AA BBB CCC was entered on line 15 of the display, the macro would be invoked as MYMACRO 15 AA BBB CCC. That is, the line number is always the first operand, all others are shifted right.

It is important to understand how the command line operands are handled. SPFLite does an initial parse of the command line operands, which are delimited by spaces or quotes as usual, and stores them into a table, which can be accessed with the Get_Arg$ and Get_Arg_Count functions.

These operands are not initially categorized or sorted in any way. You would simply "get" them, using the functions described next.

There are three types of macro operand access, as follows:

Basic Access

The number of operands is available via Get_Arg_Count

Each operand can be accessed as Get_Arg$(n), where n is the operand position on the command line; the first operand after the macro name itself is considered operand number 1. Operands are returned as STRING values, as indicated by the $ in the function name.

If local variables are needed for processing the operand values, they must be declared in a DIM statement and assigned the Get_Arg$() value. These two steps can be combined if you wish, so that you could write DIM FIRST_ARG AS STRING = GET_ARG$(1) or these can be done as separate steps.

All validation and handling of the operands is the responsibility of the macro code you write.

SUB Operand Access

In creating the SUB structure, the operands are assigned, from left to right, to the arguments defined in the SUB statement. NOTE: You must specify at least one operand. If you have no operands, simply insert DUMMY AS STRING for the operand.

Operands are accessed using the variable names used in the SUB statement, making the code much more readable. e.g. if the first operand of the SUB statement were coded as start-line AS STRING it makes code much more readable to code IF start-line = xxx than to code IF Get_Arg$(1) = xxx as in the Basic Access mode.

Local variables do not need to be declared with a DIM statement for storage of the data.

All validation and handling of the operands is the responsibility of the macro code you write.

Full Parse Access

Most built-in SPFLite primary commands utilize 'order-independent' operands. For instance, you can say CHG FRED BILL ALL or CHG ALL FRED BILL or CHG FRED ALL BILL and SPFLite will figure out what you mean. Additionally, many keyword operands have multiple aliases, such as PREFIX, PRE, and PFX. Handling all these variations of operand formats in a macro, using your own code and positional operand access methods, would be difficult and error-prone.

The function SPF_Parse does this 'sorting out' for you, identifying all the various operand types, keywords, and keyword aliases. This allows your macro to provide flexible operand handling with much less effort.

The main requirement is for you to specify with the SPF_Parse function the detailed syntax requirements of your command. This involves informing SPFLite as to how many labels, tags, numbers, string values and keywords you expect to be used.

SPF_Parse is normally be invoked at the beginning of the macro, and, if no scanning errors are reported, all the command line operands will have been categorized and set up for easy retrieval when you need them. Since this is an ordinary function like others provided by SPFLite, you are free to call this function wherever it is most appropriate for your logic.

The categorization supports operand types such as:

Line references (like .AA .BB .123)
Tag references (like :DD :S1)
Text literals (like ABC C'DEF' K5)
Numeric literals (like 10 20 30)
Keywords (like ALL PREFIX | SUFFIX | WORD)

This support includes handling of aliases and mutually-exclusive keywords.

Optional validation of Line References and Tag operands can be performed for you. Invalid (undefined) label or tag operands will cause SPF_Parse to report a syntax error. Because this process is optional, you can decide if you expect your label or tag operands to already exist, or if they might be new labels or tags that the macro itself would define in the course of its operation. To validate a label using macro code, you can try converting a label to a line pointer using Get_Lptr, where a non-zero result means the label is valid. To validate a tag, you can try issuing a command like SPF_CMD("LOC :ABC FIRST") and if you get RC=0 the tag should be valid.

Parameter validation that is specific to your macro's application must be done by your code.

Basic operand access

Using basic access, macro operands are accessed positionally by their position in the command string, from left to right. The total number of operands available is available by calling the Get_Arg_Count function. Each individual operand is obtained by calling Get_Arg$(n) where n is the operand number; the first operand after the macro name itself is operand number 1.

The macro may have default operands specified by the macro prototype line (see Macro Prototype) 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 the Get_Arg_Count function would return 3. Get_Arg$(1) would be aaa, Get_Arg$(2) would be bbb, and Get_Arg$(3) would be ccc.

If the macro were invoked with the command Sample RED GREEN BLUE YELLOW, then the Get_Arg_Count function would return 4. Get_Arg$(1) would be RED, Get_Arg$(2) would be GREEN, Get_Arg$(3) would be BLUE, and Get_Arg$(4) would be YELLOW.

If the macro were invoked with the command Sample RED, then the Get_Arg_Count function would return 3. Get_Arg$(1) would be RED, Get_Arg$(2) would be bbb, and Get_Arg$(3) would be ccc.

All other validation of the operands is the responsibility of the macro itself.

SUB operand access

If you choose to code your macro in a more "structured" design, then you can have the command line operands provided to you as passed parameters to your mainline SUB subroutine. To do this, certain considerations which must be met.

To convert your macro to a structured format, you must place an initial SUB subroutine header immediately after the macro prototype line, as described in Macro Prototype. If you do this, and you normally use your macro from the primary command line with some fixed maximum number of parameters, SPFLite will assign these for you just like any other SUB subroutine would receive them, so that calls to Get_Arg$ will not be needed.

This can be a quite useful feature, but it requires you to follow some fairly strict rules to take advantage of this:

The initial SUB subroutine follows all the rules of thinBasic syntax, and must be ended by an END SUB statement.

The SUB keyword must appear immediately following the SPFLite macro prototype line, meaning that the initial SUB keyword must be on line 2 of the MACRO file and no where else, and no comments may appear anywhere on the SUB statement.

The initial SUB line may be continued on multiple lines if needed, by placing an _ underscore at the end of each continued line except the last one, as required by standard thinBasic line-continuation rules.

The type of each parameter to the initial SUB must be individually declared with AS STRING. No other data type will work. Note this point carefully. If you fail to do this, your macro will not work correctly.

In the body of the initial SUB subroutine, you can optionally issue the HALT statement anywhere you wish to end the macro. Otherwise, an implied HALT will be automatically issued when the subroutine issues an EXIT SUB, or passes through the normal END SUB.

The initial SUB subroutine may have any valid name you wish.

The initial SUB subroutine name need not match the name (if any) on the macro prototype header that appears on line 1 of the MACRO file, or the name of the MACRO file itself. However, for clarity and documentation purposes, it is recommended that you do make these names match. Future versions of SPFLite may or may not enforce such naming agreement.

The parameters defined on the SUB statement are provided by merging the actual command line operands with the default operands which may be provided on the Macro Prototype header. When no value exists in either location, a null string "" is passed as the parameter.

SUB subroutine statements can only define a fixed number of parameters. If you wish to access parameters that were specified on the primary command line beyond these, or need to handle a variable number of parameters, the Get_Arg$ function and other related functions are available and can still be used as documented, even though you used an initial SUB subroutine.

When you write a macro with an initial SUB subroutine, and the macro is launched as a line-command macro, only the defaults on the macro prototype header will be passed, and if the prototype has no defaults, all of the parameters passed to the SUB will be empty (null) strings.

NOTE: Unless you strictly follow the SUB formatting rules, SPFLite may not detect that you have put an initial SUB subroutine in your macro, and it will not get called.

We have to perform a clever bit of "magic" to pull this off. SPFLite has to do a "read-ahead" and "peek" at your macro, and quickly analyze it to determine if you actually have an initial SUB subroutine like this. When it finds one, it inserts a call to that SUB, passing the appropriate parameters as needed. To do that, and do it reliably, you must ensure that the format of the SUB line strictly adheres to these rules.

In the initial SUB subroutine, you are free to call other subroutines and functions as desired. These can be built-in functions, functions imported by USES statements, or additional SUB and FUNCTION routines that you write yourself.

As with Basic Operand Access, validation of the command line operands is still entirely up to the macro code to perform.

A note about macro parameter data type

It is important that you follow rule noted above to define all operands AS STRING. For example, this macro,

' sample.macro abc def

SUB sample (arg1,arg2,arg3 AS STRING)

' ... statements

END SUB

is incorrect. The reason is that, as written, the AS STRING clause does not apply to all three parameters, but only to the last one. This is simply a thinBasic syntax rule, and we have no control over it. However, you needn't worry about forgetting this rule, SPFLite will verify this has been done properly and reject the macro if it breaks the rule.

What actually happens here is that when you have parameters written like "arg1,arg2," with no type information specified, thinBasic treats these as parameters of type VARIANT. It's too complicated to discuss here, except it's just not what you want. SPFLite will only pass you parameters as strings anyway, so you have to cooperate and do it the right way.

The correct way to write it is like this:

' sample.macro abc def

SUB sample (arg1 AS STRING, arg2 AS STRING, arg3 AS STRING)

' ... statements

END SUB

If you like, you can put each parameter on a separate line, for readability and maintenance purposes, using line continuation like this:

' sample.macro abc def

SUB sample (arg1 AS STRING, _

arg2 AS STRING, _

arg3 AS STRING)

' ... statements

END SUB

Full-parse access

This support co-exists with all the Basic Access and SUB Operand Access methods for accessing macro operands. It make no changes at all to the Get_Arg$ and Get_Arg_Count functions, or to the support for SUB operand handling.

You are free to choose whatever method suits you best, and you also can combine these methods. For instance, your macro operands might have a "simple" format that does not need to be parsed, and also a more complex format. You can choose to do the full parse if you determine that the simple format is not present.

The idea is that a call to SPF_Parse is made, passing a set of parameters that describe the syntax of your macro's operands. Using these parameters, and the initially-created contents of the Get_Arg$ data array, SPF_Parse will 'sort out' and validate the macro operands according to your specifications. If all is well, it returns an RC=0, and makes all those parameters available for use. If a parsing or validation error is found, it will issue an RC=8 along with an error message which you can obtain with Get_Msg$ and display to the user.

Validation consists of the following:

Depending on the optional validation flags, verification that the number of operands entered of that type meets the specification. Using flags, you can control whether an operand count represents an exact count, or is an upper limit (where the lower limit is zero), or if it is to be taken as an optional, "all or nothing" count.

Where Line References are allowed, it can also validate that the line references entered are valid. For a line label like .ABC, the label must exist in your edit file to be "valid". For a line-number pseudo-label like .123, a data line on line 123 must exist, but since these are not actually labels, nothing else need be "defined".

Where Tag operands are allowed, it can also validate that the Tag operands entered are valid Tags. A tag is valid if at least one tag of that name appears in your edit file.

Where single keyword operands are specified, it simply tracks whether the keyword was specified or not. It is not an error if the keyword is absent.

Where mutually exclusive keywords are specified, it validates that one and only one has been entered, This is the same principle used on SPFLite command like FIND, where you cannot say FIND FIRST LAST ABC.

Where keywords have multiple aliases, it accepts them all and 'normalizes' them to return the first specified keyword. e.g. if the alias list were specified as (EXCL,EXCLUDE,EXC,X) then when any of them are entered it would be treated and returned as EXCL. This normalization process means that you don't have to check every possible spelling of a keyword, but only the first (left-most) one that appears in the list. This greatly simplifies the amount of work needed to check such keywords, since only value has to be tested.

On the completion of a successful SPF_Parse, there should normally be no need to examine or use the Get_Arg$ array. There will be no unaccounted-for operands 'left over' that would be the responsibility of the macro. (If there were unaccounted-for operands, these would be categorized as a syntax error. The fact that you don't have a syntax error means the parsing completed successfully).

However, since the initially-created "arg" array is not modified by Spf_Parse, nothing prevents access using the functions discussed above, if you have that need.

How to access the parsed-out operands

SPF_Parse sorts and categorizes the command line operands into five groups:

Keywords	For all specified Keywords, you can call a single function to return a TRUE / FALSE indication of whether a particular keyword has been entered or not. For example, to see if the Keyword ALL had been specified, the code would be IF Get_Arg_KW("ALL") then ... When keywords are part of a mutually exclusive group (like WORD, PREFIX, SUFFIX) you may call a function to return which of the keywords were specified. The code for this would be IF Get_Arg_KWGroup$("list-name") then ... This requires the creation of list-name to be used to refer to the group of keywords when specifying the keyword list. This is described in the details for SPF _Parse below. Use of the list-name and Get_Arg_KWGroup$ function does not prevent use of Get_Arg_KW for a specific keyword if you desire. (Just to be clear, all keywords are optional. It would not really make sense to say that a keyword was mandatory every time you used a macro.)
Line References	Your macro may specify that it requires any number of Line References, there is no limit. When retrieving Line References, they are returned by relative position, left to right. Their exact operand location, and whether there are intervening operands of other types is immaterial. You request the first Line Reference, the second Line Reference, etc. The code for this would be start-line = Get_Arg_LRef$(n) where 'n' specifies the required relative Line Reference number.
Tag Operands	Your macro may specify that it requires any number of Tag Operands, there is no limit. When retrieving Tag Operands, they are returned by relative position, left to right. Their exact operand location, and whether there are intervening operands of other types is immaterial. You request the first Tag Operand, the second Tag Operand, etc. The code for this would be tag-name = Get_Arg_Tag$(n) where 'n' specifies the required relativeTag Operand number.
Text Literals	Text operands are quoted strings or un-quoted strings which are not keywords nor not solely numeric. i.e. like the search and change strings of a CHANGE command. Your macro may specify that it requires any number of Text Literals, there is no limit. When retrieving Text Literals, they are returned by relative position, left to right. Their exact operand location, and whether there are intervening operands of other types is immaterial. You request the first Text Literal, the second Text literal, etc. The code for this would be srch-string = Get_Arg_TextLit$(n) where 'n' specifies the required relative Text Literal number.
Numeric Literals	Numeric operands are un-quoted strings which are solely numeric digits. i.e. like the column range operands of a FIND command. Your macro may specify that it requires any number of Numeric Literals, there is no limit. When retrieving Numeric Literals, they are returned by relative position, left to right. Their exact operand location, and whether there are intervening operands of other types is immaterial. You request the first Numeric Literal, the second Numeric literal, etc. The code for this would be start-col = Get_Arg_NumLit$(n) where 'n' specifies the required relative Numeric Literal number.

How to specify the macro command syntax

The SPF_Parse function may appear complicated at first, but don't let that hold you back from trying it. Let's have a look:

RC = SPF_Parse(TxtLit-number, NumLit-number, LinRef-number, Tag-number, _

[ keyword-set, ]

...

)

What do we have? Four numeric values, and then a series of optional keyword definitions. Let's see the details.

The first four operands specify how many of each of the non-keyword operands your macro will allow. For example, if your macro operands consists solely of two line reference operands, the coding is simply:

RC = SPF_Parse(0, 0, 2, 0)

which is pretty straight-forward.

If your macro added an optional "ALL" keyword, the coding becomes:

RC = SPF_Parse(0, 0, 2, 0, "ALL")

again, not unduly complicated.

How to specify a variable number of values

Many operands are optional. In our example above, the line references may be optional if the macro also allows you to mark the lines with a CC / CC line block. But if we code just the number 2 as the Line Reference operand with nothing else, that means the operands are mandatory, and there must be exactly 2 of them. To allow a varying number of arguments, it is handled by adding the ARG_VAR as a "flag" to the count value, so that this parameter to the SPF_Parse call is changed from 2 to 2+ARG_VAR. The ARG_VAR option will allow from 0 (zero) to the number specified to be entered.

So if the TxtLit-number operand is coded as 2+ARG_VAR it means there can be from 0 to 2 Text Literals.

The flag name ARG_VAR, like the ARG_OPT and ARG_DEF flags discussed next, are predefined by SPFLite.

How to specify optional values

Some macro parameters may be used in an optional, "all or nothing" manner. This can be handled by using the ARG_OPT validation flag. When ARG_OPT is added to a count value, it indicates that for this type of parameter the number of supplied values must either be zero or the exact count specified.

For example, if the number of line references is specified as 2+ARG_OPT it indicates that there must be either no line references or exactly two line references.

You cannot combine the ARG_OPT flag and the ARG_VAR flag, since the meanings conflict. For instance, if a count value is specified as 2+ARG_VAR+ARG_OPT, the ARG_VAR implies that having one argument is valid, but ARG_OPT implies that it isn't, and these cannot both be true. If you attempt to use the flags this way, the SPF_Parse function will fail with a nonzero RC.

How to validate tag and line references

When Tags or Line References are used as operands, you may wish these entered values to be validated to ensure they correctly point at valid data lines. This can be handled by using the ARG_DEF validation option. When this is added to a value, it indicates that for this type of parameter data line reference must be valid. For example, if the number of line references ia entered as 2 + ARG_DEF it indicates that there must be two valid line references.

How to specify keywords

There are two basic types of keywords, the simple "I'm here / I'm not here" type of keyword (like the RAW operand of CUT), and the mutually exclusive list of keywords (like ON / OFF, or WORD / PREFIX / SUFFIX)

For the simple type, the keyword-set operand is just the keyword itself, couldn't be simpler. "ALL" or "TRUNC" etc.

For the mutually exclusive type, the various keywords are just entered, separated by commas. e.g. for an ON/OFF pair, the keyword-set would be coded as "ON,OFF". For the WORD / PREFIX / SUFFIX example it would be "WORD,PREFIX,SUFFIX"

When a keyword can be specified in various alias values, the normal single keyword value in the list is replaced by the list of aliases, enclosed in parentheses. As an example, a macro might accept either DELETE or PURGE as operands. These would normally be coded as "DELETE,PURGE". But what if you wanted to accept DEL as an alternate for DELETE and PUR as an alternate for PURGE. It would then look like "(DEL,DELETE),(PUR,PURGE)"

Almost done now, just one more wrinkle for keywords. In the above examples, any of the keywords can be tested for using the Get_Arg_KW function, but what if, for the WORD/PREFIX/SUFFIX example, you wanted to ask "Which one was entered" without having to test each one individually? This is possible, but you have to assign a 'list-name' to refer to that specific set of keywords. Then you can ask for which KW in the set was entered by using the Get_Arg_KWGroup$(list-name).

So where does the list-name go? It is inserted at the beginning of the list, followed by a colon (:). Our example here, using the list-name WTYPE, would be coded as:

"WTYPE:WORD,PREFIX,SUFFIX".

Asking for 'which one was entered' would be done by

wtype = Get_Arg_KWGroup$("WTYPE")

Example: Putting SPF_Parse all together

A picture is worth a thousand words, so lets do an example. Here's a reasonably complex imaginary macro command whose syntax is similar to FIND and looks like:

MACNAME search-str

[ start-col [ end-col] ]

[ start-line [ end-line] ]

[ WORD | PREFIX | SUFFIX ]

[ RED | GREEN | BLUE | YELLOW ]

[ ALL ]

Lets code the SPF_Parse request to parse this command:

IF SPF_Parse(1, 2 + ARG_VAR, 2 + ARG_VAR + ARG_DEF, 0, _

"WTYPE:WORD,PREFIX,SUFFIX", _

"COLOR:RED,GREEN,BLUE,YELLOW", _

"ALL") then

Halt(FAIL, Get_Msg$)

END IF

The first operand 1 says there is 1 mandatory text literal (the search-str in the syntax diagram)
The second operand 2 + ARG_VAR says there may be 0 to 2 optional numeric literals (the start-col and end-col in the syntax diagram)
The third operand 2 + ARG_VAR + ARG_DEF says there are from 0 to 2 optional line references (the start-line and end-line in the syntax diagram and that if entered, the references should be validated as correct line references)
The fourth operand 0 says there are no allowable Tag operands.
The "WTYPE:WORD,PREFIX,SUFFIX" operand specifies 3 mutually exclusive keywords, which can be referenced as a group using the list-name value of WTYPE.
The "COLOR:RED,GREEN,BLUE,YELLOW" operand specifies 4 mutually exclusive keywords, which can be referenced as a group using the list-name value of COLOR.
The "ALL" operand specifies the simple keyword ALL which may be present or not present.
The entire SPF_Parse function is coded as part of an IF ... THEN statement. Since SPF_Parse returns a non-zero value (8) if any parsing errors occur, it is usually simplest to test this way and use an SPF_SetMsg to issue the error message text provided by SPF_Parse. This text is obtained using a standard Get_Msg$ function.
Assuming SPF_Parse returns with no error status, the macro can continue at this point to use the parsed values, or to perhaps perform additional validation if required by the circumstances of the macro's function.

A simple macro demo in all three command operand modes

Here is a simple macro coded in the three different modes to show the differences. The syntax for this example is:

DEMOFIND srch-string [ ALL ]

Note: All examples below should probably use SPF_Quote$ to properly process the srch-string, but this has been left out to simplify the demonstration code.

Basic Operand Access

' DEMOFIND.MACRO

DIM OpAll as STRING

IF Get_Arg_Count < 1 then Halt(FAIL, "Missing search string")

OpAll = ucase$(Get_Arg$(2))

If OpAll <> "" and OpAll <> "ALL" then Halt(FAIL, "Unknown operand: " + OpAll))

SPF_CMD("FIND " + Get_Arg$(1) + " " + OpAll)

HALT

SUB Operand Access

' DEMOFIND.MACRO

SUB DEMOFIND(srchstr as string, OpAll as STRING)

IF srchstr = "" then Halt(FAIL, "Missing search string")

If OpAll <> "" and OpAll <> "ALL" then Halt(FAIL, "Unknown operand: " + OpAll))

SPF_CMD("FIND " + srchstr + " " + OpAll)

Halt

END SUB

Full Parse Access

' DEMOFIND.MACRO

if SPF_Parse(1, 0, 0, 0, "ALL") then Halt(FAIL, Get_Msg$")

SPF_CMD("FIND " + Get_Arg_TextLit$(1) + iif$(Get_KW("ALL"), " ALL", "")

HALT

Created with the Personal Edition of HelpNDoc: Transform Your Documentation Workflow with HelpNDoc's Intuitive UI