Accessing Command Line Operands

Contents of Article


Introduction

Basic operand access

SUB operand access

A note about macro parameter data type

Full-parse access

How to access the parsed out operands

How to specify the macro command syntax

How to specify a variable number of values

How to specify optional values

How to validate tag and line references

How to specify keywords

Example: Putting SPF_Parse all together

A Simple Macro Demo in All Three Command Operand modes

Compatibility note for SPF_Parse



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.


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


  • 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.


  • 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 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:












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:








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, ]

              [ 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


                                     

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


Compatibility note for SPF_Parse


Starting withe SPFLite version 8.5, the four operand count fields used by the SPF_Parse function will accept the predefined flag values ARG_OPT, ARG_VAR and ARG_DEF added to a base count value.  Macros written for SPFLite prior to version 8.5, which used a different interface, will continue to operate, but your macros cannot use these named flag values if you run an older version of SPFLite.  Going forward, all new macros should use the flag values described above.



Created with the Personal Edition of HelpNDoc: Create HTML Help, DOC, PDF and print manuals from 1 single source