Templates

Syntax

CaptanHook templates are free-form text files with embedded “macros” which follow the syntax shown below:

@[this.]Property[.Property][(argument)]@

There are two kinds of macros – property references (by convention prefixed with this. although it’s just a convention, not a requirement) and synthetic. Read the sections below for more details.

Currently macros accept only one argument which can contain other macros, with no nesting limit.

Data model

Each template is associated with a data model – an instance of a C# class defined in the CaptainHook assembly. Macros have access to the instance properties of that data model and a built-in support for templating data collections. If a data model property is a generic collection, the macro processor determines element type of the collection and looks for a template named lowercasetypename.txt in the same directory where the other templates live. If such a template exists, macro processor applies it to each element of the collection.

Template names

There is only one predetermined template name – mail.txt which is the main entry point for generating all the emails. Macro processor associates the Push type instance corresponding to the current commit as the data model for the template. Other possible template names are looked up for collections in the way described above.

Before using the plain template name, the macro processor looks for a template prefixed with the current commit source ID, e.g.:

deff30c5-fe0e-4301-9479-f95c49db1817.mail.txt

Macros

Property Reference Macros

Each time the macro processor reads a macro definition it first checks whether the verbatim macro name (including dots, but excluding parameters) corresponds to a synthetic macro and, if not, it treats the macro as a property reference to a property of a current data model associated with the template being processed. Only instance and public properties can be accessed this way. By convention, such references are prefixed with this. to easily distinguish them from synthetic macros.

CaptainHook defines with two sample templates – mail.txt and commit.txt. The former is passed an instance of the Push type while the latter is used to generate text from a collection of the Commit type instances (the Push.Commits property of type List <Commit>.

If you look at the Commit type, you will notice that it contains several more collections, for instance the Modified property which is a List <string> containing names of files modified in the current push. By default, there is no template for this property (and the macro processor simply converts each element to string) but if for some reason you wanted to template each string of the collection, you could create a string.txt template file and it would be used with each string in the collection.

Each property macro can refer to inner properties of whatever data type instance is returned by the data model property. For instance, in the commit.txt you could write:

this.ID.Length

and the length of the ID would be output to generated email.

Synthetic Macros

This kind of macros exists to provide pieces of information not available directly from the associated data model or to modify the way the email is generated (e.g. by adding a header or setting the subject). Some of those macros are available in all templates and some only for the specific data models.

Currently Defined Synthetic Macros

Syntax	Arguments	Defined in Model	Description
Header(HeaderName=HeaderValue)	name and value of the header	all	Adds an email header to the generated message. The left hand side of the first = sign is the header name, the right hand side of it constitutes the value of the header
Version	none	all	contains CaptainHook’s version string
Subject(subject)	Subject header value	Push	Sets the Subject header of the generated mail
FirstCommit(len)	length of the returned string	Push	References the first commit in the Push.Commits list and allows you to access its properties. If a parameter is present, its value (an integer) is used to truncate the property result to that length
FirstCommit.MessageSummary	length of the returned string	Push	Contains the first line of the commit log message truncated to the specified length, if specified (defaults to 72)
ChangedPaths(caption)	caption of the list	Commit	List of changed paths prefixed with caption, if defined (defaults to “Changed paths:”)
AddedPaths(caption)	caption of the list	Commit	List of added paths prefixed with caption, if defined (defaults to “Added paths:”)
RemovedPaths(caption)	caption of the list	Commit	List of removed paths prefixed with caption, if defined (defaults to “Removed paths:”)
FullDiff	none	Commit	A diff with the changes introduced to the repository by the current commit
AffectedDirectories(HeaderName)	Name of the header to add	Push	Adds a header named HeaderName to the generated mail with a value being a comma-separated of all the unique directories modifed by the push
NumberOfCommits(min,text)	min – number of commits, text – text to generate	Push	When there are at least min commits, the text after comma is processed (including macros embedded in it) and output to the resulting mail. Otherwise, no text is output.
IfDifferent(lead,left,right)	lead – text preceeding the output, left – left-hand side of comparison, right – right-hand side of comparison	all	If left and right are different, output left preceeded by lead