Praise: Rev Documentation to the rescue

[Michael J. Lew]

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.
-- 
Michael J. Lew

Senior Lecturer
Department of Pharmacology
The University of Melbourne
Parkville 3010
Victoria
Australia

Phone +613 8344 8304

**
New email address: michaell at unimelb.edu.au
**