str = EvalToken(nDate,sToken)
This macro function returns the value that a token sToken (or a string expression containing one or more tokens) will have on the date nDate.
➢The evaluation of tokens in sToken is performed assuming the same DayValue and LanguageTag as those of the incoming macro token.
➢If there are no braces in sToken, then braces will automatically be added to the front and back of sToken, before evaluating it.
So, for example, the 2 calls below would be the same.
sCurMonthName = EvalToken(Today(),'[Mmmm]')
// if not present, wrapping braces will be added automatically
sCurMonthName = EvalToken(Today(),'Mmmm')
You are not limited to the evaluation of a single token.
sCurMonthName = EvalToken(Today(),'The date is [Mmmm] [d]')
If the evaluation of the tokens contained in sToken generated other tokens, then they will be evaluated automatically by the function EvalToken, until there are no tokens left (ie. the result of this function is guaranteed to contain no tokens).
Examples
You need the token to be evaluated with a different DayValue or LanguageTag than those of the incoming macro token. In that case the tokens in sToken can be modified, using s_TokenRoot, to have the desired DayValue and/or LanguageTag, as shown below.
sRESULT = '[' + sNewLanguageTag + IntToStr(nNewDayValue) + s_TokenRoot + ']'
You need to "see" the result of the token evaluation within the macro code to then branch or loop in the code accordingly (though in this case you might wish to use the function PeekTokenValue instead). In the example below, we mimic the [ifHOL:ae:&c] holiday response token.
// mimic the [ifHOL:ae:&c] holiday response token
sHolsA = EvalToken(n_TokenDate, '[fa]')
sHolsE = EvalToken(n_TokenDate, '[fe]')
if (sHolsA <> '') and (sHolsE <> '')
sResult = '&c'
else
sResult = ''
endif
Precautions to use when using this function
Calling the function EvalToken will generate all the same side-effects as if the token(s) it evaluates were part of a template.
For example, if the token being evaluated is a Moon phase token, then code will be generated to change the result of the macro to the appropriate Moon phase symbol, and this includes the insertion of markers such as "**MOON**" and "**PHASE**". These markers are cleaned-up during diary generation, when the token processing runs its course. But when using EvalToken, this is not the case, and this can lead to the spurious issuing of message 108509.
Therefore, if you are just calling this function to see what the result would be, but not using that result, then you should use the function PeekTokenValue instead, which discards any side-effects encountered during the evaluation of tokens. The preceding code example would therefore be:
// mimic the [ifHOL:ae:&c] holiday response token
sHolsA = PeekTokenValue(n_TokenDate, '[fa]')
sHolsE = PeekTokenValue(n_TokenDate, '[fe]')
if (sHolsA <> '') and (sHolsE <> '')
sResult = '&c'
else
sResult = ''
endif
See also: PeekTokenValue.
Topic 105097, last updated on 18-Apr-2020
