Common Macros

From ESM Wiki
Revision as of 16:04, 11 November 2009 by Sfyrin (Talk | contribs)

Jump to: navigation, search

The following macros can be used in templates and conditions of all engines:

$attachment
$attachment.base64
$attachment.headers
$attachment.text
$attachment.malformed
$attachment.multipart
$attachment.resource_fork
$attachment.resource_fork.base64
$attachment.file_name
$attachment.mime_type
$body
$body.html
$body_part
$body_part.base64
$body_part.is_body
$body_part.is_attachment
$body_part.size
$body_part.headers
$body_part.text
$body_part.malformed
$body_part.multipart
$body_part.file_name
$body_part.mime_type

$body_part.digest
$body_part.resource_fork
$body_part.resource_fork.size
$body_part.resource_fork.digest
$data
$data.size
$data.digest
$decode_base64
$empty
$encode_base64
$json_escape
$header
$header.name
$header.body
$headers
$headers.message_id
$headers.in_reply_to
$headers.references
$headers.from
$headers.sender
$headers.reply_to
$headers.to
$headers.cc

$headers.bcc
$headers.subject
$hmac
$host
$ip
$ip.dec
$ip.hex
$if_not_empty
$gethostname
$group
$message_id
$md5
$not_empty
$pid
$recipient
$recipient.local
$recipient.domain
$recipient.component
$sender
$sender.local
$sender.domain
$sender.component
$sha1

$size
$size_hex
$sp, $br, $cr, $lf, $crlf, $htab
$subject
$text_find_replace_all
$text_truncate
$thread
$time
$time6
$timezone, $timezone.sign, $timezone.hh, $timezone.mm, $timezone.ss
$uri_escape
$wrap
$xml_cdata
$xml_escape
$year, $month, $day, $hour, $minute, $second

$attachment

Description: Email attachment data. Attachment is every body part that is not body in body-attachments-view typical for MUA's.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.base64

Description: Email attachment data encoded as base64. Using this macro may be more effective then using ${encode_base64 $attachment} in most cases because attachment data in email is likely to be already encoded as base64.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.headers

Description: Email attachment headers as single string.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.text

Description: Text extracted from email attachment and converted to utf-8 encoding. This macro is intended to extract pure text from different types of documents for this text to be used in content analyzing tools. Though currently this macro is fully equivalent to $attachment it will be enhanced to support as much types of documents as possible.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.malformed

Description: Flag that indicates whether attachment is malformed from MIME point of view. It has two values: "yes" and "no". When attachment is malformed its data will be empty. One should use this flag to exclude malformed attachments from processing to avoid lost of data in scenarios like attachment stripping. For example:
<engines>
  <file>
    <save>
      <precondition>$attachment.malformed $EQ no</precondition>
      ...
    </save>
  </file>
</engines>
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.multipart

Description: Flag that indicates whether attachment is a legacy Apple file that consists from data and resource forks. It has two values: "yes" and "no". When attachment is multipart its $attachment.resource_fork may be not empty. One should use this flag to exclude multipart attachments from processing to avoid lost of data in scenarios like attachment stripping. For example (in combination with malformed flag):
<engines>
  <file>
    <save>
      <precondition>$attachment.malformed $EQ no $AND $attachment.multipart $EQ no</precondition>
      ...
    </save>
  </file>
</engines>

However it is expected that such file format is depricated thus will rarely appear in emails.

Dimension: $attachment
Stage: smtp-end-of-data

$attachment.resource_fork

Description: Resource fork of legacy Apple file that consists from data and resource forks. It is expected that such file format is depricated thus will rarely appear in emails.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.resource_fork.base64

Description: Base64 encoded resource fork of legacy Apple file that consists from data and resource forks. Using this macro may be more effective then using ${encode_base64 $attachment.resource_fork} in most cases because attachment data in email is likely to be already encoded as base64. It is expected that such file format is depricated thus will rarely appear in emails.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.file_name

Description: File name of an attachment as extracted from headers and converted to utf-8. Will be empty if no file name is specified in headers.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.mime_type

Description: MIME type of an attachment as extracted from headers. Will be empty if no MIME type is specified in headers.
Dimension: $attachment
Stage: smtp-end-of-data

$body

