The GSAK macro language supports variable substitution (for expediency it will now be referred to as VS for the remainder of this topic), and by default this support is turned on.You can toggle support for VS with the VSUB command. If you are familiar with languages like PHP then this will be second nature to you. However, if you are a novice programmer it can be confusing, so I would suggest you turn it off by starting all your macros with VSUB Status=off
When the macro language was first written I allowed VS for quick and easy expressions and the ability to easily use special tags. In retrospect I probably should have turned off VS by default and then make the user set it on when needed. VS can complicate the macro language and provides opportunities for generation of errors that are not obvious. However, to now disable support for variable substitution would cause too many problems with existing users that have already written macros that take advantage of this feature.
The purpose of this topic is to help you understand how VS is implemented in GSAK and make you aware of the possible associated problems. Note that VS is only performed inside string literals (anything between double quotes) with the exception being special tags. Special tags (any valid tag beginning with %) are always substituted when VS is turned on.
The good
By allowing VS, it makes for type casting on the fly, easy concatenation of strings, the ability to use special tags. For example with variable substitution support you typecast number to string by:
$aNumber = 45
$aString = "$aNumber"
$aString now = "45"
And you can easily assign the values of special tags to variables via:
$data = "%code %smart"
$data is now a string variable, that contains the waypoint code followed by a space followed by the waypoint smart name
Concatenation of variables
$a = "one"
$b = "two"
$c = "three"
$numbers = "$a $b $c"
Now $numbers = "one two three"
The bad
Now this approach can have drawbacks that are not obvious until you delve into programming with macros. There are times when you may want to allocate these literal values to a variable or write them out to a file. With VS turned on it is not possible to set a variable with the literal value of "%smart" (or any special tag or variable for that matter) because the current VS code will always replace it with the value of the corresponding special tag. Unfortunately the expression engine that GSAK uses does not support escaping of characters, so you must set off VS if you want this ability.
Having VS turned on can cause serious problems in some cases. For example if you wanted to generate a variable that had the following literal url (perhaps not a valid url, but I am hoping you will get the point)
$url = "http://somesite.com/%lon=32"
Because %lon corresponds to one of the GSAK special tags (and this applies to any % combination that matches a special tag you are going to wind up with the contents of the URL having something like:
"http://somesite.com/83.4567=32"
There is also the subtle problem of using a variable name in a literal. For example:
$AUS = 1000
$msg = "37 $US is equal to about 45 $AUS"
You would expect that message to show exactly the text above. However, because of VS we now have a $AUS variable that just happens to match, so the resulting message would be:
"37 $US is equal to about 45 1000"
Which is not what you wanted.
Summary
By turning off VS you get exactly what is contained in the literal, so for example with VS off:
$test = "test data"
$data = "$test %smart %code"
Now $data contains ""$test %smart %code"
Is really up to the user to decide which mode to use when programming macros - what ever works best for you. If you are a novice, you may run into less errors by turning VS off.
You may then ask - If I turn off VS how do I do the things you mention in the good part of using VS. I will provide examples of the code your would use to get the same result when having VS turned off.
1. Type casting a numeric to a string with VS turned off - Use the function NumToStr:
$aNumber = 45
$aString = NumToStr($aNumber)
2. Concatenating string variables:
$a = "one"
$b = "two"
$c = "three"
$numbers = $a + " " + $b + " " + $c
The + " " here is purely to provide a space between each string of numbers.
3. To get the value of special tags when variable substitution is off, use the Eval function:
Vsub status=off
$result = eval("%code %smart")
Vsub status=on
Warning: VS has been optimized for speed, which means that not *every* possible variable name is interrogated for substitution. When GSAK does variable substitution, it interrogates the string looking for Variables using the regular expression \$.+?\b (For more information on this subtlety see this link)