.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "AERC-TEMPLATES" "7" "2024-04-07" .PP .SH NAME .PP aerc-templates - template file specification for \fBaerc\fR(1) .PP .SH SYNOPSIS .PP 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 app.\& .PP Template files are composed of headers, followed by a newline, followed by the body text.\& .PP Example: .PP .nf .RS 4 X-Clacks-Overhead: GNU Terry Pratchett Hello, Greetings, Chuck .fi .RE .PP If you have a template that doesn'\&t add any header, it \fBmust\fR be preceded by a newline, to avoid parsing parts of the body as header text.\& .PP All headers defined in the template will have precedence over any headers that are initialized by aerc (e.\&g.\& Subject, To, From, Cc) when composing a new message, forwarding or replying.\& .PP .SH MESSAGE DATA .PP The following data can be used in templates.\& Though they are not all available always.\& .PP \fBAddresses\fR .RS 4 An array of mail.\&Address.\& That can be used to add sender or recipient names to the template.\& .PP .PD 0 .IP \(bu 4 \fI{{.\&From}}\fR: List of senders.\& .IP \(bu 4 \fI{{.\&Peer}}\fR: List of senders or To recipients if the message is from you.\& .IP \(bu 4 \fI{{.\&To}}\fR: List of To recipients.\& Not always Available.\& .IP \(bu 4 \fI{{.\&ReplyTo}}\fR: List of ReplyTo recipients.\& Not always Available.\& .IP \(bu 4 \fI{{.\&Cc}}\fR: List of Cc recipients.\& Not always Available.\& .IP \(bu 4 \fI{{.\&Bcc}}\fR: List of Cc recipients.\& Not always Available.\& .IP \(bu 4 \fI{{.\&OriginalFrom}}\fR: List of senders of the original message.\& Available for quoted reply and forward.\& .PD .PP Example: .PP Get the name of the first sender.\& .nf .RS 4 {{(index \&.From 0)\&.Name}} {{index (\&.From | names) 0}} .fi .RE .PP Get the email address of the first sender.\& .nf .RS 4 {{(index \&.From 0)\&.Address}} .fi .RE .PP .RE \fBDate and Time\fR .RS 4 The date and time information is always available and can be easily formatted.\& .PP .PD 0 .IP \(bu 4 \fI{{.\&Date}}\fR: Date and time information when the compose window is opened.\& .IP \(bu 4 \fI{{.\&OriginalDate}}\fR: Date and time when the original message was received.\& Available for quoted reply and forward.\& .PD .PP To format the date fields, \fIdateFormat\fR and \fI.\&Local\fR are provided.\& Refer to the \fBTEMPLATE FUNCTIONS\fR section for details.\& .PP .RE \fBSubject\fR .RS 4 The subject of the email (\fIThreadPrefix\fR will be empty unless threading is enabled).\& .PP .nf .RS 4 {{\&.ThreadPrefix}}{{if \&.ThreadFolded}}{{printf "{%d}" \&.ThreadCount}}{{end}}{{\&.Subject}} .fi .RE .PP The subject of the email stripped of any \fIRe:\fR and \fIFwd:\fR prefixes.\& .PP .nf .RS 4 {{\&.SubjectBase}} .fi .RE .RE \fBThreading\fR .RS 4 When threading is enabled, these attributes are available in the message list: .PP \fIThreadPrefix\fR .RS 4 If the message is part of a thread, this will contain arrows that represent the message tree based on \fIIn-Reply-To\fR and \fIReferences\fR headers.\& .PP .RE \fIThreadFolded\fR .RS 4 Will be \fItrue\fR if the message has thread children which are hidden by \fB:fold\fR.\& .PP .RE \fIThreadCount\fR .RS 4 The number of messages in the thread.\& .PP .RE \fIThreadUnread\fR .RS 4 The number of unread messages in the thread.\& .PP .RE .RE \fBFlags\fR .RS 4 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 \fBjoin\fR.\& .PP .nf .RS 4 {{\&.Flags | join ""}} .fi .RE .PP .RE \fBIsReplied\fR, \fBHasAttachment\fR, \fBIsFlagged\fR, \fBIsRecent\fR, \fBIsUnread\fR, \fBIsMarked\fR, \fBIsDraft\fR .RS 4 Individual boolean flags.\& not available when composing, replying nor forwarding.\& .PP .nf .RS 4 {{if \&.IsFlagged}}★{{end}} .fi .RE .PP .RE \fBLabels\fR .RS 4 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 \fBjoin\fR.\& .PP .nf .RS 4 {{\&.Labels | join " "}} .fi .RE .PP .RE \fBSize\fR .RS 4 The size of the message in bytes.\& Not available when composing, replying nor forwarding.\& It can be formatted with \fBhumanReadable\fR.\& .PP .nf .RS 4 {{\&.Size | humanReadable}} .fi .RE .PP .RE \fBFilename\fR .RS 4 The full path of the message file.\& Not available when composing, replying nor forwarding.\& For the notmuch backend, it returns a random filename if there are multiple files associated with the message.\& .PP .RE \fBFilenames\fR .RS 4 A list of the full paths of the files associated with the message.\& For maildir this is always a list with a single element.\& Not available when composing, replying nor forwarding.\& .PP .RE \fBAny header value\fR .RS 4 Any header value of the email.\& .PP .nf .RS 4 {{\&.Header "x-foo-bar"}} .fi .RE .PP Any header values of the original forwared or replied message: .PP .nf .RS 4 {{\&.OriginalHeader "x-foo-bar"}} .fi .RE .RE \fBMessage-ID\fR .RS 4 The message-ID of the message.\& .PP .nf .RS 4 :term b4 am {{\&.MessageId}} .fi .RE .PP .RE \fBMIME Type\fR .RS 4 MIME type is available for quoted reply and forward.\& .PP .PD 0 .IP \(bu 4 \fI{{.\&OriginalMIMEType}}\fR: MIME type info of quoted mail part.\& Usually \fItext/plain\fR or \fItext/html\fR.\& .PD .PP .RE \fBOriginal Message\fR .RS 4 When using quoted reply or forward, the original message is available in a field called \fIOriginalText\fR.\& .PP .nf .RS 4 {{\&.OriginalText}} .fi .RE .PP .RE \fBAccount info\fR .RS 4 The current account name: .PP .nf .RS 4 {{\&.Account}} .fi .RE .PP Currently selected mailbox folder: .PP .nf .RS 4 {{\&.Folder}} .fi .RE .PP Current message counts for all folders: .PP .nf .RS 4 {{\&.Recent}} {{\&.Unread}} {{\&.Exists}} {{\&.RUE}} .fi .RE .PP IANA role of the mailbox, converted to lowercase: .PP .nf .RS 4 {{\&.Role}} .fi .RE .PP \fBaerc\fR implements two additional custom roles: A '\&query'\& role is given to folders from a notmuch query-map and '\&virtual'\& indicates a virtual node in the directory tree listing: .PP .nf .RS 4 {{if eq \&.Role "query"}}{{\&.\&.\&.}}{{else}}{{\&.\&.\&.}}{{end}} .fi .RE .PP Current message counts for specific folders: .PP .nf .RS 4 {{\&.Recent "inbox"}} {{\&.Unread "inbox" "aerc/pending"}} {{\&.Exists "archive" "spam" "foo/baz" "foo/bar"}} {{\&.RUE "inbox"}} .fi .RE .PP .RE \fBStatus line\fR .PP .RS 4 The following data will only be available in the status line templates: .PP Connection state.\& .PP .nf .RS 4 {{\&.Connected}} {{\&.ConnectionInfo}} .fi .RE .PP General status information (e.\&g.\& filter, search) separated with \fB[statusline].\&separator\fR.\& .PP .nf .RS 4 {{\&.ContentInfo}} .fi .RE .PP Combination of \fB{{.\&ConnectionInfo}}\fR and \fB{{.\&StatusInfo}}\fR separated with \fB[statusline].\&separator\fR.\& .PP .nf .RS 4 {{\&.StatusInfo}} .fi .RE .PP General on/off information (e.\&g.\& passthrough, threading, sorting), separated with \fB[statusline].\&separator\fR.\& .PP .nf .RS 4 {{\&.TrayInfo}} .fi .RE .PP Currently pressed key sequence that does not match any key binding and/or is incomplete.\& .PP .nf .RS 4 {{\&.PendingKeys}} .fi .RE .PP .RE .SH TEMPLATE FUNCTIONS .PP Besides the standard functions described in go'\&s text/template documentation, aerc provides the following additional functions: .PP \fBwrap\fR .RS 4 Wrap the original text to the specified number of characters per line.\& .PP .nf .RS 4 {{wrap 72 \&.OriginalText}} .fi .RE .PP .RE \fBquote\fR .RS 4 Prepends each line with \fI"> "\fR.\& .PP .nf .RS 4 {{quote \&.OriginalText}} .fi .RE .PP .RE \fBtrimSignature\fR .RS 4 Removes the signature froma passed in mail.\& Quoted signatures are kept as they are.\& .PP .nf .RS 4 {{trimSignature \&.OriginalText}} .fi .RE .PP .RE \fBjoin\fR .RS 4 Join the provided list of strings with a separator: .PP .nf .RS 4 {{\&.To | names | join ", "}} .fi .RE .PP .RE \fBsplit\fR .RS 4 Split a string into a string slice with a separator: .PP .nf .RS 4 {{\&.To | names | join ", " | split ", "}} .fi .RE .PP .RE \fBnames\fR .RS 4 Extracts the names part from a mail.\&Address list.\& If there is no name available, the mbox (email address without @domain) is returned instead.\& .PP .nf .RS 4 {{\&.To | names | join ", "}} {{index (\&.To | names) 0}} .fi .RE .PP .RE \fBfirstnames\fR .RS 4 Extracts the first names part from a mail.\&Address list.\& If there is no name available, the short mbox (start of email address without @domain) is returned instead.\& .PP .nf .RS 4 {{\&.To | firstnames | join ", "}} {{index (\&.To | firstnames) 0}} .fi .RE .PP .RE \fBinitials\fR .RS 4 Extracts the initials from the names part from a mail.\&Address list.\& If there is no name available, the first letter of the email address is returned instead.\& .PP .nf .RS 4 {{\&.To | initials | join ", "}} {{index (\&.To | initials) 0}} .fi .RE .PP .RE \fBemails\fR .RS 4 Extracts the addresses part from a mail.\&Address list.\& .PP .nf .RS 4 {{\&.To | emails | join ", "}} {{index (\&.To | emails) 0}} .fi .RE .PP .RE \fBmboxes\fR .RS 4 Extracts the mbox part from a mail.\&Address list (i.\&e.\& \fIsmith\fR from \fIsmith@example.\&com\fR).\& .PP .nf .RS 4 {{\&.To | mboxes | join ", "}} {{index (\&.To | mboxes) 0}} .fi .RE .PP .RE \fBshortmboxes\fR .RS 4 Extracts the short mbox part from a mail.\&Address list (i.\&e.\& \fIsmith\fR from \fIsmith.\&and.\&wesson@example.\&com\fR).\& .PP .nf .RS 4 {{\&.To | shortmboxes | join ", "}} {{index (\&.To | shortmboxes) 0}} .fi .RE .PP .RE \fBpersons\fR .RS 4 Formats a list of mail.\&Address into a list of strings containing the human readable form of RFC5322 (e.\&g.\& \fIFirstname Lastname \fR).\& .PP .nf .RS 4 {{\&.To | persons | join ", "}} {{index (\&.To | persons) 0}} .fi .RE .PP .RE \fB.\&Attach\fR .RS 4 Attaches a file to the message being composed.\& .PP .nf .RS 4 {{\&.Attach \&'/usr/libexec/aerc/filters/html\&'}} .fi .RE .PP .RE \fBexec\fR .RS 4 Execute external command, provide the second argument to its stdin.\& .PP .nf .RS 4 {{exec `/usr/libexec/aerc/filters/html` \&.OriginalText}} .fi .RE .PP .RE \fB.\&Local\fR .RS 4 Convert the date to the local timezone as specified by the locale.\& .PP .nf .RS 4 {{\&.Date\&.Local}} .fi .RE .PP .RE \fBdateFormat\fR .RS 4 Format date and time according to the format passed as the second argument.\& The format must be specified according to go'\&s time package format.\& .PP .nf .RS 4 {{dateFormat \&.Date "Mon Jan 2 15:04:05 -0700 MST 2006"}} .fi .RE .PP You can also use the \fI.\&DateAutoFormat\fR method to format the date according to \fB*-time*format\fR settings: .PP .nf .RS 4 {{\&.DateAutoFormat \&.OriginalDate\&.Local}} .fi .RE .PP .RE \fBnow\fR .RS 4 Return the current date as a golang time.\&Time object that can be formatted with \fBdateFormat\fR.\& .PP .nf .RS 4 {{dateFormat now "Mon Jan 2 15:04:05 -0700 MST 2006"}} .fi .RE .PP .RE \fBhumanReadable\fR .RS 4 Return the human readable form of an integer value.\& .PP .nf .RS 4 {{humanReadable 3217653721}} .fi .RE .PP .RE \fBcwd\fR .RS 4 Return the current working directory with the user home dir replaced by \fI~\fR.\& .PP .nf .RS 4 {{cwd}} .fi .RE .PP .RE \fBcompactDir\fR .RS 4 Reduce a directory path into a compact form.\& The directory name will be split with \fI/\fR and each part will be reduced to the first letter in its name: \fIINBOX/01_WORK/PROJECT\fR will become \fII/W/PROJECT\fR.\& .PP .nf .RS 4 {{compactDir \&.Folder}} .fi .RE .PP .RE \fBcontains\fR .RS 4 Checks if a string contains a substring.\& .PP .nf .RS 4 {{contains "" \&.OriginalText}} .fi .RE .PP .RE \fBhasPrefix\fR .RS 4 Checks if a string has a prefix.\& .PP .nf .RS 4 {{hasPrefix "Business" \&.Folder}} .fi .RE .PP .RE \fBtoLower\fR .RS 4 Convert a string to lowercase.\& .PP .nf .RS 4 {{toLower "SPECIAL OFFER!"}} .fi .RE .PP .RE \fBtoUpper\fR .RS 4 Convert a string to uppercase.\& .PP .nf .RS 4 {{toUpper "important"}} .fi .RE .PP .RE \fBreplace\fR .RS 4 Perform a regular expression substitution on the passed string.\& .PP .nf .RS 4 {{replace `(\&.+) - \&.+ at \&.+.\&.+` `$1` ((index \&.OriginalFrom 0)\&.Name)}} .fi .RE .PP .RE \fB.\&Style\fR .RS 4 Apply a user-defined style (see \fBaerc-stylesets\fR(7)) to a string.\& .PP .nf .RS 4 {{\&.Style \&.Account "red"}} {{\&.Style \&.ThreadPrefix "thread"}}{{\&.Subject}} .fi .RE .PP .RE \fB.\&StyleSwitch\fR .RS 4 Apply a user-defined style (see \fBaerc-stylesets\fR(7)) to a string if it matches one of the associated regular expressions.\& If the string does not match any of the expressions, leave it unstyled.\& .PP .nf .RS 4 {{\&.StyleSwitch \&.Subject (`^([[w-]+]s*)?[(RFC )?PATCH` "cyan")}} {{\&.StyleSwitch (\&.From | names | join ", ") (case `Tim` "cyan") (case `Robin` "pink-blink") (default "blue")}} .fi .RE .PP .RE \fB.\&StyleMap\fR .RS 4 Apply user-defined styles (see \fBaerc-stylesets\fR(7)) to elements of a string list.\& The logic is the same than \fB.\&StyleSwitch\fR but works on a list of elements.\& An additional \fBexclude\fR option is available to remove the matching elements from the list.\& .PP .nf .RS 4 {{\&.StyleMap \&.Labels (exclude \&.Folder) (exclude `^spam$`) (case `^inbox$` "red") (case `^Archive/\&.*` "green") (default "blue") | join " "}} .fi .RE .PP .RE \fBversion\fR .RS 4 Returns the version of aerc, which can be useful for things like X-Mailer.\& .PP .nf .RS 4 X-Mailer: aerc {{version}} .fi .RE .PP .RE \fBmatch\fR .RS 4 Check if a string matches a regular expression.\& This is intended for use in conditional control flow: .PP .nf .RS 4 {{if match \&.Folder `\&.*/Archive-[0-9]+`}}{{humanReadable \&.Unread}}{{end}} .fi .RE .PP .RE \fBswitch\fR .RS 4 Do swich/case/default control flows.\& The switch value is compared with regular expressions.\& If none of the case/default arms match, an empty string is returned.\& .PP .nf .RS 4 {{switch \&.Folder (case `^INBOX$` "📥") (case `^Archive/\&.*` "🗃") (default "📁")}} .fi .RE .PP .RE \fBmap\fR .RS 4 Transform a string list into another one.\& The logic is the same than \fBswitch\fR but works on a list of elements.\& An additional \fBexclude\fR option is available to remove the matching elements from the list.\& .PP .nf .RS 4 {{map \&.Labels (exclude \&.Folder) (exclude `^spam$`) (case `^inbox$` "📥") (case `^Archive/\&.*` "🗃") | join " "}} .fi .RE .PP .RE \fBFunction chaining\fR .RS 4 All of the template functions can be chained together if needed.\& .PP Example: Automatic HTML parsing for text/html mime type messages .PP .nf .RS 4 {{if eq \&.OriginalMIMEType "text/html"}} {{exec `/usr/libexec/aerc/filters/html` \&.OriginalText | wrap 72 | quote}} {{else}} {{wrap 72 \&.OriginalText | trimSignature | quote}} {{end}} .fi .RE .PP .RE .SH SEE ALSO .PP \fBaerc\fR(1) \fBaerc-config\fR(5) .PP .SH AUTHORS .PP Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors.\& For more information about aerc development, see \fIhttps://sr.\&ht/~rjarry/aerc/\fR.\&