Description: Email body in body-attachment-view typical for MUA's. Body is the first text body part in email or text body part in first alternative.
Stage: smtp-end-of-data

$body.html

Description: Html alternative of email body in body-attachment-view typical for MUA's. Html body is the first html body part in email or html body part in first alternative.
Stage: smtp-end-of-data

$body_part

Description: Body part of a email in body-part-view. Unlike a body-attachments-view body-part-view doesn't distinguish between body and attachments. It treats all body parts in the same manner. This is more closely corresponds to MIME standard because it doesn't distinguish body and attachments - all are body parts.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.base64

Description: Base64-encoded body part of a email. Using this macro may be more effective then using ${encode_base64 $body_part} in most cases because body part data in email is likely to be already encoded as base64.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.is_body

Description: Flag that indicates whether body part is body in body-attachments-view. It has two values: "yes" and "no". Body is the first text or html body part in email or text or html body part in first alternative.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.is_attachment

Description: Flag that indicates whether body part is attachment in body-attachments-view. It has two values: "yes" and "no". Everything that is not body is attachment.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.size

Description: Size of body part in bytes. This is deprecated because of available $size macro.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.headers

Description: Body part headers as single string.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.text

Description: Text extracted from email body part and converted to utf-8 encoding. This macro is intended to extract pure text from different types of documents for this text to be used in content analyzing tools. Though currently this macro is fully equivalent to $body_part it will be enhanced to support as much types of documents as possible.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.malformed

Description: Flag that indicates whether body part is malformed from MIME point of view. It has two values: "yes" and "no". When body part is malformed its data will be empty. One should use this flag to exclude malformed body parts from processing to avoid lost of data in scenarios like body stripping. For example:
<engines>
  <file>
    <save>
      <precondition>$body_part.malformed $EQ no</precondition>
      ...
    </save>
  </file>
</engines>
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.multipart

Description: Flag that indicates whether body part is a legacy Apple file that consists from data and resource forks. It has two values: "yes" and "no". When body part is multipart its $body_part.resource_fork may be not empty. One should use this flag to exclude multipart body parts from processing to avoid lost of data in scenarios like body stripping. For example (in combination with malformed flag):
<engines>
  <file>
    <save>
      <precondition>$body_part.malformed $EQ no $AND $body_part.multipart $EQ no</precondition>
      ...
    </save>
  </file>
</engines>

However it is expected that such file format is depricated thus will rarely appear in emails.

Dimension: $body_part
Stage: smtp-end-of-data

$body_part.file_name

Description: File name of a body part as extracted from headers and converted to utf-8. Will be empty if no file name is specified in headers.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.mime_type

Description: MIME type of a body part as extracted from headers and converted to utf-8. Will be empty if no file name is specified in headers.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.digest

Description: SHA1 digest calculated from body part data. This is deprecated because of available $sha1 macro.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.resource_fork

Description: Resource fork of legacy Apple file that consists from data and resource forks. It is expected that such file format is depricated thus will rarely appear in emails.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.resource_fork.size

Description: Size of resource fork of body part. This is deprecated because of available $size macro.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.resource_fork.digest

Description: SHA1 digest calculated from resource fork data of body part. This is deprecated because of available $sha1 macro.
Dimension: $body_part
Stage: smtp-end-of-data

$data

Description: Whole email data. Uses LF's for linebreaks.
Stage: smtp-end-of-data

$data.size

Description: Size of email data in bytes. This is deprecated because of available $size macro.
Stage: smtp-end-of-data

$data.digest

Description: SHA1 digest calculated from email data. This is deprecated because of available $sha1 macro.
Stage: smtp-end-of-data

$decode_base64

Description: Decodes data from base64 encoding.
Arguments: 1) Data to decode.

$empty

Description: Empty string.

$encode_base64

Description: Encodes data to base64 encoding.
Arguments: 1) Data to encode.
2) Maximum line length in encoded data. Optional, default is unlimited (do not break on lines).
3) Flag whether to suppress final newline. Can be "yes" or "no". Optional, default to "yes".
4) Flag whether to use CRLF's instead of LF's for newlines. Can be "yes" or "no". Optional, default to "no".

$json_escape

Description: Escapes string to be a valid JSON string.
Arguments: One or more arguments are concatenated and then escaped.

