Praise: Rev Documentation to the rescue

[Jon]

Not from me!  I guess I chose a horribly wrong example!  Point taken!

:)

Jon


Michael J. Lew wrote:

> I dare say this one will get me into trouble...
>
> At 9:36 PM -0500 25/7/05, use-revolution-request at lists.runrev.com wrote:
>
>>
>> For me, the biggest problem I have with the docs, aside from not being
>> able to find things, is that when I get to a topic, there are not enough
>> examples to indicate exactly how a facility might be used.  Whether this
>> belongs in the "docs" or in something else is beside the point.  If I'm
>> struggling with how to use a REPEAT, I need examples.
>
>
> Here is some help with repeat that includes no less than 8 code 
> examples. You can find many, many more examples of how and when to use 
> repeat in almost any Rev project that you care to open and examine. I 
> hope that helps (HTH).
>
> I'm sorry if this post is excessively long. It is Jeanne's fault for 
> writing a long dictionary entry ;-)
>
> From the docs:
> repeat control structure
> Platform support:    Introduced in version 1.0 (Changed in version 2.0)
>
> Executes a set of statements repeatedly.
>
> repeat loopForm
>   statementList
> end repeat
>
> See also: each keyword, end repeat keyword, exit repeat control 
> structure, for keyword, forever keyword, next repeat control 
> structure, until keyword, while keyword, Why does a repeat loop behave 
> strangely?
>
> Description
> Use the repeat control structure to perform the same set of actions 
> for each member of a set: for example, for each card in a stack, or 
> each line in a variable.
>
> Form:
> The repeat control structure always begins with the word "repeat".
>
> The last line of a repeat control structure is the end repeat keyword.
>
> Parameters:
> The loopForm is one of the following forms:
>
>     * forever
>     * until condition
>     * while condition
>     * [for] number times
>     * with counter = startValue [to | down to] endValue [step increment]
>     * for each chunkType labelVariable in container
>     * for each element labelVariable in array
>
> The condition is any expression that evaluates to true or false.
>
> The number, startValue, endValue, and increment are numbers or 
> expressions that evaluate to numbers.
>
> The counter or labelVariable is a legal variable name.
>
> The chunkType is one of character (or char), word, line, item, or token.
>
> The container is any existing container. The array is any existing 
> container that contains an array of values.
>
> The statementList consists of one or more Transcript statements, and 
> can also include if, switch, try, or repeat control structures.
>
> Comments:
> How many times the statementList is executed depends on the loopForm 
> you use.
>
> The forever form:
> The forever form continues repeating the statements in the 
> statementList until an exit, exit repeat, pass, or return statement is 
> executed. Usually, one of these control structures is included in an 
> if control structure within the statementList.
>
> Use the forever form if you want to test a condition at the bottom of 
> the loop, after the statementList is executed. In the following 
> example, the go command is executed at least once, since the 
> mouseClick is not checked until after the go command:
>
>   repeat forever
>     go next card
>     if the mouseClick then exit repeat -- user clicked
>   end repeat
>
> If no loopForm is specified, the forever form is used.
>
> The until and while forms:
> The until condition and while condition forms repeat the statementList 
> as long as the condition is false or as long as it is true, 
> respectively. Revolution re-evaluates the condition before each 
> iteration.
>
> Use the until condition or while condition form if you want to test a 
> condition at the top of the loop, before the statements are executed. 
> This example scrolls through the cards until the user clicks the mouse:
>
>   repeat until the mouseClick
>     go next
>     wait for 100 milliseconds
>   end repeat
>
> The for form:
> The for number times form repeats the statementList for the specified 
> number of times.
>
> The number is evaluated when the loop is first entered, and is not 
> re-evaluated as a result of any actions performed in the 
> statementList. For example, if the number is the number of cards, and 
> the statementList contains a create card command, the loop is executed 
> as many times as there were cards when the loop began, even though the 
> current number of cards is changing with each iteration through the loop.
>
> If the number is not an integer, it is rounded to the nearest integer, 
> using the same rules as the round function.
>
> Use the for number times form if you want to execute the statementList 
> a fixed number of times. The following simple example beeps three times:
>
>   repeat for 3 times
>     beep
>   end repeat
>
> The with form:
> The with counter = startValue to endValue form and the with counter = 
> startValue down to endValue form set the counter to the startValue at 
> the beginning of the loop, and increase (or decrease, if you're using 
> the down to form) the countVariable by 1 each time through the loop. 
> When the counter is greater than or equal to the endValue, (less than 
> or equal to, if you're using the down to form), the loop performs its 
> final iteration and then ends.
>
> If you specify an increment, the increment is added to the counter 
> each time through the loop, rather than the counter being increased by 
> 1. (The increment is not treated as an absolute value: if you're using 
> the down to form, the increment must be negative.)
>
> As with the for number times form described above, the startValue and 
> endValue are evaluated when the loop is first entered, and are not 
> re-evaluated as a result of any actions performed in the statementList.
>
> Use one of these forms if you want to perform an action on each member 
> of a set, and you need to refer to the member by number within the 
> statementList. The following example loops through all the controls on 
> the current card. The counter x is 1 during the first iteration, 2 
> during the second, and so on:
>
>   repeat with x = 1 to the number of controls
>     show control x
>   end repeat
>
> The following example loops backwards through a set of lines. The 
> counter myLine is 20 during the first iteration, 18 during the second, 
> and so on:
>
>   repeat with myLine = 20 down to 1 step -2
>     put myLine
>   end repeat
>
>   Note:  It is possible to change the counter variable in a statement 
> in the loop. However, doing this is not recommended, because it makes 
> the loop logic difficult to follow:
>
>   repeat with x = 1 to 20 -- this loop actually repeats ten times
>     answer x
>     add 1 to x -- not recommended
>   end repeat
>
> The for each form:
> The for each chunkType labelVariable in container form sets the 
> labelVariable to the first chunk of the specified chunkType in the 
> container at the beginning of the loop, then sets it to the next chunk 
> for each iteration. For example, if the chunkType is word, the 
> labelVariable is set to the next word in the container for each 
> iteration of the loop.
>
> Use the for each form if you want to perform an action on each chunk 
> in a container. This form is much faster than the with countVariable = 
> startValue to endValue form when looping through the chunks of a 
> container. The following example changes a return-delimited list to a 
> comma-delimited list:
>
>   repeat for each line thisLine in myList
>     put thisLine & comma after newList
>   end repeat
>   if last char of newList is comma then delete last char of newList
>
> The for each element labelVariable in array form sets the 
> labelVariable to the first element in the array at the beginning of 
> the loop, then sets it to the next element for each iteration.
>
>   Important!  You cannot change the labelVariable in a statement 
> inside the loop. Doing so will cause a script error. You can change 
> the content of the container, but doing so will probably produce 
> unexpected results.
>
> Use the for each form if you want to perform an action on each element 
> in an array. The following example gets only the multi-word entries in 
> an array of phrases:
>
>   repeat for each element thisIndexTerm in listOfTerms
>     if the number of words in thisIndexTerm > 1
>     then put thisIndexTerm & return after multiWordTerms
>   end repeat
>
>   Note:  The repeat control structure is implemented internally as a 
> command and appears in the commandNames.
>
> Changes to Transcript:
> The ability to specify an increment for the repeat with counter = 
> startValue to endValue form was added in version 2.0. In previous 
> versions, this form of the repeat control structure always incremented 
> or decremented the counter by 1 each time through the loop.