Documentation for "expecto"

Download the whole documentation as one plain text file

4. Template Syntax

4.7. Changing Report Messages

Recall the purpose of expecto: to get rid of unwanted mail messages. So, if the output of a cron job matches your template, expecto will produce no output at all.

However, what if it does not match? In this case expecto will produce a report. This chapter explains how to control this report, so the mismatch is presented to you in a useful and convenient way.

A basic and easy way to control the report is by using the -r option of expecto to specify the reporting level. Please refer to the "Command Line Options" chapter for details. The remaining things explained in this chapter don't use command line options, but they're based on special statements in the template file.

By default, if a mismatch occurs, expecto prints a small header, followed by the data that caused the mismatch. The latter is controlled by the -r option, see above. The header looks like this:

ERROR: The data starting at line 16 of the cron job output is unexpected, it does not match the template.

You can refine that message by specifying the name of the data that's being processed by expecto, using the NAME statement. For example, place the following line at the beginning of your template:

NAME "backup script's output"

That will change the mismatch header as follows:

ERROR: The data starting at line 16 of the backup script's output is unexpected, it does not match the template.

The name is also used within other messages, for example if the data is empty or too short for the template, or the opposite case, if there's more data than the template accepts:

ERROR: The backup script's output is too short. (Unexpected EOF after 23 lines. There should be more data, according to the template)

ERROR: The backup script's output is too long (more data than expected). (38 lines matched the template correctly, 5 lines remaining.)

If no NAME statement is present in the template, the default name is "cron job output". If there are multiple NAME statements, the last one overrides the preceding ones.

Please note that the NAME statement always works at a global level, no matter where it is located in the template, even if it is placed inside a branch that never matches. Therefore, in order to avoid any confusion, you should put it at the top of your template.

[Valid XHTML 1.0]