Documentation for "expecto"

Download the whole documentation as one plain text file


4. Template Syntax

4.1. First Steps: Strings, Comments, Repetition

Basically, a template file contains a description of what the expected output from your cron job should look like.

In the most simple case, the output from your cron job is always exactly the same. In this case, you can simply take the output, add quotation marks, and use that as the template. For example, if your cron job always produces the following output:

Checking for foo: hap hep hip hop hup Successfully finished.

Then you can simply take that output and put quotation marks around the lines, so your template file looks like this:

"Checking for foo:" "hap hep hip hop hup" "Successfully finished."

This template will match the above cronjob output. There are two things that you need to be aware of:

Comments

By the way, you can insert empty lines in your template file. These are simply ignored by expecto. They do not match empty lines in the input -- to do that, you have to specify an empty string, i.e. a pair of quote characters with nothing between. Lines that contain only spaces are treated as empty, too.

You can also indent lines, i.e. put spaces or tab characters at the beginning of lines (not inside the quotes!). Any white space outside of strings and regular expressions is ignored by expecto. So you can use white space and empty lines to visually structure your template file without having an impact on the behaviour.

The template syntax also enables you to insert comments. These are ignored by expecto, too. A comment begins with a hash character ("#") and extends to the end of the line. Hash characters inside quoted strings and inside regular expressions don't have any special meaning and do not introduce a comment.

The following template contains some comments and an empty line, and one line is indented. It behaves exactly the same as the template above:

# # This is my first expecto template. # "Checking for foo:" # Another comment. "hap hep hip hop hup" "Successfully finished."

Repetition Marks

Often there are empty lines at the beginning and/or at the end of the output of a cron job. Sometimes it is not clear how many there are because you can't see them. But this is not a problem: You can put an asterisk ("*") at the start of a template line, which means that this line may occur any times (including zero, i.e. not at all). This is called a repetition mark. So, to swallow an arbitrary number of empty lines at the beginning and at the end of the input, our template should look like this:

* "" "Checking for foo:" "hap hep hip hop hup" "Successfully finished." * ""

There are more types of repetition marks: If you use a plus sign ("+") instead of an asterisk, it means that this line must occur at least once. In other words, "*" means zero or more, and "+" means one or more. Finally, a question mark ("?") means zero or one, i.e. the line may occur not at all or once, but not multiple times.

As you can see, these special characters ("*", "+" and "?") resemble characters in regular expressions. This is intentional, so they are easier to memorize. However, they don't work exactly the same as in regular expressions. In particular, there is no back-tracking, i.e. they always swallow as many lines as possible. For example, if a template line with a "*" mark has has matched as many input lines as possible, and the following template line fails to match, no backtracking of the preceding "*" line is attempted.

You can only use at most one repetition mark per line, and it must be the first character in the line, but it may be preceded by white space (i.e. spaces and tab characters).

The following table summarizes the various kinds of repetition marks:

Mark Number of lines to match
none 1
? 0 or 1
* 0 or 1 or 2 or 3 or ...
+ 1 or 2 or 3 or 4 or ...


[Valid XHTML 1.0]