templates: add more fields and functions

Add functions and fields in preparation for more than only message
templates. The idea is to reuse the same symbols for the message list
format and other parts of the UI.

Update the man page accordingly.

Signed-off-by: Robin Jarry <robin@jarry.cc>
Acked-by: Tim Culverhouse <tim@timculverhouse.com>

2 files changed, 141 insertions, 15 deletions

diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd
index d48e38ad..dcaa3dd4 100644
--- a/doc/aerc-config.5.scd
+++ b/doc/aerc-config.5.scd
@@ -805,9 +805,10 @@ They are configured in the *[triggers]* section of _aerc.conf_.
 
 # TEMPLATES
 
-Templates are used to populate the body of an email. The *:compose*, *:reply*
-and *:forward* commands can be called with the *-T* flag with the name of the
-template name.
+Template files are used to populate the body of an email. The *:compose*,
+*:reply* and *:forward* commands can be called with the *-T* flag with the name
+of the template name. The available symbols and functions are described in
+*aerc-templates*(7).
 
 aerc ships with some default templates installed in the share directory (usually
 _/usr/share/aerc/templates_).
diff --git a/doc/aerc-templates.7.scd b/doc/aerc-templates.7.scd
index 6c9e3190..67d5c112 100644
--- a/doc/aerc-templates.7.scd
+++ b/doc/aerc-templates.7.scd
@@ -8,6 +8,8 @@ aerc-templates - template file specification for *aerc*(1)
 
 aerc uses the go text/template package for the template parsing.
 Refer to the go text/template documentation for the general syntax.
+The template syntax described below can be used for message template files and
+for dynamic formatting of some UI widgets.
 
 Template files are composed of headers, followed by a newline, followed by the
 body text.
@@ -39,11 +41,14 @@ available always.
 	An array of mail.Address. That can be used to add sender or recipient
 	names to the template.
 
-	- _From_: List of senders.
-	- _To_: List of To recipients. Not always Available.
-	- _Cc_: List of Cc recipients. Not always Available.
-	- _Bcc_: List of Cc recipients. Not always Available.
-	- _OriginalFrom_: List of senders of the original message.
+	- _{{.From}}_: List of senders.
+	- _{{.Peer}}_: List of senders or To recipients if the message is from
+	  you.
+	- _{{.To}}_: List of To recipients. Not always Available.
+	- _{{.ReplyTo}}_: List of ReplyTo recipients. Not always Available.
+	- _{{.Cc}}_: List of Cc recipients. Not always Available.
+	- _{{.Bcc}}_: List of Cc recipients. Not always Available.
+	- _{{.OriginalFrom}}_: List of senders of the original message.
 	  Available for quoted reply and forward.
 
 	Example:
@@ -51,6 +56,7 @@ available always.
 	Get the name of the first sender.
 	```
 	{{(index .From 0).Name}}
+	{{index (.From | names) 0}}
 	```
 
 	Get the email address of the first sender.
@@ -62,22 +68,63 @@ available always.
 	The date and time information is always available and can be easily
 	formatted.
 
-	- _Date_: Date and time information when the compose window is opened.
-	- _OriginalDate_: Date and time when the original message of received.
+	- _{{.Date}}_: Date and time information when the compose window is opened.
+	- _{{.OriginalDate}}_: Date and time when the original message of received.
 	  Available for quoted reply and forward.
 
-	To format the date fields, _dateFormat_ and _toLocal_ are provided.
+	To format the date fields, _dateFormat_ and _.Local_ are provided.
 	Refer to the *TEMPLATE FUNCTIONS* section for details.
 
 *Subject*
-	The subject of the email is available for quoted reply and forward.
+	The subject of the email.
 
