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).
You should not include any DayValue in sToken as the date of the incoming macro token will already have been shifted by the DayValue and inserting it in sToken will shift the date used to calculate the tokens in sToken a second time.
sCurMonthName = EvalToken(Today(),'[Mmmm]') // the month of today
sCurMonthName = EvalToken(Today(),'[2Mmmm]') // the month of tomorrow !!!
The above example might have been self-evident, but that error can also occur if you use the s_LangDayToken system variable.
➢Instead of using the s_LangDayToken system variable as a parameter of this function, use the s_TokenRoot system variable.
Finally, if you add a DayValue, the tokens in sToken will be calculated differently in the case of backtrack monthly templates.
For example, in a monthly template which backtracks based on the week of the 1st of the month:
// the next call is based on the date of today
sCurMonthName = EvalToken(Today(),'[Mmmm]')
// this call is based on the Monday before the 1st of the month
sCurMonthName = EvalToken(Today(),'[1Mmmm]')
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
