82. Loops via Recursion
Description
How to create a loop through recursion (having a computation call itself).
Code
(Calling Computation)
// initial values
SET Pos-n TO 0
SET Count-n TO 0
// call the loop
Loop-c
// analyze the result
IF Count-n = 1
"There is one occurance of the letter A."
ELSE
"There are «Count-n:nine» occurances of the letter A."
END IF
(Looping Computation Loop-c)
""
// limit the loops to the length of the string
IF Pos-n < LENGTH( TextVar )
// look at the next letter in the string
SET Pos-n TO Pos-n + 1
// if it's an 'a', add it to the count
IF MID( TextVar, Pos-n, 1 ) = "a"
SET Count-n TO Count-n + 1
END IF
// call the loop again
Loop-c
END IF
Explanation
Recursion loops require two computation variables. The first is the calling variable. It sets up the initial parameters for the loop, calls the loop, then inserts the results from the loop into the document. The second is the loop computation. When the loop computation is called, it will continue calling itself until it is finished, at which point its results are returned to the calling computation.
The above example demonstrates this. Its purpose is to count how many times the letter "a" occurs in a string. To do this, we require two temporary variables: Pos-n, a number variable which tells us the position in the string we need to analyze, or in other words the character number, and Count-n, a number variable that keeps track of how many occurances of "a" we've found. (Both of these variables should have their "Advanced" options set to "Ask only in dialog," "Don't warn if unanswered," and "Don't save in answer file").
The calling variable first SETs Pos-n and Count-n to zero values -- our starting point. It then calls the looping computation, Loop-c, which will go through the string letter by letter, counting the number of times it finds "a."
Specifically, Loop-c first makes sure that Pos-n is less than the length of the string. This safeguard will hopefully keep the loop from going on endlessly and will force an abort when the end of the string is met. Then the loop computation increments Pos-n so that it can examine the next character in the string. It looks at the character at Pos-n position to see if it is an "a." If so, it notches up Count-n by one. The loop then calls itself again. It will continue to do this until Pos-n is the same value as the length of the string, or in other words, until every character of the string has been examined. It then ends, effectively returning control to the calling variable.
At this point, Count-n will contain the number of times the letter "a" was found. We can examine this value and insert it into our document.
WARNING: Using recursion can be dangerous, as it is easy to inadvertently program in an endless loop which will cause HotDocs to crash or hang, so be careful! Moreover, there is a fairly low limit on how many times the loop can cycle. You'll know when you reach the limit: HotDocs will crash. On a Windows 2000 machine running HotDocs 5.1 Pro, the above computation was able to analyze a string 129 characters long. At 130 characters, HotDocs crashed. Results will vary by machine, computation, and the version of HotDocs you are running.
See also, Computation 15: Loops via REPEAT.