+	```
 	{{.Subject}}
+	```
+
+*Flags*
+	List of message flags, not available when composing, replying nor
+	forwarding. This is a list of strings that may be converted to a single
+	string with *join*.
+
+	```
+	{{.Flags | join ""}}
+	```
+
+*Labels*
+	Message labels (for example notmuch tags). Not available when composing,
+	replying nor forwarding. This is a list of strings that may be converted
+	to a single string with *join*.
+
+	```
+	{{.Labels | join " "}}
+	```
+
+*Size*
+	The size of the message in bytes. Not available when composing, replying
+	nor forwarding. It can be formatted with *humanReadable*.
+
+	```
+	{{.Size | humanReadable}}
+	```
+
+*Any header value*
+	Any header value of the email.
+
+	```
+	{{.Header "x-foo-bar"}}
+	```
+
+	Any header values of the original forwared or replied message:
+
+	```
+	{{.OriginalHeader "x-foo-bar"}}
+	```
 
 *MIME Type*
 	MIME Type is available for quoted reply and forward.
 
-	- _OriginalMIMEType_: MIME type info of quoted mail part. Usually
+	- _{{.OriginalMIMEType}}_: MIME type info of quoted mail part. Usually
 	  _text/plain_ or _text/html_.
 
 *Original Message*
@@ -88,6 +135,19 @@ available always.
 	{{.OriginalText}}
 	```
 
+*Account info*
+	The current account name:
+
+	```
+	{{.Account}}
+	```
+
+	Currently selected mailbox folder:
+
+	```
+	{{.Folder}}
+	```
+
 # TEMPLATE FUNCTIONS
 
 Besides the standard functions described in go's text/template documentation,
@@ -107,6 +167,49 @@ aerc provides the following additional functions:
 	{{quote .OriginalText}}
 	```
 
+*join*
+	Join the provided list of strings with a separator:
+
+	```
+	{{.To | names | join ", "}}
+	```
+
+*names*
+	Extracts the names part from a mail.Address list. If there is no name
+	available, the email address is returned instead.
+
+	```
+	{{.To | names | join ", "}}
+	{{index (.To | names) 0}}
+	```
+
+*emails*
+	Extracts the addresses part from a mail.Address list.
+
+	```
+	{{.To | emails | join ", "}}
+	{{index (.To | emails) 0}}
+	```
+
+*mboxes*
+	Extracts the mbox part from a mail.Address list (i.e. _smith_ from
+	_smith@example.com_).
+
+	```
+	{{.To | mboxes | join ", "}}
+	{{index (.To | mboxes) 0}}
+	```
+
+*persons*
+	Formats a list of mail.Address into a list of strings containing the
+	human readable form of RFC5322 (e.g. _Firstname Lastname
+	<email@address.tld>_).
+
+	```
+	{{.To | persons | join ", "}}
+	{{index (.To | persons) 0}}
+	```
+
 *exec*
 	Execute external command, provide the second argument to its stdin.
 
@@ -114,11 +217,11 @@ aerc provides the following additional functions:
 	{{exec `/usr/local/share/aerc/filters/html` .OriginalText}}
 	```
 
-*toLocal*
+*.Local*
 	Convert the date to the local timezone as specified by the locale.
 
 	```
-	{{toLocal .Date}}
+	{{.Date.Local}}
 	```
 
 *dateFormat*
@@ -129,6 +232,28 @@ aerc provides the following additional functions:
 	{{dateFormat .Date "Mon Jan 2 15:04:05 -0700 MST 2006"}}
 	```
 
+	You can also use the _.DateAutoFormat_ method to format the date
+	according to *\*-time\*format* settings:
+
+	```
+	{{.DateAutoFormat .OriginalDate.Local}}
+	```
+
+*humanReadable*
+	Return the human readable form of an integer value.
+
+	```
+	{{humanReadable 3217653721}}
+	```
+
+*cwd*
+	Return the current working directory with the user home dir replaced by
+	_~_.
+
+	```
+	{{cwd}}
+	```
+
 *version*
 	Returns the version of aerc, which can be useful for things like X-Mailer.