REPEAT commands are used to create (for each object found in the source) sections in your document. For example, you could use a REPEAT command to generate a section for each file in a directory. REPEAT commands can also be defined to be recursive so that with only one recursive REPEAT command you can drill down through an artifact structure and extract all of the information you need.
Each REPEAT command is based on the context of one of the OPEN, REPEAT, or LIMIT commands defined above it in the command hierarchy. At least one OPEN command must be specified in a document before a REPEAT command can be created.
To add a REPEAT command:
1. Place the insertion point where you want to insert the command. If a section placeholder already exists, you can select the section.
Note: If you work in the document, show the existing SoDA commands so you can be sure the cursor position is correct.
2. Choose Add Command from the SoDA menu.
3. Select the REPEAT Command.
4. In the REPEAT Command dialog box, select the relationships to be used, modify any options, and click OK.
To modify an existing REPEAT command, refer to: Modifying Existing Commands
Note: To read about the annotation differences between the Word versions, see Word 2000 and Word 2002 Comparison.
You can use a REPEAT command to produce one table row for each object you specify. Follow these steps:
1. Choose Insert Table from the Table menu. Select the number of columns you need and the format you want. If your table will have a heading row then create a 2-row table; otherwise create a 1-row table.
2. Make any required format changes to the borders and shading. It is important to determine this information before document generation – once you generate the document you cannot change the table style.
3. Enter the headings in the heading row, if used.
4. Select the second row of the table (or the only row of a 1-row table). Be sure to select only the row and not any additional text beyond the table.
5. Choose Add Command from the SoDA menu, and follow the steps for inserting a standard REPEAT command.
6. Add DISPLAY commands in the table cells as needed.
You can also nest a REPEAT command within a single table cell. To do so, follow the steps for inserting a standard REPEAT command.
The And Where expression specifies criteria which must be met by items in the set of objects returned by a REPEAT command. If the criteria are not met by a particular object, that object will not become part of the set.
Expressions consist of operands and operators. Operands are the attributes or literals on either side of an operator. The operands that are available at a given time in the REPEAT command dialog box depend upon the information source domain specified in the current context. Operators specify the test that will be applied to the operands to determine their relationship, for example, the test of equality or the test of inequality.
Here are the operators available for And Where expressions (note: all of the following operators are case sensitive):
= exactly equal to
!= not equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to
LIKE matches the regular expression
NOT LIKE does not match the regular expression
IS the class of the object matches
Note that when a DISPLAY value returns a Boolean value, "True" or "False", you must enter these values exactly.
Note: Operands that are literals always evaluate to a string value. Therefore, numeric values are not considered to be numbers, but rather strings. What is the effect?: If you are filtering based on a numeric value, you may get results that you don’t expect. For example: if you are filtering for an operand greater than "42", you may get 43 through 99, but you won’t get 100 or beyond. This is because the "1" in "100" is considered to be less than the "4" in "42". Again, operands are evaluated based on string representations, not numeric representations.
You are creating a document that will extract objects from the File System domain. You would like SoDA to create a document section for each directory in your project directory that starts with "ROSE".
After creating an OPEN command called project_directory, create a REPEAT command that will result in a section for each directory in project_directory, and specify an And Where expression which limits the set of directories to those that start with "ROSE".
Select Relationship project_directory -> Contents
Where Is A Directory
And Where SimpleName LIKE ^ROSE
When you use the LIKE operator in an And Where expression, you can use any of the following metacharacters:
. The dot metacharacter matches a single instance of any single character.
For example: "bat." is a pattern that matches any four character string that begins with "bat". It would retrieve "bata", ‘batb", but not "batab" (because it is longer than four characters, the length of "bat.").
As another example: "basebal." would match any eight character string that begins with "basebal".
"basebal.xyz" would match any character string that begins with "basebal", then has any single character, then ends with "xyz".
The dot metacharacter can also return a space: so "basebal.xyz" can also return "basebal xyz (where a space is between the "l" and the "x".
* The star metacharacter matches zero or more of the preceding character in the expression. An expression followed by an asterisk "*" can be repeated any number of times (including zero, (i.e., 0-n times)).
For example: "ba*" matches all of "b", "ba", "baaa", "be", "beee", etc., but not "aaaa" because it doesn’t start with a "b"
The star metacharacter can also return spaces: so "b *" (a space between the "b" and the * metacharacter) can return "b ", and "b ".
^ The NOT metacharacter matches patterns by using the characters to the left of the ^ metacharacter and excluding those to the right of the ^ metacharacter.
For example: "bat^abc" is a pattern that matches any string (regardless of size) that begins with "bat" (the characters to the left of the ^ metacharacter) and isn’t followed by abc (the characters to the right of the ^ metacharacter).
Using the pattern "bat^abc", "batabc" would not be returned while "batabc123" would be returned. The first would not be returned because it ends with "abc" (the pattern to the right of the ^ metacharacter, while the second would be returned because begins with "bat" (the characters defined to the left of the ^ metacharacter) and it ends with "abc123" which is NOT the pattern to the right of the ^ metacharacter.
"^bat" means match anything except "bat", while "^xyz" means match anything except "xyz".
The ^ metacharacter can block out spaces as well: so "^this is a test" will return "thisisatest", but will not return "this is a test".
$ The dollar metacharacter matches expressions only at the end of the string.
For example: "bag$" will return "airbag", but not "baguette".
\ The backslash metacharacter is used as an ESCAPE code so that SoDA metacharacters (those listed here) can be used as literals.
For example, "\\" means that you want a literal backslash, while \$ means that you want a literal dollar-sign.
As a further example, if you are specifying a path that includes backslashes ("\"), you must use double backslashes as follows: Path LIKE ‘C:\xyz’ returns nothing, while Path LIKE ‘C:\\xyz’ returns all targets items in the directory C:\xyz
The backslash metacharacter MUST also be used when using plus-signs (+). For example, when looking for a particular style in a Word document, you may need to use the plus-sign (+) to identify style definitions. While the following would be incorrect: "ading 3 + Font: 10 pt, Indent: Hanging", the following would be correct: "ading 3 \+ Font: 10 pt, Indent: Hanging"
[ ] The bracket metacharacters match any one of the enclosed characters. Characters between the brackets are to be matched.
For example: "bat[123]xyz" would match "bat1xyz", and "bat2xyz", and "bat3xyz", but NOT "bat123xyz" (because the bracket metacharacter applies to single character matches only).
To match "bat123xyz" and "bat321xyz" and "bat312xyz" would require the following pattern to be used: "bat[123][123][123]xyz".
A dash may be used with the bracket metacharacter. For example: "Name LIKE bat[a d] would return "bata", "batb", "batc", and "batd".
An interesting pattern for the bracket metacharacter is the inclusion of the * metacharacter. For example, "bat[xyz*] means that "batx" is returned, "baty" is returned, "batz" is returned, and "batzzzzzz" is returned, but NOT "batzzzz" or "batyyyy".
Another interesting pattern for the bracket metacharacter is the inclusion of the NOT metacharacter (^). For example, you can use the pattern "bat[^123]xyz" to obtain any string that begins with "bat", then has a single character that is not "1" or "2" or "3", and ends with "xyz". Such a pattern would return "batHxyz", but would not return "bat1xyz".
The backslash metacharacter (\) can be used with the backslash metacharacter. For example: "bat[\\abc]xyz" returns any character string that begins with "bat", then has a single backslash (remember, the double backslash means that you are ESCAPing a single backslash), or an "a", or a "b", or a "c", finally ending with "xyz".
The bracket metacharacter pair can also contain spaces, meaning that a returned string can have an embedded space.
Final Exam on Metacharacters:
What values might the following metacharacter combination return: "base*..[\\x][^7X]*$ball" ?
Answer:
Well, let’s look at it. First of all, note that there are a number of metacharacters being used: "*", ".", "[ ]", "\", and "$". Any returned string will begin with "bas", the characters to the left of the first metacharacter (not including the character to the "immediate" left of the first metacharacter). Then the first * metacharacter will return any number of "e"s (zero to infinity, well not quite infinite, more like a very large number of them). So up to this point, the following would qualify: "bas", "base", and "baseeeeeeee". Next we have a pair of dot metacharacters. These characters return any single character, and being that there are two of this type of metacharacter, we get two single characters of any kind. So now we can get "base56", "baseeeeHX", or even "bas \" (note: the backslash is a returned value and has nothing to do with the "\" metacharacter) (also note the space between the "s" and the "\", as dot metacharacters can return spaces).
Continuing, we come upon the first pair of bracket metacharacters "[\\x]". This pair returns a match if a backslash or the letter "x" exist at this position. So now we can get "base56\", "baseeeeeeeeeZHx", or even "baseee \\" (Here the double backslash is not to be confused with the ESCAPE metacharacter. The first of the pair comes form the second dot metacharacter (as discussed above, and the second backslash comes from the ESCAPEd pair defined by the bracket metacharacter.
Following the first bracket metacharacter combination is a second pair of bracket metacharacters: "[^X]". This pair states anything can be included at this point in the string except an uppercase X. Now our string can consist of such things as: "baseeee56xY", or even "baseeeeee23xH, but NOT "baseee56x7".
Are you catching on? Next we find another * metacharacter. What is interesting about this particular instance of the * metacharacter is that it is acting against a bracket metacharacter that contains a ^ metacharacter. So what does it mean? It means that we are multiplying (repeating, if you will), the ^ metacharacter. So, you can get such things as "baseee56xY", or even "baseeee56xYYYYYY", but not "baseee56x7", or "baseeeee56x77777" (as the * metacharacter is acting on the "[^7]" combination.
Next we come to the final metacharacter combination: "$ball". This one means that any string that complies with the discussion above can be used, AND those strings can end with anything except the string "ball". Thus "baseeeee56xyballlll" would be returned by SoDA, but "baseeeee56xyball" would not.
Ordering specifies one or more attributes by which the objects resulting from the REPEAT command will be sorted. Sorting can take place alphanumerically or numerically, in forward or reverse order, and case can be ignored. (Note that numeric sorts are for pure numbers only. If the number contains punctuation (for example, a comma or a period (decimal point)) then the number is considered a string and the results will reflect the sort as a string.)
In the bottom right corner of the REPEAT Command dialog box is a button titled "Add". Clicking this button enables you to define a REPEAT command that recurses down through a defined structure and extracts the selected artifacts by using only one REPEAT command. Note that the "And Where" and "Sort By" features discussed above do not need to be the same for the recursed sections as they are for the main sections. When defining a recursive REPEAT command you are provided a second instance of the dialog box with the title: "REPEAT Command: Recursion".
Recursive REPEAT commands can be limited to recurse through a defined number of levels. The number of levels is defined SoDA> Options. On the Generation tab is a field titled: Maximum recursion level, the default value is 20. If the field is left blank then the recursive REPEAT will recurse as many items as it can, else, it restricts recursion to the number of levels defined.
The Prompt (for Filter) field enables SoDA users to perform real-time filtering, during the SoDA generation process, for REPEAT and LIMIT commands.
This flexibility means that you can generate a template multiple times, each with a different set of filtering criteria, without having to explicitly open the REPEAT / LIMIT commands involved.
To define a Prompt for Filter, click the Advanced checkbox and then click the Prompt column (the right-most column). When Prompt for Filter is enabled, the field is populated with an asterisk ("*"), and the Right Operand field is disabled.
Each REPEAT command and each LIMIT command can get its own individual set of filter prompts.
When a template that contains prompt commands is generated, a dialog box displays requesting information for the Right Operand. A prompt will be displayed for each command defined for to prompt.