$header

Description: Email header.
Dimension: $header
Stage: smtp-end-of-data

$header.name

Description: Email header name.
Dimension: $header
Stage: smtp-end-of-data

$header.body

Description: Email header body.
Dimension: $header
Stage: smtp-end-of-data

$headers

Description: Email headers as single string.
Stage: smtp-end-of-data

$headers.message_id

Description: ID extracted from Message-ID header value.
Stage: smtp-end-of-data

$headers.in_reply_to

Description: ID extracted from In-Reply-To header value. There may be multiple ID's so this macro has dimension.
Dimension: $headers.in_reply_to
Stage: smtp-end-of-data

$headers.references

Description: ID extracted from References header value. There may be multiple ID's so this macro has dimension.
Dimension: $headers.references
Stage: smtp-end-of-data

$headers.from

Description: Address extracted from From header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.from
Stage: smtp-end-of-data

$headers.sender

Description: Address extracted from Sender header value.
Stage: smtp-end-of-data

$headers.reply_to

Description: Address extracted from Reply-To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.reply_to
Stage: smtp-end-of-data

$headers.to

Description: Address extracted from To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.to
Stage: smtp-end-of-data

$headers.cc

Description: Address extracted from Cc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.cc
Stage: smtp-end-of-data

$headers.bcc

Description: Address extracted from Bcc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.bcc
Stage: smtp-end-of-data

$headers.subject

Description: Text extracted from Subject header value and converted to utf-8.
Stage: smtp-end-of-data

$hmac

Description: Calculates HMAC digest from provided data and key.
Arguments: 1) Data to calculate from.
2) Key to use.
3) Hash function to use. Optional, default to "sha1". Allowed values: "md2", "md4", "md5", "sha", "sha1", "dss", "dss1", "ecdsa", "sha224", "sha256", "sha384", "sha512", "ripemd160".

$host

Description: Host name of a client sending a request as extracted from message headers or from other sources.

$ip

Description: IP address in doted-decimal notation of a client sending a request as extracted from message headers or from other sources.

$ip.dec

Description: IP address as decimal of a client sending a request as extracted from message headers or from other sources.

$ip.hex

Description: IP address as hexadecimal of a client sending a request as extracted from message headers or from other sources.

$if_not_empty

Description: Checks if second argument is not empty, adds prefix and suffix and returns obtained value. Otherwise returns emtpy value.
Arguments: 1) Prefix.
2) Checked value.
3) Suffix.

$gethostname

Description: Result of gethostname() call. Name of the host where application is running.

$group

Description: ID of MPP policy group that request is processed with.

$message_id

Description: Short equivalent to $headers.message_id.

$md5

Description: Calculates MD5 digest from data.
Arguments: 1) Data to calculate from.

$not_empty

Description: Returns first not null and not empty value from its arguments evaluating from left to right. Otherwise returns null (if all are null) or empty value. Has important property that it will be null only if ALL arguments are null. This property may be used for merging execution branches.
Arguments: One or more.

$pid

Description: Process ID of application.

$recipient

Description: SMTP recipient address.
Dimension: $recipient

$recipient.local

Description: Local part of SMTP recipient address.
Dimension: $recipient

$recipient.domain

Description: Domain part of SMTP recipient address.
Dimension: $recipient

$recipient.component

Description: Components of SMTP recipient address. Components are address itself and domains starting from more specific ending with less specific.
Dimension: $recipient, $recipient.component

$sender

Description: SMTP sender address.

$sender.local

Description: Local part of SMTP sender address.

$sender.domain

Description: Domain part of SMTP sender address.

$sender.component

Description: Components of SMTP sender address. Components are address itself and domains starting from more specific ending with less specific.
Dimension: $sender.component

$sha1

Description: Calculates SHA1 digest from data.
Arguments: 1) Data to calculate from.

$size

Description: Calculates size of data in bytes.
Arguments: 1) Data to calculate from.

$size_hex

Description: Calculates size of data in bytes as hexadecimal value.
Arguments: 1) Data to calculate from.

$sp, $br, $cr, $lf, $crlf, $htab

Description: Special characters and sequences: SP, LF, CR, LF, CRLF, HTAB.

$subject

Description: Short variant of $headers.subject.

