Documentation for "expecto"

Download the whole documentation as one plain text file

4. Template Syntax

4.5. Grouping of Lines

Let's have a look at a cron job that expires old archives from a file system: As long as the free space on that file system is below a certain threshold, the oldest archive is deleted. The output might look like this:

Starting expiry script on 2012-10-31 05:00:10. Free space is 7%. Removing archive webdata-378 ... Done. Free space is 12%. Removing archive webdata-379 ... Done. Free space is 16%. Removing archive webdata-380 ... Done. Expiry finished, free space is 21%.

As you can see, there is a group of three lines that is repeated for every removal. The number of repetitions is variable, it may be even zero if the free space is high enough right from the start. In the above example, the group is repeated three times.

In order to facilitate matching such groups of lines, expecto enables you to group template lines with parentheses. This is how it is done:

"Starting expiry script on"{b} * ( "Free space is"{b} "Removing archive"{b} "Done." ) "Expiry finished, free space is"{b}

As you can see, the parentheses must be placed on separate lines. Do not put a match expression (string or regular expression) on the same line as parentheses used for grouping. The parentheses must be the only characters on their lines, with the exception of white space (indentation), and the opening parenthesis may be preceded by a repetition mark.

In this case, the opening parenthesis is preceded by an asterisk ("*"). As you have learned in an earlier chapter, the asterisk is a repetition mark that means that a line can be repeated multiple times in the input (but it might also occur only once or not at all). We now extend that concept to groups of lines: The whole group of three lines can be repeated multiple times in the input.

If you know that the group should occur at least once in the input, you should use "+" as the repetition mark instead of "*". Similarly, you can use "?" if a group of lines may occur at most once (or possibly not at all).

It is very important to understand that a group must always match as a whole. In the above case, if the first and second line of the group would match, but the third one doesn't, then the whole group fails to match, and the repetition stops.

Group matching is performed recursively, that means you can nest groups inside each other.

[Valid XHTML 1.0]