There are times when tagging that you may wish to insert sequential decimal integers or Roman numerals into fields or other data. The \1 escape sequence reads named variable Integer to Insert for configuration information. The format is:
next{,pad{,increment}}
next can be any integer value and is the next integer to be inserted.
pad is optional and defaults to 0. A pad of -1, 2, 3 or 4 can be specified. Any other value implies no padding. 2, 3 and 4 are treated as the desired length of the number achieved by adding leading zeros. -1 specifies that the inserted number is to be a Roman Numeral. If the number to be inserted cannot be represented as a Roman Numeral, nothing is inserted.
increment is optional and defaults to 1. It is the value to be added to next after the number is inserted.
After the next integer is inserted it is incremented by the increment value and is written back to the Integer to Insert named variable.
If the Integer to Insert named variable is empty, 1,0,1 is assumed. ie. a next integer of 1. No padding and an increment value of 1.
When a \1 sequence is used with an Append, Prepend or Replace statement with as list enabled, it will cause the appropriate modification text to be recalculated for each list item being manipulated.
Regular expression replacement templates can specify a \1 sequence with the Regular Expression, Replace statements and the Multi Field Editor's Replace function.
Note that more than one \1 sequence in a field may not have the desired results. Additionally when using \1 sequences with statements which can process more than one field it is not a good idea to specify more than one field, as again the results may not be as you would expect. Every encountered \1 sequence works in isolation.
If you are operating stepwise and you want to insert into a field or track variable using Yate's parallel execution, you can redirect the Integer to Insert information to a track variable. The contents of Integer to Insert can be specified as:
=#
Where # is an integer in the range of 0 through 15. The specified track variable contains the per file next{,pad{,increment}} encoded information. The track variable can be initially empty implying 1,0,1. After each \1 insertion the appropriate track variable is modified as opposed to the Integer to Insert named variable.
The following example sets chapter names in all files starting with Chapter 1 until Chapter n where n is the total number of chapters in all selected files.
As an example assume that you have files where you want each line in a comment to be preceded by a number:
1: Set named variable 'Integer To Insert' to "=15" 2: Clear Variable 15 3: Test if the Comments field is not empty (Set test state and Variable 0) 4: if Variable 0 is true 5: Prepend "\1.·" to the Comments field, as list with delimiter "\n" 6: endif
Statement 1 redirects the Integer to Insert processing to track variable 15.
Statement 2 clears track variable 15 which implies 1,0,1.
Statement 3 sets variable 0 to true for every comment field which is not empty.
Statement 4 ensures that the statements in the if-endif construct are only executed if variable 0 is true (ie. The Comments field was not empty).
Statement 5 inserts a number followed by a period then a space at the start of every line in the comment.
As the Integer to Insert processing was redirected to a track variable, the inserted numbers will restart from 1 for each file. The following statements would insert numbers which do not restart for each file:
Clear named variable 'Integer To Insert'
Test if the Comments field is not empty (Set test state and Variable 0)
if Variable 0 is true
Prepend "\1.·" to the Comments field, as list with delimiter "\n"
endif