$text_find_replace_all

Description: In given data replaces all specified sequences with corresponding replacers. Can be used as general purpose escaping function.
Arguments: 1) Data to replace in.
Each even argument is a sequence to replace.
Each odd argument is a corresponding replacer.

$text_truncate

Description: Truncate data to a specified size if data size is greater then this size. Truncation occur at the end of data. Optionally puts specified truncation sequence (such as "...") at the end of data. If truncation sequence is specified data is truncated to lower size so that total size remains no more then specified size.
Arguments: 1) Data to truncate.
2) Data size to truncate data to.
3) Truncation sequence. Optional, default to empty.

$thread

Description: Current thread ID. Can be useful for unique ID's generation.

$time

Description: Current timestamp. Evaluated only once at first usage in a pipeline for each request and then remains the same even if actual time is changing while request is being processed.

$time6

Description: Current timestamp as compact 6-characters value. Evaluated at each usage. Can be useful for unique ID's generation.

$timezone, $timezone.sign, $timezone.hh, $timezone.mm, $timezone.ss

Description: Current timezone and its different parts. Timezone is presented in the following format +/-HH:MM (for example +02:00). Other macros are timezone parts: sign, hours, minutes, seconds.

$uri_escape

Description: Escapes string for URI.
Arguments: 1) String to escape.

$wrap

Description: Special tool to "wrap" expression by last dimension. Used to create lists from dimensional (multi-value) expressions. It works as follow:
  • Iterates through last dimension of an expression. Last dimension is the right-most dimension of a union of dimensions of macros used in an expression starting from left to right.
  • At each iteration evaluates expression and substitutes it instead of placeholder $# in a wrap template.
  • Evaluates other parts of a wrap template. Prefix is evaluated at each iteration except first, suffix - except last. Effectively prefix and suffix has same effect and serves as list separator.
  • Concatenates values of wrap template obtained at each iteration at single value. This value is a result of $wrap macro.
  • Result value looses dimension that it is wrapped by.

For example lets assume that an email has three recipients: rcpt_1@domain.com, rcpt_2@example.net and rcpt_3@my.host.edu. Expression:

${wrap $#{ OR } $recipient}

will be evaluated to:

rcpt_1@domain.com OR rcpt_2@example.net OR rcpt_3@my.host.edu

and will not have $recipient dimension.

Arguments: 1) Wrap template. Syntax is the following:
wrap_template =   "{" 0*1wrap_prefix wrap_main 0*1wrap_suffix "}"        ; generic version
                | 0*1wrap_prefix wrap_main_without_space 0*1wrap_suffix  ; simplified version if main part has no spaces inside

wrap_prefix              = "{" *(template | wrap_placeholder) "}"        ; prefix is added at each iteration except first
wrap_suffix              = "{" *(template | wrap_placeholder) "}"        ; suffix is added at each iteration except last
wrap_main                = *(template | wrap_placeholder)                ; main part is always added
wrap_main_without_space  = *(template_without_space | wrap_placeholder)  ; main part is always added

wrap_placeholder = "$#" | "${#}"                                         ; this will be replaced with expression value at each iteration
                                                                         ; note that it can't be used in arguments of a macro

template               = ...                                             ; usual template expression
template_without_space = ...                                             ; usual template expression without spaces inside

For example expression:

SELECT FROM `access_list` WHERE ${wrap `address`=$#{ OR } '${escape $recipient.component}'}

in the context of MySQL Engine will be evaluated for each recipient as follow:

SELECT FROM `access_list` WHERE `address`='test1@example.domain.com' OR `address`='example.domain.com' OR `address`='domain.com' OR `address`='com'

provided that recipient is test1@example.domain.com. Result value will have only $recipient dimension - $recipient.component dimension will be wrapped out.

2) Expression to wrap.

$xml_cdata

Description: Makes XML CDATA from a string: replaces all "]]>" with "]]]]><![CDATA[>", prefixes with "<![CDATA[" and suffixes with "]]>".
Arguments: 1) String to make from.

$xml_escape

Description: Escapes string for XML.
Arguments: 1) String to escape.

$year, $month, $day, $hour, $minute, $second

Description: Current year, month, etc. Calculated from value of $time macro thus evaluated once at first usage of any of them.
Personal tools