<a id="standard-library"></a>

# Standard library

Functions which are documented in this chapter are considered *core* functions hence are available in all *contexts*. Functions in the standard library may be recognized by the fact that they are all in lowercase.

* **Array** [`array_combine()`](#array_combine) [`array_every()`](#array_every) [`array_filter()`](#array_filter) [`array_find()`](#array_find) [`array_includes()`](#array_includes) [`array_join()`](#array_join) [`array_keys()`](#array_keys) [`array_map()`](#array_map) [`array_random()`](#array_random) [`array_range()`](#array_range) [`array_reduce()`](#array_reduce) [`array_reverse()`](#array_reverse) [`array_sort()`](#array_sort) [`array_shuffle()`](#array_shuffle) [`array_unique()`](#array_unique)
* **Cryptographic** [`aes_decrypt()`](#aes_decrypt) [`aes_encrypt()`](#aes_encrypt) [`hmac_md5()`](#hmac_md5) [`hmac_sha1()`](#hmac_sha1) [`hmac_sha2()`](#hmac_sha2) [`md5()`](#md5) [`sha1()`](#sha1) [`sha2()`](#sha2) [`hash()`](#hash) [`pkcs11_load()`](#pkcs11_load) [`rsa_privatekey()`](#rsa_privatekey) [`is_rsa_privatekey()`](#is_rsa_privatekey) [`rsa_sign()`](#rsa_sign) [`rsa_verify()`](#rsa_verify) [`ec_privatekey()`](#ec_privatekey) [`is_ec_privatekey()`](#is_ec_privatekey) [`ed25519_privatekey()`](#ed25519_privatekey) [`is_ed25519_privatekey()`](#is_ed25519_privatekey) [`ed25519_sign()`](#ed25519_sign) [`ed25519_verify()`](#ed25519_verify) [`pkcs7_sign()`](#pkcs7_sign) [`cms_sign()`](#cms_sign) [`cms_verify()`](#cms_verify) [`cms_encrypt()`](#cms_encrypt) [`cms_decrypt()`](#cms_decrypt) [`cms_type()`](#cms_type) [`cms_recipients()`](#cms_recipients) [`random_bytes()`](#random_bytes) [`random_number()`](#random_number) [`crypt()`](#crypt)
* **Data types** [`length()`](#length) [`array()`](#id0) [`boolean()`](#boolean) [`number()`](#number) [`string()`](#string) [`is_array()`](#is_array) [`is_boolean()`](#is_boolean) [`is_function()`](#is_function) [`is_number()`](#is_number) [`is_object()`](#is_object) [`is_string()`](#is_string) [`isset()`](#isset) [`unset()`](#unset) [`Map`](#Map) [`Set`](#Set)
* **Date and time** [`executiontime()`](#executiontime) [`sleep()`](#sleep) [`strftime()`](#strftime) [`strptime()`](#strptime) [`strpduration()`](#strpduration) [`time()`](#time) [`timelocal()`](#timelocal) [`uptime()`](#uptime)
* **DNS** [`dns_query()`](#dns_query) [`domain_includes()`](#domain_includes) [`domain_publicsuffix()`](#domain_publicsuffix) [`idna_encode()`](#idna_encode) [`idna_decode()`](#idna_decode)
* **Encodings and JSON** [`base32_encode()`](#base32_encode) [`base32_decode()`](#base32_decode) [`base64_encode()`](#base64_encode) [`base64_decode()`](#base64_decode) [`base64url_encode()`](#base64url_encode) [`base64url_decode()`](#base64url_decode) [`zlib_compress()`](#zlib_compress) [`zlib_uncompress()`](#zlib_uncompress) [`csv_encode()`](#csv_encode) [`csv_decode()`](#csv_decode) [`json_encode()`](#json_encode) [`json_decode()`](#json_decode) [`url_encode()`](#url_encode) [`url_decode()`](#url_decode) [`mimeword_encode()`](#mimeword_encode) [`mimeword_decode()`](#mimeword_decode)  [`yaml_decode()`](#yaml_decode) [`pack()`](#pack) [`unpack()`](#unpack) [`Iconv`](#Iconv)
* **File and HTTP** [`File`](#File) [`http()`](#http) [`url_parse()`](#url_parse)
* **Mail** [`envelope_address_parse()`](#envelope_address_parse) [`envelope_localpart_escape()`](#envelope_localpart_escape) [`header_addresslist_compile()`](#header_addresslist_compile) [`header_addresslist_extract()`](#header_addresslist_extract) [`header_dkim_decode()`](#header_dkim_decode) [`xtext_encode()`](#xtext_encode) [`xtext_decode()`](#xtext_decode) [`spf_query()`](#spf_query)
* **Mathematical** [`abs()`](#abs) [`ceil()`](#ceil) [`floor()`](#floor) [`log()`](#log) [`pow()`](#pow) [`round()`](#round) [`sqrt()`](#sqrt)
* **MIME** [`MIME`](#MIME) [`MailMessage`](#_CPPv411MailMessage) [`MIMEPart`](#_CPPv48MIMEPart)
* **Misc** [`gethostname()`](#gethostname) [`uuid()`](#uuid) [`uuidv5()`](#uuidv5) [`syslog()`](#syslog) [`inet_includes()`](#inet_includes) [`inet_ntop()`](#inet_ntop) [`inet_pton()`](#inet_pton) [`inet_reverse()`](#inet_reverse) [`Exception`](#_CPPv49Exception)
* **Protocols** [`smtp_lookup_rcpt()`](#smtp_lookup_rcpt) [`smtp_lookup_auth()`](#smtp_lookup_auth)
* **String** [`chr()`](#chr) [`ord()`](#ord) [`str_repeat()`](#str_repeat) [`str_replace()`](#str_replace) [`str_find()`](#str_find) [`str_rfind()`](#str_rfind) [`str_lower()`](#str_lower) [`str_upper()`](#str_upper) [`str_slice()`](#str_slice) [`str_split()`](#str_split) [`str_strip()`](#str_strip) [`str_rstrip()`](#str_rstrip) [`str_lstrip()`](#str_lstrip) [`str_chunk()`](#str_chunk)
* **Regular expression** [`pcre_match()`](#pcre_match) [`pcre_match_all()`](#pcre_match_all) [`pcre_quote()`](#pcre_quote) [`pcre_compile()`](#pcre_compile) [`pcre_replace()`](#pcre_replace)
* **Socket** [`Socket`](#Socket) [`TLSSocket`](#TLSSocket) [`X509`](#X509) [`is_x509_resource()`](#is_x509_resource) [`X509CRL`](#X509CRL) [`is_x509crl_resource()`](#is_x509crl_resource)
* **FFI** [`FFI`](#FFI) [`FFIFunction()`](#FFIFunction) [`FFIType`](#FFIType) [`FFIValue`](#FFIValue)
* **Shared memory** [`memory_add()`](#memory_add) [`memory_dec()`](#memory_dec) [`memory_delete()`](#memory_delete) [`memory_exists()`](#memory_exists) [`memory_fetch()`](#memory_fetch) [`memory_inc()`](#memory_inc) [`memory_store()`](#memory_store) [`memory_update()`](#memory_update)
* **Server** [`server_concurrency()`](#server_concurrency)
* **Queue** [`queue_policy()`](#queue_policy) [`queue_policy_delete()`](#queue_policy_delete) [`queue_suspend()`](#queue_suspend) [`queue_quota()`](#queue_quota)
* **Metrics** [`metrics_increment()`](#metrics_increment) [`metrics_decrement()`](#metrics_decrement) [`metrics_set()`](#metrics_set) [`metrics_get()`](#metrics_get)

<a id="array"></a>

## Array

<a id="array_combine"></a>

### array_combine(keys, values[, default_value])

Create a new array with the keys and values combines into a new array. Duplicate keys are updated.

* **Parameters:**
  * **keys** (*array*) – the array of keys
  * **values** (*array*) – the array of values
  * **default_value** (*any*) – the default value if not enough values for all keys
* **Returns:**
  an array
* **Return type:**
  array

```hsl
array_combine(["a", "b", "c"], [1, 2], 0); // ["a"=>1,"b"=>2,"c"=>0]
array_combine(["a", "b", "a", "c"], [1, 2, 3, 4]); // ["a"=>3,"b"=>2,"c"=>4]
```

<a id="array_every"></a>

### array_every(callback, array)

Returns true if all items in the array are true based on the result of the callback function.

* **Parameters:**
  * **callback** (*function*) – the callback
  * **array** (*array*) – the array
* **Returns:**
  true if all callbacks return true
* **Return type:**
  boolean

The callback function should take one argument (value) and return a boolean value.

```hsl
array_every(function ($x) { return $x % 2 == 0; }, [0, 2, 4, 6]); // true
array_every(function ($x) { return $x % 2 == 0; }, [0, 2, 5, 6]); // false
```

<a id="array_filter"></a>

### array_filter(callback, array[, options])

Returns the filtered items from the array using a callback.

* **Parameters:**
  * **callback** (*function*) – the callback
  * **array** (*array*) – the array
  * **options** (*array*) – options array
* **Returns:**
  array of filtered values, keys are preserved
* **Return type:**
  array

The following options are available in the options array.

> * **keys** (boolean) Find values based on keys. The default is `false`.

The callback function should take one argument (value) and return a boolean value.

```hsl
array_filter(function ($x) { return $x % 2 == 0; }, [0, 1, 2, 3]); // even values
array_filter(is_number, [0, "Hello World", 2]);
```

<a id="array_find"></a>

### array_find(callback, array[, options])

Return the first element that matches in the array. If no element is found `none` is returned.

* **Parameters:**
  * **callback** (*function*) – the callback
  * **array** (*array*) – the array
  * **options** (*array*) – options array
* **Returns:**
  the value if found
* **Return type:**
  any

The following options are available in the options array.

> * **keys** (boolean) Find values based on keys. The default is `false`.

The callback function should take one argument (value) and return a boolean value.

```hsl
array_find(function ($x) { return $x["id"] === 2; }, [["id" => 1, "name" => "a"], ["id" => 2, "name" => "b"]]); // ["id"=>2,"name"=>"b"]
```

<a id="array_includes"></a>

### array_includes(needle, array)

Returns true if needle is found in the array.

* **Parameters:**
  * **needle** (*any*) – the value to match or a callback function
  * **array** (*array*) – the array
* **Returns:**
  true if needle is found
* **Return type:**
  boolean

The callback function should take one argument (value) and return a boolean value. If the needle is not a function, it will be matched using the strict comparison operator (`===`).

```hsl
array_includes(function ($x) { return $x === 2; }, [0, 1, 2, 3]); // true
array_includes(false, [0, none, ""]); // false
```

<a id="array_join"></a>

### array_join(array[, separator])

Join the elements in the array with a separator returning a string

* **Parameters:**
  * **array** (*array*) – the array
  * **separator** (*string*) – the separator
* **Returns:**
  a string from an array
* **Return type:**
  string

> **See also**
> 
> To split a string to an array, see [`str_split()`](#str_split).

<a id="array_keys"></a>

### array_keys(array)

Returns the keys in the array.

* **Parameters:**
  **array** (*array*) – the array
* **Returns:**
  array’s keys
* **Return type:**
  array

<a id="array_map"></a>

### array_map(callback, array)

Returns values from the array with the callback applied.

* **Parameters:**
  * **callback** (*function*) – the callback
  * **array** (*array*) – the array
* **Returns:**
  array of values, keys are preserved
* **Return type:**
  array

The function should take one argument (value) and return a value.

```hsl
array_map(function ($x) { return $x * 2; }, [0, 1, 2, 3]); // double values
```

<a id="array_random"></a>

### array_random(array[, seed])

Returns a random key and value from the array. If the array is empty *none* is returned.

* **Parameters:**
  * **array** (*array*) – the array
  * **seed** (*number*) – a seed used to make the result deterministic
* **Returns:**
  array with key and value
* **Return type:**
  array

The function should take one argument (value) and return a value.

```hsl
array_random(["hello" => "foo", "world" => "bar"]); // ["world", "bar"] // [key, value]
```

<a id="array_range"></a>

### array_range(start, stop[, step = 1])

Returns an array from a numeric range (half-open) with the given steps.

* **Parameters:**
  * **start** (*number*) – the first number
  * **stop** (*number*) – the last number (not included)
  * **step** (*number*) – the step between numbers
* **Returns:**
  an array with numbers
* **Return type:**
  array

```hsl
foreach (array_range(0, 9) as $i) // 0,1,2,..,8
        echo $i;
```

<a id="array_reduce"></a>

### array_reduce(callback, array[, initial])

Reduces the values in the array using the callback from left-to-right, optionally starting with a initial value.

* **Parameters:**
  * **callback** (*function*) – the callback
  * **array** (*array*) – the array
  * **initial** (*any*) – the initial value
* **Returns:**
  a single value
* **Return type:**
  any

The function should take two arguments (carry and value) and return a value.

If no initial value is provided and;

> * the array is empty, an error will be raised.
> * the array contains one value, that value will be returned.

```hsl
array_reduce(function ($carry, $x) { return $carry + $x; }, [0, 1, 2, 3]); // sum values
```

<a id="array_reverse"></a>

### array_reverse(array)

Return array in reverse order. Numeric keys are reindexed.

* **Parameters:**
  **array** (*array*) – the array
* **Returns:**
  array in reverse order
* **Return type:**
  array

<a id="array_sort"></a>

### array_sort(callback, array[, options])

Returns the array sorted (with index association maintained) using the callback function to determine the order. The sort is not guaranteed to be stable.

* **Parameters:**
  * **callback** (*function*) – the callback
  * **array** (*array*) – the array
  * **options** (*array*) – options array
* **Returns:**
  a sorted array
* **Return type:**
  array

The following options are available in the options array.

> * **keys** (boolean) Sort the array based on their keys. The default is `false`.

The callback function should take two arguments (a and b) and return true if a is less-than b.

```hsl
array_sort(function ($a, $b) { return $a < $b; }, [2, 3, 1]); // sort
array_sort(function ($a, $b) { return $a > $b; }, [2, 3, 1]); // reverse-sort
```

> **Note**
> 
> Some other languages (eg. javascript and PHP) use a trivalue function (-1, 0, 1) in a similar way in order to determine the order. HSL does not since if needed, a trivalue function may be simulated internally using the provided less-than function. Further some sorting implementation may only need the less-than result hence the greater-than and equality result may be superfluous to establish.
> 
> > ```hsl
> > function trivalue($a, $b, $lessthan)
> > {
> >       if ($lessthan($a, $b)) return -1;
> >       if ($lessthan($b, $a)) return 1;
> >       return 0;
> > }
> > ```

<a id="array_shuffle"></a>

### array_shuffle(array[, seed])

Return array in shuffled order. Numeric keys are reindexed.

* **Parameters:**
  * **array** (*array*) – the array
  * **seed** (*number*) – a seed used to make the result deterministic
* **Returns:**
  array in shuffled order
* **Return type:**
  array
  ```hsl
  $array = array_shuffle($array, hash("hello world"));
  ```

<a id="array_unique"></a>

### array_unique(array)

Return an array with unique values (the first key is preserved).

* **Parameters:**
  **array** (*array*) – the array
* **Returns:**
  array with unique values
* **Return type:**
  array

<a id="cryptographic"></a>

## Cryptographic

<a id="aes_decrypt"></a>

### aes_decrypt(message, key, mode[, options])

Decrypt a message using AES. On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to decrypt
  * **key** (*string*) – the key as raw bytes (no padding is done)
  * **mode** (*string*) – the block cipher mode of operation (`ecb` or `cbc`)
  * **options** (*array*) – options array
* **Returns:**
  the message decrypted
* **Return type:**
  string or none

The following options are available in the options array.

> * **iv** (string) The initialization vector as bytes (16 bytes for `cbc`).
> * **padding** (boolean) Use PKCS7 padding. The default is `true`.

> **Note**
> 
> The key length must be either 16 bytes for AES-128, 24 bytes for AES-192 or 32 bytes for AES-256. No NUL bytes padding nor truncation is done on either the key or iv. The example below shows how to do manual padding.
> 
> ```hsl
> $message = aes_decrypt(
>                         $encrypted,
>                         pack("a32", "short aes-256 key"),
>                         "cbc",
>                         ["iv" => pack("x16")]
>                 );
> ```

<a id="aes_encrypt"></a>

### aes_encrypt(message, key, mode[, options])

Encrypt a message using AES. On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to encrypt
  * **key** (*string*) – the key as raw bytes (no padding is done)
  * **mode** (*string*) – the block cipher mode of operation (`ecb` or `cbc`)
  * **options** (*array*) – options array
* **Returns:**
  the message encrypted
* **Return type:**
  string or none

The following options are available in the options array.

> * **iv** (string) The initialization vector as bytes (16 bytes for `cbc`).
> * **padding** (boolean) Use PKCS7 padding. The default is `true`.

> **Note**
> 
> The key length must be either 16 bytes for AES-128, 24 bytes for AES-192 or 32 bytes for AES-256. No NUL bytes padding nor truncation is done on either the key or iv. The example below shows how to do manual padding.
> 
> ```hsl
> $encrypted = aes_encrypt(
>                         $message,
>                         pack("a32", "short aes-256 key"),
>                         "cbc",
>                         ["iv" => pack("x16")]
>                 );
> ```

<a id="hmac_md5"></a>

### hmac_md5(key, message[, options])

Return the HMAC MD5 hash of message with the key.

* **Parameters:**
  * **key** (*string*) – the HMAC key
  * **message** (*string*) – the value to hash
  * **options** (*array*) – options array
* **Returns:**
  the hash value hex encoded
* **Return type:**
  string

The following options are available in the options array.

> * **binary** (boolean) Return binary instead of hex format. The default is `false`.

<a id="hmac_sha1"></a>

### hmac_sha1(key, message[, options])

Return the HMAC SHA1 hash of message with the key.

* **Parameters:**
  * **key** (*string*) – the HMAC key
  * **message** (*string*) – the value to hash
  * **options** (*array*) – options array
* **Returns:**
  the hash value hex encoded
* **Return type:**
  string

The following options are available in the options array.

> * **binary** (boolean) Return binary instead of hex format. The default is `false`.

<a id="hmac_sha2"></a>

### hmac_sha2(key, message, hashsize[, options])

Return the HMAC SHA2 hash of message with the key.

* **Parameters:**
  * **key** (*string*) – the HMAC key
  * **message** (*string*) – the value to hash
  * **hashsize** (*number*) – the hash size (must be 256 or 512)
  * **options** (*array*) – options array
* **Returns:**
  the hash value hex encoded
* **Return type:**
  string

The following options are available in the options array.

> * **binary** (boolean) Return binary instead of hex format. The default is `false`.

<a id="md5"></a>

### md5(message[, options])

Return the MD5 hash of message.

* **Parameters:**
  * **message** (*string*) – the value to hash
  * **options** (*array*) – options array
* **Returns:**
  the hash value hex encoded
* **Return type:**
  string

The following options are available in the options array.

> * **binary** (boolean) Return binary instead of hex format. The default is `false`.

<a id="sha1"></a>

### sha1(message[, options])

Return the SHA1 hash of message.

* **Parameters:**
  * **message** (*string*) – the value to hash
  * **options** (*array*) – options array
* **Returns:**
  the hash value hex encoded
* **Return type:**
  string

The following options are available in the options array.

> * **binary** (boolean) Return binary instead of hex format. The default is `false`.

<a id="sha2"></a>

### sha2(message, hashsize[, options])

Return the SHA2 hash of message.

* **Parameters:**
  * **message** (*string*) – the value to hash
  * **hashsize** (*number*) – the hash size (must be 256 or 512)
  * **options** (*array*) – options array
* **Returns:**
  the hash value hex encoded
* **Return type:**
  string

The following options are available in the options array.

> * **binary** (boolean) Return binary instead of hex format. The default is `false`.

<a id="hash"></a>

### hash(message)

Return the numeric hash value of the message. The hash value is same for equal messages.

* **Parameters:**
  **message** (*string*) – the value to hash
* **Returns:**
  the hash value
* **Return type:**
  number

<a id="pkcs11_load"></a>

### pkcs11_load(uri)

Return an array of fetched resources types of (PrivateKey’s, X509 and X509CRL). Only URI starting with *pkcs11:* are supported.

* **Parameters:**
  **uri** (*string*) – the pkcs11 uri
* **Returns:**
  resources
* **Return type:**
  an array of resources

<a id="rsa_privatekey"></a>

### rsa_privatekey(privatekey[, options])

Return a RSA privatekey resource from a PEM certificate (`--- BEGIN PRIVATE KEY ---`). On error `none` is returned.

* **Parameters:**
  * **privatekey** (*string*) – the private key in PEM format
  * **options** (*array*) – options array
* **Returns:**
  the privatekey
* **Return type:**
  RSAPrivateKey resource or none

The following options are available in the options array.

> * **password** (string) The password used to decrypt an encrypted key.

<a id="is_rsa_privatekey"></a>

### is_rsa_privatekey(privatekey)

Return a true if privatekey is a RSA privatekey resource.

* **Parameters:**
  **privatekey** (*any*) – the privatekey
* **Returns:**
  if the argument is a privatekey
* **Return type:**
  boolean

<a id="rsa_sign"></a>

### rsa_sign(message, privatekey[, options])

RSA sign a message digest using a hash function. On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to sign
  * **privatekey** (*RSAPrivateKey* *or* *string*) – the private key resource or string
  * **options** (*array*) – options array
* **Returns:**
  the message signature
* **Return type:**
  string or none

The following options are available in the options array.

> * **hash** (string) The hash method to use (`md5`, `sha1`, `sha256` or `sha512`). The default is `sha256`.
> * **format** (string) The private key format to use `PrivateKeyInfo` (PKCS#8) or `RSAPrivateKey`. The default is `RSAPrivateKey`.
> * **pem** (boolean) If the private key is in PEM format or raw bytes. The default is `false`.
> * **id** (boolean) If the private key is given as an id of an RSA key in the configuration. The default is `false`.

<a id="rsa_verify"></a>

### rsa_verify(message, signature, publickey[, options])

RSA verify a message digest using a hash function. On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to verify
  * **signature** (*string*) – the signature for the message as raw bytes
  * **publickey** (*string*) – the public key
  * **options** (*array*) – options array
* **Returns:**
  if the signature verifies
* **Return type:**
  boolean or none

The following options are available in the options array.

> * **hash** (string) The hash method to use (`md5`, `sha1`, `sha256` or `sha512`). The default is `sha256`.
> * **format** (string) The public key format to use `SubjectPublicKeyInfo` or `RSAPublicKey`. The default is `RSAPublicKey`.
> * **pem** (boolean) If the public key is in PEM format or raw bytes. The default is `false`.
> * **id** (boolean) If the public key is given as an id of an RSA key in the configuration. The default is `false`.

<a id="ec_privatekey"></a>

### ec_privatekey(privatekey[, options])

Return a EC privatekey resource from a PEM certificate (`--- BEGIN PRIVATE KEY ---`). On error `none` is returned.

* **Parameters:**
  * **privatekey** (*string*) – the private key in PEM format
  * **options** (*array*) – options array
* **Returns:**
  the privatekey
* **Return type:**
  ECPrivateKey resource or none

The following options are available in the options array.

> * **password** (string) The password used to decrypt an encrypted key.

<a id="is_ec_privatekey"></a>

### is_ec_privatekey(privatekey)

Return a true if privatekey is a EC privatekey resource.

* **Parameters:**
  **privatekey** (*any*) – the privatekey
* **Returns:**
  if the argument is a privatekey
* **Return type:**
  boolean

<a id="ed25519_privatekey"></a>

### ed25519_privatekey(privatekey[, options])

Return a ED25519 privatekey resource from a PEM certificate (`--- BEGIN PRIVATE KEY ---`). On error `none` is returned.

* **Parameters:**
  * **privatekey** (*string*) – the private key in PEM format
  * **options** (*array*) – options array
* **Returns:**
  the privatekey
* **Return type:**
  ED25519PrivateKey resource or none

The following options are available in the options array.

> * **password** (string) The password used to decrypt an encrypted key.

<a id="is_ed25519_privatekey"></a>

### is_ed25519_privatekey(privatekey)

Return a true if privatekey is a ED25519 privatekey resource.

* **Parameters:**
  **privatekey** (*any*) – the privatekey
* **Returns:**
  if the argument is a privatekey
* **Return type:**
  boolean

<a id="ed25519_sign"></a>

### ed25519_sign(message, privatekey)

ED25519 sign a message. On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to sign
  * **privatekey** (*ED25519PrivateKey* *or* *string*) – the private key resource or string (as raw bytes)
* **Returns:**
  the message signature
* **Return type:**
  string or none

<a id="ed25519_verify"></a>

### ed25519_verify(message, signature, publickey)

ED25519 verify a message. On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to verify
  * **signature** (*string*) – the signature as raw bytes
  * **publickey** (*string*) – the public key as raw bytes
* **Returns:**
  if the signature verifies
* **Return type:**
  boolean or none

<a id="pkcs7_sign"></a>

### pkcs7_sign(message, certificate[, options])

PKCS7 sign (S/MIME) a message. If certificate is given as an associative array it should
include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*.
If certificate is given as a string it should either be an `id` or a PEM encoded string with a x509 certificate, a chain and a privatekey.
On error `none` is returned.

* **Parameters:**
  * **message** (*string*) – the message to sign
  * **certificate** (*array* *or* *string*) – the certificate and privatekey to use
  * **options** (*array*) – options array
* **Returns:**
  the message signature
* **Return type:**
  string or none

The following options are available in the options array.

> * **id** (boolean) If a certificate argument is given as an string, use this to indicate a id of a certificate in the configuration. The default is `false`.
> * **detached** (boolean) If the signature should be detached (not include the message itself). The default is `true`.

If the certificate argument contains multiple certificates (intermediates) they will be included in the signature as well.

<a id="cms_sign"></a>

### cms_sign(message, certificate[, options])

CMS sign (S/MIME) a message. If certificate is given as an associative array it should
include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*.
If certificate is given as a string it should either be an `id` or a PEM encoded string with a x509 certificate, a chain and a privatekey.

It will return an associative array with an `result` (boolean). If false, an `error` (string) is set.
If true, data is returned the `data` (string).

* **Parameters:**
  * **message** (*string*) – the message to sign
  * **certificate** (*array* *or* *string*) – the certificate and privatekey to use
  * **options** (*array*) – options array
* **Returns:**
  the result
* **Return type:**
  array

The following options are available in the options array.

> * **id** (boolean) If a certificate argument is given as an string, use this to indicate a id of a certificate in the configuration. The default is `false`.
> * **detached** (boolean) If the signature should be detached (not include the message itself). The default is `true`.
> * **noattr** (boolean) Control the CMS_NOATTR. The default is `false`.
> * **binary** (boolean) Control the CMS_BINARY. The default is `true`.
> * **nosmimecap** (boolean) Control the CMS_NOSMIMECAP. The default is `false`.
> * **usekeyid** (boolean) Control the CMS_USE_KEYID. The default is `false`.
> * **digest** (string) This can be `sha256` or `sha512`. The default is `sha256`.

If the certificate argument contains multiple certificates (intermediates) they will be included in the signature as well.

<a id="cms_verify"></a>

### cms_verify(signature, message, certificates[, options])

CMS verify (S/MIME) a message. The certificate should be given as an associative array and must
include an array of `certs` (*X509Resource*) and/or an array of `store` (*X509Resource*).

It will return an associative array with an `result` (boolean). If false, an `error` (string) is set and if possible an array of `certs` (X509Resource).
If true, an array of `signers` (X509Resource), an array of `certs` (X509Resource), if data is returned the `data` (string) and a `cms` classification
if the data is enclosed in another cms object (one of `data`, `signed`, `digest`, `compressed`, `encrypted`, `enveloped`, `unknown`).

* **Parameters:**
  * **signature** (*string*) – the signature to verify
  * **message** (*string* *or* *none*) – the message to verify (may be `none` for nondetached)
  * **certificates** (*array*) – the certificates to use to verify
  * **options** (*array*) – options array
* **Returns:**
  the result
* **Return type:**
  array

The following options are available in the options array.

> * **detached** (boolean) If the signature should be detached (not include the message itself). The default is `true`.
> * **data** (boolean) If the signature data should be return. The default is `true`.
> * **nointern** (boolean) When verifying a message normally certificates (if any) included in the message are searched for the signing certificate. The default is `false`.

<a id="cms_encrypt"></a>

### cms_encrypt(message, certificates[, options])

CMS encrypt (S/MIME) a message. The certificate should be given as an associative array and must
include an array of `certs` (*X509Resource*).

It will return an associative array with an `result` (boolean). If false, an `error` (string) is set.
If true, data is returned the `data` (string).

* **Parameters:**
  * **message** (*string*) – the signature to encrypt
  * **certificates** (*array*) – the certificate to use to encrypt the message
  * **options** (*array*) – options array
* **Returns:**
  the result
* **Return type:**
  array

The following options are available in the options array.

> * **cipher** (string) This can be `des-ede3-cbc` or `aes-256-cbc`. The default is `des-ede3-cbc`.
> * **usekeyid** (boolean) Control the CMS_USE_KEYID. The default is `false`.

<a id="cms_decrypt"></a>

### cms_decrypt(message, certificate[, options])

CMS decrypt (S/MIME) a message. If certificate is given as an associative array it should
include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`).
If certificate is given as a string it should either be an `id` or a PEM encoded string with a x509 certificate and a privatekey.

It will return an associative array with an `result` (boolean). If false, an `error` (string) is set.
If true, data is returned the `data` (string) and a `cms` classification
if the data is enclosed in another cms object (one of `data`, `signed`, `digest`, `compressed`, `encrypted`, `enveloped`, `unknown`).

* **Parameters:**
  * **message** (*string*) – the message to decrypt
  * **certificate** (*array*) – the certificate and privatekey to use
  * **options** (*array*) – options array
* **Returns:**
  the result
* **Return type:**
  array

The following options are available in the options array.

> * **id** (boolean) If a certificate argument is given as an string, use this to indicate a id of a certificate in the configuration. The default is `false`.

<a id="cms_type"></a>

### cms_type(message)

Get the CMS type of a message, eg. if it is `pkcs7-signedData` (signed) or `pkcs7-envelopedData` (encrypted) as return by OpenSSL `CMS_get0_type()` encoded with `OBJ_obj2txt()`.

* **Parameters:**
  **message** (*string*) – the message to check
* **Returns:**
  the message type
* **Return type:**
  string or none

<a id="cms_recipients"></a>

### cms_recipients(message)

Get recipients information from a S/MIME encrypted message. This can be used to determine which certificate to use for decryption.

It will return an associative array with either `keyid` (string) or `serial_number` (string) and `issuer` (array).
On error `none` is returned.

* **Parameters:**
  **message** (*string*) – the message to get recipients information from
* **Returns:**
  the recipients information
* **Return type:**
  array or none

<a id="random_bytes"></a>

### random_bytes(bytes)

Return a string of random bytes (at most 1MiB).

* **Parameters:**
  **bytes** (*number*) – number of bytes to return
* **Returns:**
  random bytes
* **Return type:**
  string

<a id="random_number"></a>

### random_number([first, last[, seed]])

Return a random integer between first and last (inclusive) or a random double (decimal) between 0 and 1 (inclusive).

* **Parameters:**
  * **first** (*number*) – first possible number
  * **last** (*number*) – last possible number
  * **seed** (*number*) – a seed used to make the result deterministic
* **Returns:**
  the random number
* **Return type:**
  number

<a id="crypt"></a>

### crypt(key, salt)

Uses the underlying operating system’s `crypt()` function.

* **Parameters:**
  * **key** (*string*) – the user’s typed password
  * **salt** (*string*) – the salt
* **Returns:**
  the encrypted string
* **Return type:**
  string

```hsl
if (crypt($password, $encryptedpassword) === $encryptedpassword)
  echo "match";
```

<a id="data-types"></a>

## Data types

<a id="length"></a>

### length(value)

Return the length of an array (items) or a string (characters). For all other datatypes *none* is returned.

* **Parameters:**
  **value** (*any*) – the value
* **Returns:**
  the length
* **Return type:**
  number or none

<a id="id0"></a>

### array([...args])

This function creates an array.

* **Parameters:**
  **...****args** (*any*) – the input
* **Returns:**
  an array
* **Return type:**
  array

> **Note**
> 
> *array* is not a function, it’s a language construct to create an [array](literals.html.md#arraytype) type. It’s an alias for the short array syntax `[]`.

<a id="boolean"></a>

### boolean(value)

This function converts the input of value to the boolean type (according to the [truthiness](operators.html.md#truthtable)) table.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  a boolean
* **Return type:**
  boolean

<a id="number"></a>

### number(value)

This function converts the input of value to the number type. Decimal and hexadecimal (*Ox*) numbers are supported. If the input contains an invalid number as string or type `0` is returned.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  a number
* **Return type:**
  number

<a id="string"></a>

### string(value)

This function converts the input of value to the string type, hence converting it to its string representation.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  a string
* **Return type:**
  string

<a id="is_array"></a>

### is_array(value)

Returns true if the type of value is an array.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="is_boolean"></a>

### is_boolean(value)

Returns true if the type of value is a boolean.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="is_function"></a>

### is_function(value)

Returns true if the type of value is a function.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="is_number"></a>

### is_number(value)

Returns true if the type of value is a number.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="is_object"></a>

### is_object(value)

Returns true if the type of value is an object.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="is_string"></a>

### is_string(value)

Returns true if the type of value is a string.

* **Parameters:**
  **value** (*any*) – the input
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="isset"></a>

### isset(x)

Returns true if the variable is defined.

> > **Note**
> > 
> > This is not a regular function. It’s a language construct and will only accept variables as input.

* **Parameters:**
  **x** (*variable*) – a variable
* **Returns:**
  the result
* **Return type:**
  boolean

<a id="unset"></a>

### unset(x)

Unsets the variable or array index or slice of x, it return true if the variable or array index was defined.

> > **Note**
> > 
> > This is not a regular function. It’s a language construct and will only accept variables as input.

* **Parameters:**
  **x** (*variable*) – a variable
* **Returns:**
  if x was unset
* **Return type:**
  boolean

<a id="Map"></a>

### *class* Map

The Map class maps keys to values. Keys are unique and may only point to a single value.
This map is strongly-typed, meaning you have to define which data types you intend to store in it.
There is a limited number of key types, but they are optimized for performance.
As for value you may choose to use the *any* type to support all data types and also mixed in the map,
but it is more memory efficent to use a specific type.

<a id="Map.constructor"></a>

#### constructor(keytype, valuetype)

Create a Map with the following data types.

* **Parameters:**
  * **keytype** (*string*) – the key type
  * **valuetype** (*string*) – the value type

The following key types are available.

* `string`
* `uint32`, `sint32`

The following value types are available.

* `string`
* `uint32`, `sint32`
* `double`
* `boolean`
* `any` (holds any value)

```hsl
$map = Map("string", "uint32");
$map->set("foo", 123);
```

> **Warning**
> 
> If the `Map` is shared between concurrent script executions (eg. using `import` or `cache`) do *not* modify (`set`, `delete` et.c.) the object as those operations are not thread-safe.

<a id="Map.set"></a>

#### set(key, value)

Add or update the key with the value.

* **Parameters:**
  * **key** (*string*) – the key
  * **value** (*string*) – the value
* **Returns:**
  if the element was created (true) or overwritten (false)
* **Return type:**
  boolean

<a id="Map.has"></a>

#### has(key)

Check if the key exists.

* **Parameters:**
  **key** (*string*) – the key
* **Returns:**
  if the key exists
* **Return type:**
  boolean

<a id="Map.get"></a>

#### get(key)

Get the value of key or `none` if it doesn’t exists.

* **Parameters:**
  **key** (*string*) – the key
* **Returns:**
  the value of key or `none`
* **Return type:**
  any

<a id="Map.delete"></a>

#### delete(key)

Delete the key from the map.

* **Parameters:**
  **key** (*string*) – the key
* **Returns:**
  if the key existed before the remove
* **Return type:**
  boolean

<a id="Map.merge"></a>

#### merge(key, value)

Merge key values in-place using the (+ operator). This can be used to add items to arrays or increment numbers.

* **Parameters:**
  * **key** (*string*) – the key
  * **value** (*string*) – the value
* **Returns:**
  if the key existed before the merge
* **Return type:**
  boolean

<a id="Map.size"></a>

#### size()

Get number of keys in the map.

* **Returns:**
  keys in map
* **Return type:**
  number

<a id="Map.clear"></a>

#### clear()

Delete all keys in the map.

* **Return type:**
  none

<a id="Map.toArray"></a>

#### toArray()

Convert the Map into an array.

* **Returns:**
  the values as an array
* **Return type:**
  array

<a id="Map.entries"></a>

#### entries()

Iterator to all keys and values in the map in no specific order.
The iterators value will be an array containg the `[0=>key, 1=>value]`.
If iterating the map with foreach, the key and value will be mapped accordingly.

* **Return type:**
  [`Iterator`](literals.html.md#Iterator)

```hsl
$map = Map("string", "uint32");
$map->set("foo", 123);
$map->set("bar", 456);

$it = $map->entries();
echo $it->next(); // ["done"=>false,"value"=>[0=>"bar",1=>456]]
echo $it->next(); // ["done"=>false,"value"=>[0=>"foo",1=>123]]
echo $it->next(); // ["done"=>true,"value"=>]

foreach ($map->entries() as $k => $v)
  echo "$k = $v";
// bar = 456
// foo = 123
```

<a id="Set"></a>

### *class* Set

The Set class holds keys in a unique collection.
This set is strongly-typed, meaning you have to define which data types you intend to store in it.
There is a limited number of key types, but they are optimized for performance.

<a id="Set.constructor"></a>

#### constructor(keytype)

Create a Set with the following data type.

* **Parameters:**
  **keytype** (*string*) – the key type

The following key types are available.

* `string`
* `uint32`, `sint32`

```hsl
$set = Set("string");
$set->add("foo");
```

> **Warning**
> 
> If the `Set` is shared between concurrent script executions (eg. using `import` or `cache`) do *not* modify (`add`, `delete` et.c.) that object as those operations are not thread-safe.

<a id="Set.add"></a>

#### add(key)

Add the key to the set.

* **Parameters:**
  **key** (*string*) – the key
* **Returns:**
  if the key was added (true) or not (false)
* **Return type:**
  boolean

<a id="Set.has"></a>

#### has(key)

Check if the key exists.

* **Parameters:**
  **key** (*string*) – the key
* **Returns:**
  if the key exists
* **Return type:**
  boolean

<a id="Set.delete"></a>

#### delete(key)

Delete the key from the set.

* **Parameters:**
  **key** (*string*) – the key
* **Returns:**
  if the key existed before the remove
* **Return type:**
  boolean

<a id="Set.size"></a>

#### size()

Get number of keys in the set.

* **Returns:**
  keys in set
* **Return type:**
  number

<a id="Set.clear"></a>

#### clear()

Delete all keys in the set.

* **Return type:**
  none

<a id="Set.toArray"></a>

#### toArray([options])

Convert the Set into an array.

* **Parameters:**
  **options** (*array*) – options array
* **Returns:**
  the values as an array
* **Return type:**
  array

The following options are available in the options array.

* **keys** (boolean) Set values as keys. The default is `false`.

<a id="Set.values"></a>

#### values()

Iterator to all keys in the set in no specific order.
If iterating the set with foreach, the key (in the set) will be mapped to the value in the foreach statement.

* **Return type:**
  [`Iterator`](literals.html.md#Iterator)

```hsl
$set = Set("string");
$set->add("foo");
$set->add("bar");

$it = $set->values();
echo $it->next(); // ["done"=>false,"value"=>"bar"]
echo $it->next(); // ["done"=>false,"value"=>"foo"]
echo $it->next(); // ["done"=>true,"value"=>]

foreach ($set->values() as $v)
  echo "$v";
// bar
// foo
```

<a id="date-and-time"></a>

## Date and time

<a id="executiontime"></a>

### executiontime()

Return the elapsed time since the beginning of the code execution.

* **Returns:**
  the time in seconds (with decimals)
* **Return type:**
  number

<a id="sleep"></a>

### sleep(seconds)

Pause the code execution for x seconds.

* **Parameters:**
  **seconds** (*number*) – the number of seconds to sleep
* **Returns:**
  the time slept in seconds (with decimals)
* **Return type:**
  number

> **Note**
> 
> This function will suspend the current script execution while sleeping allowing for cooperative multitasking.

<a id="strftime"></a>

### strftime(format[, time][, options])

Format according to the [strftime](https://man7.org/linux/man-pages/man3/strftime.3.html) manual.

* **Parameters:**
  * **format** (*string*) – the format string
  * **time** (*number*) – the default is current time without timezone
  * **options** (*array*) – options array
* **Returns:**
  the time formatted (max length 100)
* **Return type:**
  string

The following options are available in the options array.

* **local** (boolean) Expect the time to be in the current local timezone. The default is `true`.

```hsl
echo strftime("%H:%M:%S"); // prints current time eg "13:58:38"
```

<a id="strptime"></a>

### strptime(datestring, format[, options])

Parse a date string according to the [strptime](https://man7.org/linux/man-pages/man3/strptime.3.html) manual with the time without timezone.

* **Parameters:**
  * **datestring** (*string*) – the date string
  * **format** (*string*) – the format string
  * **options** (*array*) – options array
* **Returns:**
  the time in seconds
* **Return type:**
  number

The following options are available in the options array.

* **local** (boolean) Expect the time to be in the current local timezone. The default is `true`.

```hsl
echo strptime("13:58:38", "%H:%M:%S"); // prints time of today at "13:58:38"
```

<a id="strpduration"></a>

### strpduration(during)

Parse a string formated as a duration. Supported time periods are *d* (days) *h* (hours), *m* (minutes) and *s* (seconds).
On error `none` is returned.

* **Parameters:**
  **during** (*string*) – the during string
* **Returns:**
  the time in seconds
* **Return type:**
  number

```hsl
echo strpduration("1h3s"); // 3603
echo strpduration("1d"); // 86400
echo strpduration("3600"); // 3600
```

<a id="time"></a>

### time()

Return elapsed seconds (unix time) since 1970-01-01T00:00:00Z without timezone.

* **Returns:**
  the time in seconds (with decimals)
* **Return type:**
  number

<a id="timelocal"></a>

### timelocal()

Return elapsed seconds (unix time) since 1970-01-01T00:00:00Z with timezone.

* **Returns:**
  the time in seconds (with decimals)
* **Return type:**
  number

<a id="uptime"></a>

### uptime()

Return the monotonic time since system boot. Monotonic time is by definition suitable for relative time keeping, in contrast to [`time()`](#time). If you want to obtain the script execution time use [`executiontime()`](#executiontime).

* **Returns:**
  the time in seconds (with decimals)
* **Return type:**
  number

<a id="dns"></a>

## DNS

<a id="dns_query"></a>

### dns_query(host[, options])

Query for DNS records of a hostname.

* **Parameters:**
  * **host** (*string*) – the host
  * **options** (*array*) – options array
* **Returns:**
  the result
* **Return type:**
  array

The following options are available in the options array.

* **type** (string or number) Query type (one of `a`, `aaaa`, `mx`, `txt`, `cname`, `ns`, `ptr`, `srv`, `soa` or a RR type as number). The default is to query for `a` records.
* **extended_result** (boolean) Get an extended result with more RR information. Must be used with numeric RR types. The default is `false`.

An array with either `result` or `error` in set in an associative array. `dnssec` is always included. `result` is the list of results (addresses, hostnames or strings) and `error` is the string representation of *rcode* or *h_errno*.

If `extended_result` is `true`, more information will be available in the result array for each record.

| Type    | Fields                                                                             |
|---------|------------------------------------------------------------------------------------|
| `a`     | `type`, `ttl`, `address`                                                           |
| `aaaa`  | `type`, `ttl`, `address`                                                           |
| `mx`    | `type`, `ttl`, `preference`, `exchange`                                            |
| `txt`   | `type`, `ttl`, `string`                                                            |
| `cname` | `type`, `ttl`, `target`                                                            |
| `ns`    | `type`, `ttl`, `target`                                                            |
| `ptr`   | `type`, `ttl`, `target`                                                            |
| `srv`   | `type`, `ttl`, `priority`, `weight`, `port`, `target`                              |
| `soa`   | `type`, `ttl`, `mname`, `rname`, `serial`, `refresh`, `retry`, `expire`, `minimum` |
| number  | `type`, `ttl`, `data`                                                              |

```hsl
echo dns_query("nxdomain.halon.se");
// ["error"=>"NXDOMAIN","dnssec"=>false]

echo dns_query("halon.se");
// ["result"=>[0=>"54.152.237.238"],"dnssec"=>false]

echo dns_query(inet_reverse("8.8.8.8"), ["type" => "ptr", "extended_result" => true]);
// ["result"=>[0=>["type"=>"ptr","ttl"=>5,"target"=>"dns.google"]],"dnssec"=>false]

// DNSBL example
echo dns_query(inet_reverse("12.34.56.78", "dnsbl.example.com"));
// ["result"=>[0=>"127.0.0.1"],"dnssec"=>false]

// TLSA example
echo unpack("cccH*", dns_query("_25._tcp.mx.halon.io", ["type" => 52, "extended_result" => true])["result"][0]["data"]);
// [0=>3,1=>1,2=>1,3=>"42568063726264388f17d494cd3d01079ba1df4e60b1448e5670544cd7739218"]
```

> **Note**
> 
> This function will suspend the current script execution while waiting for DNS responses allowing for cooperative multitasking.

<a id="domain_includes"></a>

### domain_includes(subdomain, domain[, options])

Test if subdomain is a subdomain of domain. If the domain starts with a dot `.` it must be a subdomain of domain, hence it will **not** even if *subdomain == domain*.

* **Parameters:**
  * **subdomain** (*string*) – the subdomain
  * **domain** (*string*) – the domain
  * **options** (*array*) – options array
* **Returns:**
  if subdomain is a subdomain of domain
* **Return type:**
  boolean

The following options are available in the options array.

* **depth** (number) The maximum allowed depth of the subdomains. The default is no limit.

```hsl
domain_includes("www.halon.io", "halon.io"); // true
domain_includes("halon.io", "halon.io"); // true
domain_includes("www.halon.io", ".halon.io"); // true
domain_includes("halon.io", ".halon.io"); // false
domain_includes("test.www.halon.io", ".halon.io", ["depth" => 1]); // false
```

<a id="domain_publicsuffix"></a>

### domain_publicsuffix(domain)

Return the public suffix ([https://publicsuffix.org/](https://publicsuffix.org/)) of a domain name. If not a valid TLD (none is returned).

* **Parameters:**
  **domain** (*string*) – the domain
* **Returns:**
  the public suffix
* **Return type:**
  string or none

```hsl
domain_publicsuffix("www.halon.io"); // "io"
domain_publicsuffix("www.google.co.uk"); // "co.uk"
domain_publicsuffix("example.badtld"); // none
```

<a id="idna_encode"></a>

### idna_encode(domain)

IDNA encode a domain (to punycode). On error `none` is returned.

* **Parameters:**
  **domain** (*string*) – a unicode domain
* **Returns:**
  the punycode (ASCII) domain
* **Return type:**
  string or none

```hsl
echo idna_encode("fußball.example"); // xn--fuball-cta.example
```

<a id="idna_decode"></a>

### idna_decode(domain)

IDNA decode a domain (to unicode). On error `none` is returned.

* **Parameters:**
  **domain** (*string*) – a punycode (ASCII) domain
* **Returns:**
  the unicode domain
* **Return type:**
  string or none

```hsl
echo idna_decode("xn--fuball-cta.example"); // fußball.example
```

<a id="encodings-and-json"></a>

## Encodings and JSON

<a id="base32_encode"></a>

### base32_encode(string[, options])

Base32 encode the string (RFC 4648).

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the base32 representation
* **Return type:**
  string

The following options are available in the options array.

> * **padding** (boolean) Use padding. The default is `true`.

<a id="base32_decode"></a>

### base32_decode(string)

Base32 decode the string (RFC 4648).

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string representation
* **Return type:**
  string

<a id="base64_encode"></a>

### base64_encode(string)

Base64 encode the string.

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the base64 representation
* **Return type:**
  string

<a id="base64_decode"></a>

### base64_decode(string)

Base64 decode the string.

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string representation
* **Return type:**
  string

<a id="base64url_encode"></a>

### base64url_encode(string)

Base64 URL encode the string.

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the base64 url representation
* **Return type:**
  string

<a id="base64url_decode"></a>

### base64url_decode(string)

Base64 URL decode the string.

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string representation
* **Return type:**
  string

<a id="zlib_compress"></a>

### zlib_compress(string[, compression[, windowbits]])

Compress the string unsing zlib compression.

* **Parameters:**
  * **string** (*string*) – the input string
  * **compression** (*number*) – the compression level (default 9)
  * **windowbits** (*number*) – the window bits (default 15)
* **Returns:**
  the compressed string
* **Return type:**
  string

<a id="zlib_uncompress"></a>

### zlib_uncompress(string[, windowbits])

Decompress the string using zlib.

* **Parameters:**
  * **string** (*string*) – the input string
  * **windowbits** (*number*) – the window bits (default 15)
* **Returns:**
  the uncompressed string
* **Return type:**
  string

<a id="csv_encode"></a>

### csv_encode(values[, options])

Encode an array of strings as CSV encoded data. Multiline CSV data is supported.

* **Parameters:**
  * **values** (*array*) – strings to encode
  * **options** (*array*) – options array
* **Returns:**
  the CSV representation
* **Return type:**
  string or none

The following options are available in the options array.

> * **delimiter** (string) The format separator. The default is `,`.
> * **escape** (string) Additional escape character (causing double quotes). The default is `"\r\n` and the delimiter.

```hsl
echo csv_encode(["Hello", "World", "Hello World"], ["escape" => " "]);
// Hello,World,"Hello World"
```

<a id="csv_decode"></a>

### csv_decode(string[, options])

Parse CSV data as string. Multiline CSV data is supported. On error `none` is returned.

* **Parameters:**
  * **string** (*string*) – CSV formated string
  * **options** (*array*) – options array
* **Returns:**
  an array of data
* **Return type:**
  array or none

The following options are available in the options array.

> * **delimiter** (string) The format separator. The default is `,`.
> * **comment** (string) The comment character (first character only, eg `#` or `;`). The default is not to allow comments.
> * **header** (boolean) If the CSV data includes a header. The default is `true`.
> * **schema** (array) Use a schema to convert columns to types.

The schema should be of the format of being an array keyed on the column name.

```default
[
  "columnname" => [
      "type" => "string", "boolean" or "number",
      "format" => "json" or "regex",
      "nullable" => true or false or [ "", "NULL", ... ],
      "true" => [ "True", ... ],
      "false" => [ "False", ... ],
      "min_length" => ...
      ...other validation methods....
  ],
  ...
]
```

If the column is nullable either set `nullable` to `true` (to treat empty strings as *none*) or set `nullable` to an array of values to treat as *none* (eg. `["NULL"]`). Likewise the boolean type has a `true` and `false` property for truthy and falsy values. The default is `["true"]` and `["false"]` (all lowercase).

Various types have different types of validations available.

| Type     | Validate                            |
|----------|-------------------------------------|
| `string` | `min_length` (number)               |
| `string` | `max_length` (number)               |
| `string` | `pattern` (string)                  |
| `string` | `format` (string) `json` or `regex` |
| `number` | `minimum` (number)                  |
| `number` | `maximum` (number)                  |
| `number` | `exclusive_minimum` (number)        |
| `number` | `exclusive_maximum` (number)        |
| `number` | `multiple_of` (number)              |
| *any*    | `enum` (array)                      |

```hsl
echo csv_decode("enabled\nyes\nno", ["schema" => [
                "enabled" => ["type" => "boolean", "true" => ["yes"], "false" => ["no"]]
            ]]);
// [0=>["enabled"=>true],1=>["enabled"=>false]]
```

> **Note**
> 
> It’s possible to import CSV data at compile time to a variable using the [import](structures.html.md#data-import) statement.

<a id="json_encode"></a>

### json_encode(value[, options])

JSON encode a HSL data type. On error `none` is returned.

* **Parameters:**
  * **value** (*any*) – HSL data type
  * **options** (*array*) – options array
* **Returns:**
  a JSON representation of value
* **Return type:**
  string or none

The following options are available in the options array.

> * **ensure_ascii** (boolean) Convert all non-ASCII characters (UTF-8) to unicode (`\uXXXX`). The default is `true`.
> * **pretty_print** (boolean) Pretty print the JSON output. The default is `false`.
> * **type_error** (boolean) If conversion should fail on non-convertable types (or convert to `none`). The default is `true`.

Encode an array, objects (public members), number or string into a JSON representation (string). The encoding distinguishes arrays from objects if they are sequentially numbered from zero. On encoding errors an object with the data type of undefined is returned. All non-ASCII characters will be escaped as Unicode code points (\\uXXXX).

> **Note**
> 
> Since object keys are converted to strings (even numeric once) a [`json_encode()`](#json_encode) followed by a [`json_decode()`](#json_decode) does not always yield the same result.

<a id="json_decode"></a>

### json_decode(string[, options])

Decodes a JSON string into a HSL data type. On error `none` is returned.

* **Parameters:**
  * **string** (*string*) – JSON serialized data
  * **options** (*array*) – options array
* **Returns:**
  the decoded string as the correct type
* **Return type:**
  any or none

The following options are available in the options array.

> * **allow_comments** (boolean) Allow and ignore comments. The default is `false`.
> * **unicode_byte** (boolean) Non-standard decoding by interpret `\u00XX` as `\xXX`. The default is `false`.
> * **objects** (boolean) If JSON objects should imported as objects (instead of arrays). The default is `false`.

The following translations are done (JSON to HSL).

* **object** to **associative array** (is_array)
* **array** to **array** (is_array)
* **string** to **string** (is_string)
* **number** to **number** (is_number)
* **true** to `true` (is_boolean)
* **false** to `false` (is_boolean)
* **null** to **none**

> **Note**
> 
> It’s possible to import JSON data at compile time to a variable using the [import](structures.html.md#data-import) statement.

<a id="url_encode"></a>

### url_encode(string)

URL encode the string (RFC 3986).

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the URL encoded representation
* **Return type:**
  string

<a id="url_decode"></a>

### url_decode(string)

URL decode the string (RFC 3986).

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string representation
* **Return type:**
  string

<a id="mimeword_encode"></a>

### mimeword_encode(string)

MIME word encode the string (`=?utf-8?Q?string?=`).

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the MIME word encoded representation
* **Return type:**
  string

<a id="mimeword_decode"></a>

### mimeword_decode(string)

MIME word decode the string (`=?charset?encoding?encoded-text?=`).

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string representation
* **Return type:**
  string

<a id="yaml_decode"></a>

### yaml_decode(string[, options])

Decodes a YAML string into a HSL data type. On error `none` is returned.

* **Parameters:**
  * **string** (*string*) – YAML serialized data
  * **options** (*array*) – options array
* **Returns:**
  the decoded string as the correct type
* **Return type:**
  any or none

The following options are available in the options array.

> * **tags** (array) An array of callback functions to parse tagged values. See example below.

Types are automatically detected based on the following rules:

> - Quoted strings are always converted to strings.
> - Unquoted values are first tested as numbers, then booleans, before falling back to strings.

```hsl
echo yaml_decode(''my-set: !Set
  - item1
  - item2
  - item3
my-map: !Map
  item1: !Regex /pattern1/
  item2: !Regex /pattern2/'', [
    "tags" => [
      "!Map" => function ($data) {
        $map = Map("string", "any");
        foreach ($data as $k => $v)
          $map->set($k, $v);
        return $map;
      },
      "!Set" => function ($data) {
        $map = Set("string");
        foreach ($data as $k => $v)
          $map->add($v);
        return $map;
      },
      "!Regex" => function ($data) {
        return pcre_compile($data);
      },
      "!PrivateKey" => function ($data) {
        $k = rsa_privatekey($data);
        if ($k == none)
                $k = ed25519_privatekey($data);
        return $k;
      },
      "!X509" => function ($data) {
        return X509::String($data);
      },
      "!MailMessage" => function ($data) {
        return MailMessage::String($data);
      },
  ]
]); // ["my-set"=>__OBJECT#Set#1__,"my-map"=>__OBJECT#Map#1__]
```

> **Note**
> 
> It’s possible to import YAML data at compile time to a variable using the [import](structures.html.md#data-import) statement.

<a id="pack"></a>

### pack(format[, ...args])

Pack arguments into a binary string. On error `none` is returned.

* **Parameters:**
  * **format** (*string*) – the pack format
  * **...****args** (*any*) – the arguments for the pack format
* **Returns:**
  the packed data
* **Return type:**
  string or none

The format may contain the following types. Some types may be followed by a `*` (an end-of-argument(s) repeater or a numeric repeater, eg. `"Z*C3"`).

| Code   | Repeaters   | Type                        | HSL type   | Bytes   |
|--------|-------------|-----------------------------|------------|---------|
| `a`    | *n*, `*`    | String                      | String     | 1       |
| `C`    | *n*, `*`    | Char                        | Number     | 1       |
| `e`    | *n*, `*`    | Double (LE)                 | Number     | 8       |
| `E`    | *n*, `*`    | Double (BE)                 | Number     | 8       |
| `H`    | *n*, `*`    | Hex                         | String     | 1       |
| `n`    | *n*, `*`    | Unsigned short (16 bit, BE) | Number     | 2       |
| `N`    | *n*, `*`    | Unsigned long (32 bit, BE)  | Number     | 4       |
| `v`    | *n*, `*`    | Unsigned short (16 bit, LE) | Number     | 2       |
| `V`    | *n*, `*`    | Unsigned long (32 bit, LE)  | Number     | 4       |
| `x`    | *n*         | NULL                        |            | 1       |
| `Z`    | *n*, `*`    | String (NULL terminated)    | String     | 1       |

<a id="unpack"></a>

### unpack(format, data[, offset = 0])

Unpack data from a binary string. On error `none` is returned.

* **Parameters:**
  * **format** (*string*) – the unpack format
  * **data** (*string*) – the packed data
  * **offset** (*number*) – the offset to begin unpack from
* **Returns:**
  the unpacked data
* **Return type:**
  array or none

The format may contain the following types. Some types may be followed by a `*` (an end-of-argument(s) repeater or a numeric repeater, eg. `"Z*C3"`).

| Code   | Repeaters   | Type                        | HSL type   | Bytes   |
|--------|-------------|-----------------------------|------------|---------|
| `a`    | *n*, `*`    | String                      | String     | 1       |
| `c`    | *n*, `*`    | Signed char                 | Number     | 1       |
| `C`    | *n*, `*`    | Char                        | Number     | 1       |
| `e`    | *n*, `*`    | Double (LE)                 | Number     | 8       |
| `E`    | *n*, `*`    | Double (BE)                 | Number     | 8       |
| `H`    | *n*, `*`    | Hex                         | String     | 1       |
| `n`    | *n*, `*`    | Unsigned short (16 bit, BE) | Number     | 2       |
| `N`    | *n*, `*`    | Unsigned long (32 bit, BE)  | Number     | 4       |
| `v`    | *n*, `*`    | Unsigned short (16 bit, LE) | Number     | 2       |
| `V`    | *n*, `*`    | Unsigned long (32 bit, LE)  | Number     | 4       |
| `x`    | *n*         | Skip bytes                  |            | 1       |
| `Z`    | *n*, `*`    | String (excluding NULL)     | String     | 1       |

<a id="Iconv"></a>

### *class* Iconv

This class allows characters set conversions using the [Iconv](https://www.gnu.org/software/libiconv/) library. Be aware that different versions of Iconv may have subtile differences.

<a id="Iconv.constructor"></a>

#### constructor(fromcharset, tocharset)

Create a class for conversions between two character sets.

* **Parameters:**
  * **fromcharset** (*string*) – the input character set
  * **tocharset** (*string*) – the output character set

```hsl
$text = Iconv("UTF-8", "ASCII//TRANSLIT//IGNORE");
echo $text->convert("Hello wörld"); // Hello wrld
```

<a id="Iconv.close"></a>

#### close()

Close the Iconv resource and destroy the internal resource.

> **Note**
> 
> Iconv classes are automatically garbage collected (closed). However you may want to explicitly call close.

<a id="Iconv.convert"></a>

#### convert(text)

Convert the text between the two different character sets. On error `none` is returned and you may call [`Iconv.errno()`](#Iconv.errno) to get the error code.

* **Parameters:**
  **text** (*string*) – text to convert
* **Returns:**
  text
* **Return type:**
  string or none

<a id="Iconv.errno"></a>

#### errno()

Get the latest errno returned from the underlying Iconv API.

* **Returns:**
  errno
* **Return type:**
  number

<a id="file-and-http"></a>

## File and HTTP

<a id="File"></a>

### *class* File

This class allows low level file access. A file resource is created for each File instance, this resource is automatically garbage collected (closed) once the object is destroyed.

<a id="File.constructor"></a>

#### constructor(filename[, options])

Open a virtual file from the configuration based on id, or a file on disk (using the `file://` syntax). On error `none` is returned.

* **Parameters:**
  * **filename** (*string*) – the file name
  * **options** (*array*) – options array

The following options are available in the options array.

* **buffered** (boolean) Buffer a `file://` into memory or read from file descriptor. The default is `true`.

```hsl
$file = File("myfile.txt");
while ($data = $file->read(8192))
        echo $data;
```

> **Note**
> 
> In *hsh* a special file URI is available for stdin `hsh://stdin`.

#### constructor(fileresource)

Open a virtual file from a FileResource. On error `none` is returned.

* **Parameters:**
  **fileresource** (*FileResource*) – a FileResource

<a id="File.close"></a>

#### close()

Close the file and destroy the internal file resource.

* **Returns:**
  none
* **Return type:**
  None

> **Note**
> 
> Files are automatically garbage collected (closed). However you may want to explicitly call close.

<a id="File.read"></a>

#### read([length])

Read data from file. On EOF an empty string is returned. On error `none` is returned.

* **Parameters:**
  **length** (*number*) – bytes to read (max 65536)
* **Returns:**
  data
* **Return type:**
  string or none

> **Note**
> 
> If no length is given, all the remaning data until EOF will be read in one operation.

<a id="File.readline"></a>

#### readline()

Read a line from file (without the CRLF or LF). If there are no more lines `false` is returned, and on error `none` is returned.

* **Returns:**
  data
* **Return type:**
  string, boolean or none

<a id="File.seek"></a>

#### seek(offset[, whence = "SEEK_SET"])

Seek to the offset in the file. On error `none` is returned.

* **Parameters:**
  * **offset** (*number*) – the offset
  * **whence** (*string*) – the position specified by whence
* **Returns:**
  position
* **Return type:**
  number or none

Whence may be any of

| Name     | Position                                 |
|----------|------------------------------------------|
| SEEK_CUR | relative offset to the current position  |
| SEEK_SET | absolute offset from the beginning       |
| SEEK_END | negative offset from the end of the file |

<a id="File.tell"></a>

#### tell()

Get the current file position. On error `none` is returned.

* **Returns:**
  position
* **Return type:**
  number or none

<a id="File.getPath"></a>

#### getPath()

Get the path of a file. If no path information is available `none` is returned.

* **Returns:**
  path
* **Return type:**
  string or none

<a id="File.toFFIValue"></a>

#### toFFIValue()

Return a shared `FILE*` pointer to a [C file stream](http://www.cplusplus.com/reference/cstdio/FILE/) representing the current File content and position. On error `none` is returned.

* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue) or none

> **Note**
> 
> The pointer is shared with the [`File`](#File) instance, any operation on the [`File`](#File) instance will also affect *FILE* pointer. However read operations on the *FILE* pointer will not affect the [`File`](#File) position ([`File.tell()`](#File.tell)). The *FILE* pointer must not be closed or deleted.
> 
> ```c++
> #include <cstdio>
> 
> extern "C" void processfile(FILE* fp) {
>   fseek(fp, 0, SEEK_SET);
> }
> ```

<a id="File.String"></a>

#### *static* String(data)

Return a File resource containing the data.

* **Parameters:**
  **data** (*string*) – the content
* **Returns:**
  A file resource
* **Return type:**
  [`File`](#File)

```hsl
$file = File::String("Hello\nWorld");
echo $file->readline(); // "Hello"
```

#### *static* read(filename)

Read all data from file. On error `none` is returned.

* **Parameters:**
  **filename** (*string*) – the file name
* **Returns:**
  data
* **Return type:**
  string or none

```hsl
$data = File::read("file.txt");
if ($data != none)
  echo length($data);
```

<a id="http"></a>

### http(url[, options[, get[, post]]])

Make HTTP/HTTPS request to a URL and return the content.

* **Parameters:**
  * **url** (*string*) – URL to request
  * **options** (*array*) – options array
  * **get** (*array*) – GET variables, replaced and encoded in URL as `$1`, `$2`, …
  * **post** (*array* *,* *string* *or* *function*) – [POST data](#postdata)
* **Returns:**
  if the request was successful (2XX) the content is returned, otherwise `none` is returned
* **Return type:**
  string, array or none

The following options are available in the options array.

> * **extended_result** (boolean) Get an extended result with response code. The default is `false`.
> * **connect_timeout** (number) Connection timeout (in seconds). The default is `10` seconds.
> * **timeout** (number) Timeout (in seconds) for the request. The default is to wait indefinitely.
> * **http_version** (string) Send the request using a specific HTTP version (`1.0`, `1.1` or `2`). The default is to use latest possible available.
> * **post_size** (number) Explicitly set the POST data size. The default is automatically calculated (but needs to be set when the POST data send using HTTP/1.0 and a POST data function callback).
> * **max_file_size** (number) Maximum file size (in bytes). The default is no limit.
> * **sourceip** (string) Explicitly bind an IP address. The default is to be chosen by the system.
> * **sourceipid** (string) Explicitly bind an IP address ID. The default is to be chosen by the system.
> * **unix_socket_path** (string) Unix socket path to connect to (instead of IP).
> * **method** (string) Request method. The default is `GET` unless `POST` data is sent.
> * **headers** (array) An array of additional HTTP headers as strings.
> * **response_headers** (boolean) Return the full request, including response headers (regardless of HTTP status). The default is `false`.
> * **redirects** (number) Specify the number of 304 redirects to follow (use `-1` for *unlimited*). The default is `0` (not to follow redirects).
> * **tls_verify_peer** (boolean) Verify peer certificate. The default is `true`.
> * **tls_verify_host** (boolean) Verify certificate hostname (CN). The default is `false`.
> * **tls_client_cert** (array or string) If given as an associative array it should include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*. If given as a string use the following id of a certificate in the configuration as client certificate. The default is to not send a client certificate.
> * **proxy** (string) Use a HTTP proxy. See CURL_PROXY manual. The default is to inherit proxy settings from the system. Setting it to an empty string will disable the proxy.
> * **username** (string) The authenticate username (default is Basic authentication)
> * **password** (string) The authenticate password
> * **aws_sigv4** (string) aws_sigv4 option (see CURLOPT_AWS_SIGV4), for example `aws:amz:us-east-1:s3`. Use this option together with `username` and `password`.

If the option `extended_result` is `true`, the function returns an array containing the `status` code, `content`, and optionally an `headers` array if `response_headers` is enabled. If no valid HTTP response is received, `none` is returned.

<a id="postdata"></a>

The POST data may be sent in three different ways, depending on the different types, different encodings will be applied. The default *Content-Type* is always `application/x-www-form-urlencoded` if not changed using the `headers` options.

> - **Associative array**: The data will be properly encoded as `a=b&c=d` (x-www-form-urlencoded).
> - **String**: The data will be POSTed as is.
> - **Function callback**: The function callback is repeatedly called with one argument, the max length to return as a string. If the function return an empty string, the POST is done. If the function return `none` an error is triggered and the [`http()`](#http) function will fail. This is useful for chunked POST data.

```hsl
$response = http("http://halon.io/", [
    "extended_result" => true,
    "headers" => ["Host: example.com", "Accept: application/json"]
  ]);
if ($response) {
  echo $response;
}

$f = File::String(json_encode("POST this data as JSON"));
$response = http("http://halon.io/", [
    "extended_result" => true,
    "headers" => ["Content-Type: application/json", "Accept: application/json"]
  ], [], function ($max) closure ($f) {
    return $f->read($max);
  });
if ($response) {
  echo $response;
}

$file = File::String("POST this data as form-data");
$name = "test.txt";
$boundary = uuid();
$preamble = array_join([
    "--".$boundary,
    "Content-Disposition: form-data; name=\"file\"; filename=\"".$name."\"",
    "Content-Type: application/octet-stream",
  ], "\r\n")."\r\n\r\n";
$postamble = "\r\n--".$boundary."--\r\n";
$data = [$preamble, $file, $postamble];
$response = http("http://10.0.0.1/upload", [
    "extended_result" => true,
    "headers" => ["Content-type: multipart/form-data; boundary=".$boundary]
  ], [],
  function ($size) closure ($data) {
    while (length($data)) {
      if (is_string($data[0])) {
        $x = $data[0][0:$size];
        $data[0] = $data[0][$size:];
      } else {
        $x = $data[0]->read($size);
      }
      if ($x !== "")
        return $x;
      $data = $data[1:];
    }
    return "";
  });
if ($response) {
  echo $response;
}
```

<a id="url_parse"></a>

### url_parse(url[, options])

Parse an URL into its components (`scheme`, `username`, `password`, `hostname`, `port`, `path`, `query` and `fragment`). Missing components are not included.

* **Parameters:**
  * **url** (*string*) – URL to parse
  * **options** (*array*) – options array
* **Returns:**
  if the parse was successful each components part is return as an associative array, otherwise `none` is returned
* **Return type:**
  array or none

The following options are available in the options array.

> * **extended_result** (boolean) If `true` on error, an associative array with `error`, `errno` is returned. The default is `false`.

```hsl
echo url_parse("https://halon.io"); // ["scheme"=>"https","hostname"=>"halon.io","path"=>"/"]
```

<a id="mail"></a>

## Mail

<a id="envelope_address_parse"></a>

### envelope_address_parse(address)

Parse an email address into *localpart* and *domain*. On error `none` is returned.

* **Parameters:**
  **address** (*string*) – email addresses
* **Returns:**
  email address parts
* **Return type:**
  array or none

```hsl
echo envelope_address_parse("user@example.com"); // ["localpart"=>"user","domain"=>"example.com"]
```

<a id="envelope_localpart_escape"></a>

### envelope_localpart_escape(localpart)

Apply escaping to the an email envelope localpart.

* **Parameters:**
  **localpart** (*string*) – localpart
* **Returns:**
  escaped localpart
* **Return type:**
  string

```hsl
echo envelope_localpart_escape("email address") . "@example.org"; // "email address"@example.org
```

<a id="header_addresslist_compile"></a>

### header_addresslist_compile(addresses)

Create a properly formated string of list of addresses often used with *From*, *To* and *CC* headers. The addresses array should include a list of associative arrays containg `name` and `address`.

* **Parameters:**
  **addresses** (*array*) – an array of address objects
* **Returns:**
  list of addresses
* **Return type:**
  string

```hsl
echo header_addresslist_compile([
  ["name" => "John Doe", "address" => "john.doe@example.com"],
  ["name" => "Jane Doe", "address" => "jane.doe@example.com"],
]); // "John Doe" <john.doe@example.com>, "Jane Doe" <jane.doe@example.com>
```

<a id="header_addresslist_extract"></a>

### header_addresslist_extract(value[, options])

Extract addresses from a header value or field, often used with *From*, *To* and *CC* headers. The *name* option will make this function return an associative array with the display `name` and `address`. On error `none` is returned.

* **Parameters:**
  * **value** (*string*) – value to extract email addresses from
  * **options** (*array*) – an options array
* **Returns:**
  email addresses
* **Return type:**
  array or none

The following options are available in the options array.

> * **name** (boolean) Return an array of *name* and *address*. The default is `false`.
> * **field** (boolean) If the value is a header field (Header: Value) format. The default is `false`.
> * **decode** (boolean) Decode MIME words (`=?charset?encoding?data?=`). The default is `true`.

```hsl
echo header_addresslist_extract("Charlie <charlie@example.org>; James <james@example.com>", ["name" => true]);
// [0=>["name"=>"Charlie","address"=>"charlie@example.org"],1=>["name"=>"James","address"=>"james@example.com"]]

$fromAddresses = header_addresslist_extract("Charlie <charlie@example.org>; James <james@example.com>");
if ($fromAddresses and length($fromAddresses) > 1)
  echo "Too many From addresses";
```

<a id="header_dkim_decode"></a>

### header_dkim_decode(value[, options])

Decode a Tag=Value list from a DKIM header value or field, often used with *DKIM-Signature* or *ARC-* headers. On error `none` is returned.

* **Parameters:**
  * **value** (*string*) – value to extract tags from
  * **options** (*array*) – an options array
* **Returns:**
  tags
* **Return type:**
  array or none

The following options are available in the options array.

> * **field** (boolean) If the value is a header field (Header: Value) format. The default is `false`.

```hsl
$tags = header_dkim_decode("v=1; d=domain; s=selector; h=to:from:date:subject");
if ($tags and isset($tags["s"]) and isset($tags["d"]))
  echo $tags["s"]."._domainkey.".$tags["d"];
```

<a id="xtext_encode"></a>

### xtext_encode(text)

Encode *xtext* according to the [rfc1891](https://tools.ietf.org/html/rfc1891).

* **Parameters:**
  **text** (*string*) – value to encode
* **Returns:**
  the encoded value
* **Return type:**
  string

<a id="xtext_decode"></a>

### xtext_decode(text)

Decode *xtext* according to the [rfc1891](https://tools.ietf.org/html/rfc1891).

* **Parameters:**
  **text** (*string*) – value to decode
* **Returns:**
  the decoded value
* **Return type:**
  string

<a id="spf_query"></a>

### spf_query(ip, helo, sender)

Check the SPF status of the sender.

* **Parameters:**
  * **ip** (*string*) – IP or IPv6 address to check
  * **helo** (*string*) – HELO/EHLO host name
  * **sender** (*string*) – domain or email to lookup
* **Returns:**
  the result
* **Return type:**
  array

An array with a `result` (string) and in case of errors `error` (string) as an associative array. The `result` is returned as the string result as defined by libspf2 (eg. `pass`).

| libspf error         | result    |
|----------------------|-----------|
| SPF_RESULT_INVALID   | invalid   |
| SPF_RESULT_NEUTRAL   | neutral   |
| SPF_RESULT_PASS      | pass      |
| SPF_RESULT_FAIL      | fail      |
| SPF_RESULT_SOFTFAIL  | softfail  |
| SPF_RESULT_NONE      | none      |
| SPF_RESULT_TEMPERROR | temperror |
| SPF_RESULT_PERMERROR | permerror |

> **Note**
> 
> This function will suspend the current script execution while waiting for DNS responses allowing for cooperative multitasking.

<a id="mathematical"></a>

## Mathematical

<a id="abs"></a>

### abs(number)

Return the absolute value of a number.

* **Parameters:**
  **number** (*number*) – the numeric value to process
* **Returns:**
  the absolute value
* **Return type:**
  number

<a id="ceil"></a>

### ceil(number)

Return the integer value of a number by rounding up if necessary.

* **Parameters:**
  **number** (*number*) – the numeric value to process
* **Returns:**
  the integer value
* **Return type:**
  number

<a id="floor"></a>

### floor(number)

Return the integer value of a number by rounding down if necessary.

* **Parameters:**
  **number** (*number*) – the numeric value to process
* **Returns:**
  the integer value
* **Return type:**
  number

<a id="log"></a>

### log(number[, base = e])

Return the logarithm of number to base.

* **Parameters:**
  * **number** (*number*) – the numeric value to process
  * **base** (*number*) – the base
* **Returns:**
  the logarithm value
* **Return type:**
  number

<a id="pow"></a>

### pow(base, exponent)

Return base raised to the power of the exponent.

* **Parameters:**
  * **base** (*number*) – the base
  * **exponent** (*number*) – the exponent
* **Returns:**
  the power of
* **Return type:**
  number

> **See also**
> 
> It’s significantly faster to use the `**` operator since it’s an operator and not a function.

<a id="round"></a>

### round(number[, decimals = 0])

Return number rounded to precision of decimals.

* **Parameters:**
  * **number** (*number*) – the numeric value to process
  * **decimals** (*number*) – the number of decimals
* **Returns:**
  the rounded value
* **Return type:**
  number

<a id="sqrt"></a>

### sqrt(number)

Return the square root of number.

* **Parameters:**
  **number** (*number*) – the numeric value to process
* **Returns:**
  the square root
* **Return type:**
  number

> **See also**
> 
> It’s significantly faster to use the `number ** 0.5` operator to get the square root since it’s an operator and not a function.

<a id="mime"></a>

## MIME

<a id="MIME"></a>

### *class* MIME

This is a MIME “string builder” used to construct MIME parts.

<a id="MIME.constructor"></a>

#### constructor()

The MIME object “constructor” takes no function arguments.

```hsl
$part = MIME();
$part->setType("multipart/alternative");
$part->appendPart(MIME()->setType("text/plain")->setBody("*Hello World*"));
$part->appendPart(MIME()->setType("text/html")->setBody("<strong>Hello World</strong>"));
echo $part->toString();
```

> **Note**
> 
> Many of the MIME object’s member functions return *this*, allowing them to be called with method chaining.
> 
> ```hsl
> echo MIME()->addHeader("Subject", "Hello")->setBody("Hello World")->toString();
> ```

<a id="MIME.addHeader"></a>

#### addHeader(name, value[, options])

Add a header. The value may be encoded (if needed) and reformatted.

* **Parameters:**
  * **name** (*string*) – name of the header
  * **value** (*string*) – value of the header
  * **options** (*array*) – an options array
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

The following options are available in the options array.

> * **encode** (boolean) Fold and encode the header. The default is `true`.
> * **encoding** (string) Encoding to use (base64 or quoted-printable). The default is `quoted-printable`.

> **Note**
> 
> If a *Content-Type* header is added, the value of [`MIME.setType()`](#MIME.setType) is ignored. If a *Content-Transfer-Encoding* header is added it will be used as the default encoding for the [`MIME.setBody()`](#MIME.setBody).

<a id="MIME.appendPart"></a>

#### appendPart(part)

Add a MIME part (child) object, this is useful when building a multipart MIME.

* **Parameters:**
  **part** ([*MIME*](#MIME)) – a MIME part object
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

> **Note**
> 
> If not explicit set the *Content-Type* is set to *multipart/mixed*. The MIME boundary is also automatically created.

<a id="MIME.setBody"></a>

#### setBody(body)

Set the MIME part body content. In case the MIME part has children (multipart) this will be the MIME parts preamble. The body will be encoded as either quoted-printable or base64 depending on the type of data if no *Content-Transfer-Encoding* header is explicitly added.

* **Parameters:**
  **body** (*string*) – the body
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.setType"></a>

#### setType(type)

Set the type field of the *Content-Type* header. The default type is *text/plain*, and for *text/…* the charset is always utf-8.

* **Parameters:**
  **type** (*string*) – the content type
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.setBoundary"></a>

#### setBoundary(boundary)

Set the MIME boundary for `multipart/*` messages. The default is to use an UUID.

* **Parameters:**
  **boundary** (*string*) – the boundary
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.setDate"></a>

#### setDate([timestamp])

Add a Date header field. The default date is the current time.

* **Parameters:**
  **timestamp** (*number*) – the unix timestamp
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.setFileName"></a>

#### setFileName(filename)

Set the file name in the *Content-Disposition* header. The default disposition is *attachment*, but can be changed with [`MIME.setDisposition()`](#MIME.setDisposition).

* **Parameters:**
  **filename** (*string*) – the filename
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.setDisposition"></a>

#### setDisposition(type)

Set the disposition type in the *Content-Disposition* header.

* **Parameters:**
  **type** (*string*) – the disposition type
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.signDKIM"></a>

#### signDKIM(selector, domain, key[, options])

Sign the MIME structure (message) using DKIM.

* **Parameters:**
  * **selector** (*string*) – selector to use when signing
  * **domain** (*string*) – domain to use when signing
  * **key** (*resource* *or* *string*) – private key to use, either a `*PrivateKey` resource, `pki:X` (or a private RSA key in PEM format or a ed25519 key binary/base64 encoded, but not recommended).
  * **options** (*array*) – options array
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

The following options are available in the options array.

> * **canonicalization_header** (string) header canonicalization (`simple` or `relaxed`). The default is `relaxed`.
> * **canonicalization_body** (string) body canonicalization (`simple` or `relaxed`). The default is `relaxed`.
> * **algorithm** (string) algorithm to hash the message with (`rsa-sha1`, `rsa-sha256` or `ed25519-sha256`). The default is `rsa-sha256`.
> * **additional_headers** (array) additional headers to sign in addition to those recommended by the RFC.
> * **exclude_headers** (array) exclude headers to sign from those recommended by the RFC.
> * **oversign_headers** (array) headers to oversign. The default is `from`.
> * **timestamp** (boolean or number) add the `t` tag to the signature (may be an absolute unix timestamp). The default is `false`.
> * **expiration** (number) add the `x` tag to the signature (an absolute unix timestamp). The default is no expiration.
> * **expiration_relative** (number) add the `x` tag to the signature (seconds relative to `timestamp` or current time). The default is no expiration.
> * **identity** (string) add the `i` tag to the signature. The default is no identity tag.
> * **headers** (array) headers to sign. Note that including `from` in the array is [required](https://datatracker.ietf.org/doc/html/rfc6376#section-5.4) when using this option. The default is to sign all headers recommended by the RFC.
> * **body_length** (number) length of the body to sign. The default is to sign the entire message.
> * **id** (boolean) If the key is given as an id of an private key in the configuration. The default is auto detect.
> * **additional_signatures** (array) An array of associative arrays for additional dual signing for the same canonicalization and settings.
>   > * **selector** (string) selector to use when signing (required)
>   > * **domain** (string) domain to use when signing (required)
>   > * **key** (resource or string) private key to use, either a `*PrivateKey` resource, `pki:X` (or a private RSA key in PEM format or a ed25519 key binary/base64 encoded, but not recommended). (required)
>   > * **identity** (string or none) add the `i` tag to the signature. The default is to inherit the primary identity tag. Use `none` to not add a identity tag.
>   > * **id** (boolean) If the key is given as an string, you may set `id` to `true` and not prefix the value with `pki:`. The default is auto detect.
>   > * **algorithm** (string) Only if the key is given as PEM or base64 data, you should the algorithm (`rsa` or `ed25519`).

> **Note**
> 
> In the message the primary `DKIM-Signature` will be added first, and any additional will be prepended before the primary signature. The reason is that mail headers are added and reasoned about bottom up, similar to the top-most Received header is the latest one.
> 
> ```default
> DKIM-Signature: second-additional-signature
> DKIM-Signature: first-additional-signature
> DKIM-Signature: primary-signature
> Subject: Hello World
> 
> Message Content
> ```

<a id="MIME.toString"></a>

#### toString()

Return the created MIME as a string. This function useful for debugging.

* **Returns:**
  the MIME as string
* **Return type:**
  string

<a id="MIME.toFile"></a>

#### toFile()

Return a [`File`](#File) class for the current MIME object.

* **Returns:**
  A File class for the current MIME object.
* **Return type:**
  [`File`](#File)

<a id="MIME.setContext"></a>

#### setContext(context)

Set immutable context data for the message. Available in queue hooks and shared between recipients.

* **Parameters:**
  **context** (*associative array* *of* *strings*) – context data
* **Returns:**
  this
* **Return type:**
  [`MIME`](#MIME)

<a id="MIME.queue"></a>

#### queue(sender, recipient, transportid[, options])

Queue the message.

* **Parameters:**
  * **sender** (*string* *or* *array*) – the sender email address, either as a string or an associative array with a `localpart` and `domain`. The domain support internationalized domain names (U-labels).
  * **recipient** (*string* *or* *array*) – the recipient email address, either as a string or an associative array with a `localpart` and `domain`.  The domain support internationalized domain names (U-labels).
  * **transportid** (*string*) – the transport profile ID
  * **options** (*array*) – an options array
* **Returns:**
  an id object (with `transaction` and `queue`)
* **Return type:**
  array

The following options are available in the options array.

> * **metadata** (array) Add metadata to the queued message, as a key-value pair array of strings.
> * **hold** (boolean) Put the message in the hold (inactive) queue. The default is `false`.
> * **tenantid** (string) Assign a tenantid to the message.
> * **jobid** (string) Assign a jobid to the message.
> * **priority** (number) The queue priority (0 - normal, 1 - high). The default is `0`.
> * **quotas** (array) An array of quotas to be associated with the message, for use with [`queue_quota()`](#queue_quota).
> * **delay** (number) Delay the first delivery attempt, in seconds. The default is `0`.
> * **dsn** (array) Associative array of `envid` (string), `ret` (string), `notify` (string) and `orcpt` (string).

```hsl
MIME()
        ->addHeader("Subject", "Hello")
        ->setBody("Hi, how are you?")
        ->queue("", ["localpart" => "info", "domain" => "example.com"], "outbound");
```

<a id="MIME.send"></a>

#### send(sender, recipients, server)

Try to send the message to the server. See [`MailMessage.send()`](#MailMessage.send).

<a id="_CPPv411MailMessage"></a>

<a id="_CPPv311MailMessage"></a>

<a id="_CPPv211MailMessage"></a>

<a id="MailMessage"></a>

### class MailMessage : [MIMEPart](#_CPPv48MIMEPart)

This class extends the [`MIMEPart`](#_CPPv48MIMEPart) class, all instances of this class automatically holds a reference to the top level MIMEPart object.

<a id="MailMessage.reset"></a>

#### reset()

Undo all changes on the message.

* **Returns:**
  number of changes discarded
* **Return type:**
  number

```hsl
$mail->reset();
```

<a id="MailMessage.snapshot"></a>

#### snapshot()

Take a snapshot of the current state of the MIME object (to be used with [`MailMessage.restore()`](#MailMessage.restore)).

* **Returns:**
  the snapshot id
* **Return type:**
  number

```hsl
$id = $mail->snapshot();
```

<a id="MailMessage.restore"></a>

#### restore(id)

Restore to a snapshot (to be used with [`MailMessage.snapshot()`](#MailMessage.snapshot)).

* **Parameters:**
  **id** (*number*) – snapshot id
* **Returns:**
  if restore was successful
* **Return type:**
  boolean

```hsl
$mail->restore($id);
```

<a id="MailMessage.modifyContent"></a>

#### modifyContent(start, count, data)

An advanced method of adding custom modification that will be applied to the message (it works the same way as other modification function, eg. [`MIMEPart.addHeader()`](#MIMEPart.addHeader)). This function should not be used when there are [`MIMEPart`](#_CPPv48MIMEPart) operations available doing the supposed modification.

* **Parameters:**
  * **start** (*number*) – start offset of modification
  * **count** (*number*) – bytes to remove at position
  * **data** (*string*) – data to add at position
* **Returns:**
  this
* **Return type:**
  [`MailMessage`](#_CPPv411MailMessage)

```hsl
$mail = MailMessage::String("Subject: Hello\r\n\r\nHello");
$mail->modifyContent(18, 5, "World");
echo $mail->toString();
```

<a id="MailMessage.toFile"></a>

#### toFile()

Return a [`File`](#File) class for the current MIME object (with all changes applied).

* **Returns:**
  A File class for the current MIME object.
* **Return type:**
  [`File`](#File)

<a id="MailMessage.toString"></a>

#### toString()

Return the MailMessage as a string (with all changes applied).

* **Returns:**
  the MailMessage as string
* **Return type:**
  string

<a id="MailMessage.signDKIM"></a>

#### signDKIM(selector, domain, key[, options])

Sign the message using DKIM. On error `none` is returned.

* **Parameters:**
  * **selector** (*string*) – selector to use when signing
  * **domain** (*string*) – domain to use when signing
  * **key** (*resource* *or* *string*) – private key to use, either a `*PrivateKey` resource, `pki:X` (or a private RSA key in PEM format or a ed25519 key binary/base64 encoded, but not recommended).
  * **options** (*array*) – options array
* **Returns:**
  this
* **Return type:**
  [`MailMessage`](#_CPPv411MailMessage) or none

The following options are available in the options array.

> * **canonicalization_header** (string) header canonicalization (`simple` or `relaxed`). The default is `relaxed`.
> * **canonicalization_body** (string) body canonicalization (`simple` or `relaxed`). The default is `relaxed`.
> * **algorithm** (string) algorithm to hash the message with (`rsa-sha1`, `rsa-sha256` or `ed25519-sha256`). The default is `rsa-sha256`.
> * **additional_headers** (array) additional headers to sign in addition to those recommended by the RFC.
> * **exclude_headers** (array) exclude headers to sign from those recommended by the RFC.
> * **oversign_headers** (array) headers to oversign. The default is `from`.
> * **timestamp** (boolean or number) add the `t` tag to the signature (may be an absolute unix timestamp). The default is `false`.
> * **expiration** (number) add the `x` tag to the signature (an absolute unix timestamp). The default is no expiration.
> * **expiration_relative** (number) add the `x` tag to the signature (seconds relative to `timestamp` or current time). The default is no expiration.
> * **identity** (string) add the `i` tag to the signature. The default is no identity tag.
> * **headers** (array) headers to sign. The default is to sign all headers recommended by the RFC.
> * **body_length** (number) length of the body to sign. The default is to sign the entire message.
> * **id** (boolean) If the key is given as an id of an private key in the configuration. The default is auto detect.
> * **return_header** (boolean) Return the DKIM signature as a string, instead of adding it to the message. The default is `false`.
> * **arc** (number) Create an ARC-Message-Signature header by setting the ARC `i` field.
> * **additional_signatures** (array) An array of associative arrays for additional dual signing for the same canonicalization and settings.
>   > * **selector** (string) selector to use when signing (required)
>   > * **domain** (string) domain to use when signing (required)
>   > * **key** (resource or string) private key to use, either a `*PrivateKey` resource, `pki:X` (or a private RSA key in PEM format or a ed25519 key binary/base64 encoded, but not recommended). (required)
>   > * **identity** (string or none) add the `i` tag to the signature. The default is to inherit the primary identity tag. Use `none` to not add a identity tag.
>   > * **id** (boolean) If the key is given as an string, you may set `id` to `true` and not prefix the value with `pki:`. The default is auto detect.
>   > * **algorithm** (string) Only if the key is given as PEM or base64 data, you should the algorithm (`rsa` or `ed25519`).

> **Note**
> 
> In the message the primary `DKIM-Signature` will be added first, and any additional will be prepended before the primary signature. The reason is that mail headers are added and reasoned about bottom up, similar to the top-most Received header is the latest one.
> 
> ```default
> DKIM-Signature: second-additional-signature
> DKIM-Signature: first-additional-signature
> DKIM-Signature: primary-signature
> Subject: Hello World
> 
> Message Content
> ```

> **Note**
> 
> If *return_header* is used, you need to add the header yourself without encoding.
> 
> ```hsl
> $dkimsig = $message->signDKIM("selector", "example.com", $key, ["return_header" => true]);
> $message->addHeader("DKIM-Signature", $dkimsig, ["encode" => false]);
> ```

> **Note**
> 
> Example commands to generate an *ed25519* public/private key pair with OpenSSL.
> 
> ```hsl
> # openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
> # openssl pkey -outform PEM -pubout -in dkim_ed25519.private
> -----BEGIN PUBLIC KEY-----
> MCowBQYDK2VwAyEAt+BaReQe/Xs/jNbhGJre2Y1O4EUsHauy2Ygi5s3gc/0=
> -----END PUBLIC KEY-----
> # openssl pkey -outform DER -in dkim_ed25519.private | tail -c +17 | openssl base64
> NvGwmGmY/vdZH75jDZs9HXe6RZUEx07BeOg3q1ffNRA=
> ```

<a id="MailMessage.verifyDKIM"></a>

#### verifyDKIM(headerfield[, options])

DKIM verify a *DKIM-Signature* or *ARC-Message-Signature* header. The header should include both the header name and value (unmodified).

* **Parameters:**
  * **headerfield** (*string*) – the header to verify
  * **options** (*array*) – options array
* **Returns:**
  associative array containing the result.
* **Return type:**
  array

The following options are available in the options array.

> * **dns_function** (function) a custom DNS function. The default is to use the built in.

The DNS function will be called with the hostname (eg. *2018._domainkeys.example.com*) for which a DKIM record should be returned. The result must be an array containing either an `error` field (`permerror` or `temperror`) or a `result` field with a DKIM TXT record as string.

The resulting array always contains a `result` field of either `pass`, `permerror`, `passerror` (softfail) or `temperror`. In case of an error the reason is included in an `error` field. If the header was successfully parsed (regardless of the result) a `tags` field will be included.

> **Note**
> 
> This function will suspend the current script execution while waiting for DNS responses allowing for cooperative multitasking.

<a id="MailMessage.setContext"></a>

#### setContext(context)

Set immutable context data for the message. Available in queue hooks and shared between recipients.

* **Parameters:**
  **context** (*associative array* *of* *strings*) – context data
* **Returns:**
  this
* **Return type:**
  [`MailMessage`](#_CPPv411MailMessage)

  Return the MailMessage as a string (with all changes applied).

<a id="MailMessage.send"></a>

#### send(sender, recipients, server)

Try to send the message to the server.

* **Parameters:**
  * **sender** (*string* *or* *array*) – the sender (*MAIL FROM*), an address object
  * **recipients** (*array* *of*  *(**string* *or* *array* *)*) – the recipient (*RCPT TO*), an array of address objects
  * **server** (*string* *or* *array*) – array with server settings or transport profile ID
* **Returns:**
  associative array containing the result or an error
* **Return type:**
  array

The address parameters should be either a string or an associative array with a `localpart` and `domain` and optionally a `params` field as an key-values array (to be sent in the *MAIL FROM* or *RCPT TO* command). The domain support internationalized domain names (U-labels).
Transport profiles configured to use destination lookup by MX are not supported, see the note below.

```hsl
$response = $message->send(
    ["localpart" => "nick", "domain" => "example.org"],
    [
        ["localpart" => "chris", "domain" => "example.com", "params" => ["NOTIFY" => "DELAY"]],
        ["localpart" => "charlie", "domain" => "example.com"],
    ],
    ["server" => "10.2.0.1", "tls" => "require"]);

if (isset($response["result"]))
{
    $result = $response["result"];
    $codes = [];
    if ($result["state"] == "EOD")
        $codes = ["reply_codes" => ["code" => $result["code"], "enhanced" => $result["enhanced"]]];
    if ($result["code"] >= 200 and $result["code"] <= 299)
        Accept([...$codes, "reason" => $result["reason"]]);
    if ($result["code"] >= 500 and $result["code"] <= 599)
        Reject($result["reason"], $codes);
    Defer($result["reason"], $codes);
}
else
{
    $error = $response["error"];
    if (!$error["temporary"])
        Reject($error["message"]);
    Defer($error["message"]);
}
```

The following server settings are available in the server array.

> * **server** (string or array) The destination IP-address or hostname as a string, or an associative array with `host` (string) and `mx` (boolean). There is no default destination server.
> * **port** (number) TCP port. The default is `25`.
> * **helo** (string) The default is to use the system hostname.
> * **sourceip** (string) Explicitly bind an IP address. The default is to be chosen by the system.
> * **sourceipid** (string) Explicitly bind an IP address ID. The default is to be chosen by the system.
> * **nonlocal_source** (boolean) Allow binding of non-local addresses (BINDANY). The default is `false`.
> * **saslusername** (string) If specified issue a AUTH LOGIN before MAIL FROM.
> * **saslpassword** (string) If specified issue a AUTH LOGIN before MAIL FROM.
> * **saslmechanism** (string) If specified issue the SASL mechanism and the saslpassword (used for eg. XOAUTH2).
> * **tls** (string) Use any of the following TLS modes; `disabled`, `optional`, `optional_verify`, `dane`, `dane_fallback_require`, `dane_fallback_require_verify`, `dane_require`, `require`, `require_verify` or `trust`. The default is `disabled`.
> * **tls_implicit** (boolean) Use implicit TLS (do not use STARTTLS). The default is `false`.
> * **tls_trust_anchor** (array) An array containing *X509Resource* and/or associative arrays of `selector` (The trust selector), `mtype` (The trust match type) and `data` (The trust data (hex encoded)).
> * **tls_sni** (string or boolean) Request a certificate using the SNI extension. If `true` the connected hostname will be used. The default is not to use SNI (`false`).
> * **tls_protocols** (string) Use one or many of the following TLS protocols; `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2` or `TLSv1.3`. Protocols may be separated by `,` and excluded by `!`. The default is `!SSLv2,!SSLv3`.
> * **tls_ciphers** (string) List of ciphers to support. The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_ciphersuites** (string) List of TLS ciphersuites to support (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_groups** (string) List of TLS groups to offer for TLS key exchange. (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_verify_host** (boolean) Verify certificate hostname (CN). The default is `false`.
> * **tls_verify_name** (array) Hostnames to verify against the certificate’s CN and SAN (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **tls_verify_name_include_host** (boolean) Include the peer you’re connecting to in the verify name list. Unlink `tls_verify_host` which requires it to match regardless of items in the list. The default is `false`.
> * **tls_client_cert** (array or string) If given as an associative array it should include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*. If given as a string use the following id of a certificate in the configuration as client certificate. The default is to not send a client certificate.
> * **xclient** (array) Associative array of XCLIENT attributes to send.
> * **chunking** (boolean) Enable CHUNKING support. The default is `true`.
> * **pipelining** (boolean) Enable PIPELINING support. The default is `true`.
> * **protocol** (string) The protocol to use; `smtp` or `lmtp`. The default is `smtp`.
> * **mx_include** (array) Filter the MX lookup result, only including ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **mx_exclude** (array) Filter the MX lookup result, removing ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **mx_exclude_bypass** (array) Before applying `mx_exclude`, allow the once matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **ip_exclude** (array) Filter the IP addresses or networks, removing addresses listed.
> * **ip_exclude_temporary** (boolean) Specify if empty results due to filtered IP or MX addresses should result in a temporary or permanent error. The default is `false` (permanent error).
> * **timeout** (array) Associative array of [state](postdelivery.html.md#as1) and the timeout in seconds. The default is set according to RFC2821.
> * **connect_timeout** (number) The connect timeout in seconds. The default is `30` seconds.
> * **proxyprotocol** (array) Associative array of `server` (IP), `port` as well as local `sourceip` to use when connecting to the outbound PROXY server.

If the send function resulted in a SMTP response you will get the SMTP response in a `result` field. This `result` field contains a `state` field (string) which indicates at what SMTP stage the error happened, a `reason` field (array of strings) containing the SMTP reponse (from the server) and a `code` field (number) containg the SMTP status code, optionally a `enhanced` (array of three numbers) field containg the SMTP enhanced status code. If a generic error happens the function will return a `error` field. This `error` field contains a `temporary` (boolean) field to indicate if the error may be transient, a `reason` field (string) containing a the error which happened and a `type` field (string) containing the type of error which happened (one of `config`, `dns`, `network`, `dane`,  `protocol`, `smtp`, `tls` or `plugin`), for *dns* errors a subcategories is presented with a `dns` properites with one of the following value of `other`, `nxdomain`, `nullmx`, `ipfamily`, `nodata` or `excluded`.

If a SMTP connection could be established a `connection` field will be included. This field contains the `localip` field (string), the `localipid` field (string), the `remoteip` field (string) and the `remotemx` field (string).

A `tls` field will always be included, to indicate if the connection had TLS enabled.

The following `state` values are available.

|                 |                                                |
|-----------------|------------------------------------------------|
| BANNER          | The initial SMTP greeting                      |
| HELO            |                                                |
| EHLO            |                                                |
| LHLO            |                                                |
| STARTTLS        |                                                |
| AUTH-CRAM-MD5   | In reply to sending AUTH CRAM-MD5 command      |
| AUTH-PLAIN      | In reply to sending AUTH PLAIN command         |
| AUTH-LOGIN      | In reply to sending AUTH LOGIN command         |
| AUTH-LOGIN-USER | In reply to sending AUTH LOGIN username        |
| AUTH            | In reply to last command of AUTH login attempt |
| XCLIENT         | In reply to sending a XCLIENT command          |
| MAIL            |                                                |
| RCPT            |                                                |
| DATA            | In reply to sending the DATA command           |
| BDAT            | In reply to sending the BDAT command           |
| EOD             | In reply sending the End-of-DATA               |
| RSET            |                                                |
| NOOP            |                                                |
| QUIT            |                                                |

> **Note**
> 
> It’s not possible to use transport profiles configured to use destination lookup by MX, for the simple reason that this function supports
> sending to multiple recipients, on multiple domains/MX. You have to explicitly configure which host to deliver to.
> To use lookup MX for a specific domain use this server syntax.
> 
> ```hsl
> $mail->send($sender, $recipients, ["server" => ["host" => "example.com", "mx" => true]]);
> ```

<a id="MailMessage.queue"></a>

#### queue(sender, recipient, transportid[, options])

Queue the message.

* **Parameters:**
  * **sender** (*string* *or* *array*) – the sender email address, either as a string or an associative array with a `localpart` and `domain`
  * **recipient** (*string* *or* *array*) – the recipient email address, either as a string or an associative array with a `localpart` and `domain`
  * **transportid** (*string*) – the transport profile ID
  * **options** (*array*) – an options array
* **Returns:**
  an id object (with `transaction` and `queue`)
* **Return type:**
  array

The following options are available in the options array.

> * **metadata** (array) Add metadata to the queued message, as a key-value pair array of strings.
> * **hold** (boolean) Put the message in the hold (inactive) queue. The default is `false`.
> * **tenantid** (string) Assign a tenantid to the message.
> * **jobid** (string) Assign a jobid to the message.
> * **priority** (number) The queue priority (0 - normal, 1 - high). The default is `0`.
> * **quotas** (array) An array of quotas to be associated with the message, for use with [`queue_quota()`](#queue_quota).
> * **delay** (number) Delay the first delivery attempt, in seconds. The default is `0`.
> * **dsn** (array) Associative array of `envid` (string), `ret` (string), `notify` (string) and `orcpt` (string).

<a id="MailMessage.String"></a>

#### *static* String(data)

Return a MailMessage resource containing the data.

* **Parameters:**
  **data** (*string*) – the content
* **Returns:**
  A MailMessage resource
* **Return type:**
  [`MailMessage`](#_CPPv411MailMessage) or none

<a id="MailMessage.File"></a>

#### *static* File(file)

Return a MailMessage resource containing the file’s content.

* **Parameters:**
  **file** ([*File*](#File)) – the content
* **Returns:**
  A MailMessage resource
* **Return type:**
  [`MailMessage`](#_CPPv411MailMessage) or none

<a id="_CPPv48MIMEPart"></a>

<a id="_CPPv38MIMEPart"></a>

<a id="_CPPv28MIMEPart"></a>

<a id="MIMEPart"></a>

### class MIMEPart

This class represent a MIME part in the MIME tree.

> **Note**
> 
> This class can only be accessed through the extended [`MailMessage`](#_CPPv411MailMessage) class or from functions returning this object type eg. [`MIMEPart.getParts()`](#MIMEPart.getParts).

> **Note**
> 
> Changes done to any MIME object will **not** be reflected on consecutive calls to “get” functions, however they will be applied to the message upon delivery.
> Also multiple calls to the same “set” function may yield undefined behaviour (like calling setBody twice).

<a id="MIMEPart.getID"></a>

#### getID()

Return the MIME part’s ID.

* **Returns:**
  part id
* **Return type:**
  string

<a id="MIMEPart.getSize"></a>

#### getSize()

Return the MIME part’s size in bytes.

* **Returns:**
  size in bytes
* **Return type:**
  number

<a id="MIMEPart.getFileName"></a>

#### getFileName()

Return the MIME part’s file name (if it has one).

* **Returns:**
  file name
* **Return type:**
  string or none

<a id="MIMEPart.getType"></a>

#### getType()

Return the MIME part’s *Content-Type*’s type field (eg. *text/plain*).

* **Returns:**
  content type
* **Return type:**
  string or none

<a id="MIMEPart.getTypeParameter"></a>

#### getTypeParameter(name)

Return the MIME part’s *Content-Type*’s type parameter value based on name (eg. *boundary*).

* **Parameters:**
  **name** (*string*) – name of the parameter
* **Returns:**
  content type
* **Return type:**
  string or none

<a id="MIMEPart.getHeader"></a>

#### getHeader(name[, options])

Return the value of a header (if multiple headers with the same name exists, the topmost will be returned). If no header is found, the value `none` is returned. The name is not case sensitive.

* **Parameters:**
  * **name** (*string*) – name of the header
  * **options** (*array*) – an options array
* **Returns:**
  header value
* **Return type:**
  string or none

The following options are available in the options array.

> * **index** (number) The index of the header, from the top, starting at zero (per header name). The default is `0`.
> * **field** (boolean) Get the header field as is (including the name, CRLF and whitespace preserved). The default is `false`.
> * **decode** (boolean) Unfold and decode the header’s MIME words (`=?utf-8?q?...?=`). The default is `true`.
> * **reverse** (boolean) Get headers in reverse order. The default is `false`.

```hsl
if (is_string($contentid = $part->getHeader("Content-ID")))
        echo "Content-ID is $contentid";
```

```hsl
// DKIM verify example
$dkimHeader = $part->getHeader("DKIM-Signature", ["field" => true]); // field needed for DKIM
if ($dkimHeader)
        echo $part->verifyDKIM($dkimHeader);
```

> **Note**
> 
> The [`MIMEPart.getHeader()`](#MIMEPart.getHeader) function family will return headers as a UTF-8 string with all MIME encoded-words decoded (`=?charset?encoding?data?=`). However even if headers must be in 7-bit ASCII, some senders do not conform to this and do send headers with different charset encodings. In those cases we (1) Use the MIME-parts “Content-Type” headers charset when converting to UTF-8. (2) If there is no charset information available we use a statistical charset detection function. (3) We just pretend it to be US-ASCII and covert it to UTF-8 anyway (guaranteeing the result will be valid UTF-8).

<a id="MIMEPart.getHeaders"></a>

#### getHeaders(name[, options])

Return a list of header values. If no header is found, an empty list is returned. The name is not case sensitive.

* **Parameters:**
  * **name** (*string*) – name of the header
  * **options** (*array*) – an options array
* **Returns:**
  header values
* **Return type:**
  array of string

The following options are available in the options array.

> * **field** (boolean) Get the header field as is (including the name). The default is `false`.
> * **decode** (boolean) Unfold and decode the header’s MIME words (`=?utf-8?q?...?=`). The default is `true`.

```hsl
echo "Received headers: ".length($arguments["mail"]->getHeaders("Received"));
```

<a id="MIMEPart.getHeaderNames"></a>

#### getHeaderNames()

Return a list of all header names, from the top. The names are in lower case.

* **Returns:**
  header names
* **Return type:**
  array of string

<a id="MIMEPart.setHeader"></a>

#### setHeader(name, value[, options])

Overwrite existing header(s) or create a new header. The name is not case sensitive.

* **Parameters:**
  * **name** (*string*) – name of the header
  * **value** (*string*) – value of the header
  * **options** (*array*) – an options array
* **Returns:**
  number of headers changed
* **Return type:**
  number

The following options are available in the options array.

> * **index** (number) The index of the header, from the top, starting at zero (per header name).
> * **encode** (boolean) Fold and encode the header. The default is `true`.
> * **encoding** (string) Encoding to use (base64 or quoted-printable). The default is `quoted-printable`.

<a id="MIMEPart.addHeader"></a>

#### addHeader(name, value[, options])

Add a new header (at the top of the message).

* **Parameters:**
  * **name** (*string*) – name of the header
  * **value** (*string*) – value of the header
  * **options** (*array*) – an options array
* **Return type:**
  none

The following options are available in the options array.

> * **encode** (boolean) Fold and encode the header. The default is `true`.
> * **encoding** (string) Encoding to use (base64 or quoted-printable). The default is `quoted-printable`.

<a id="MIMEPart.delHeader"></a>

#### delHeader(name[, options])

Delete all headers by the name. The name is not case sensitive.

* **Parameters:**
  * **name** (*string*) – name of the header
  * **options** (*array*) – an options array
* **Returns:**
  number of headers deleted
* **Return type:**
  number

The following options are available in the options array.

> * **index** (number) The index of the header, from the top, starting at zero (per header name).

<a id="MIMEPart.renameHeader"></a>

#### renameHeader(name, newname[, options])

Rename all headers by the name. The name is not case sensitive.

* **Parameters:**
  * **name** (*string*) – name of the header
  * **newname** (*string*) – the new header name
* **Returns:**
  number of headers renamed
* **Return type:**
  number

<a id="MIMEPart.setDateLater"></a>

#### setDateLater()

Add or set the Date header field upon message delivery/generation. The default date is the current time.

* **Returns:**
  number of headers changed
* **Return type:**
  number

> **Warning**
> 
> If you also DKIM sign your messages when using this function it’s very important that you exclude the *Date* header from the DKIM signature using for example the `exclude_headers` option to [`MIME.signDKIM()`](#MIME.signDKIM).

<a id="MIMEPart.remove"></a>

#### remove()

Remove this MIME part.

* **Return type:**
  none

<a id="MIMEPart.getBody"></a>

#### getBody([options])

Get the body (content) of a MIME part. The content will be decoded according to the *Content-Transfer-Encoding* header.

* **Parameters:**
  **options** (*array*) – an options array
* **Returns:**
  the body content
* **Return type:**
  string or none

The following options are available in the options array.

> * **decode** (boolean) Decode the body accoding to the “Content-Transfer-Encoding” header. The default is `true`.

> **Note**
> 
> This function will decode using the “Content-Transfer-Encoding” header. It will not do any character set conversion, hence the data can be in any character set encoding.

<a id="MIMEPart.setBody"></a>

#### setBody(data[, options])

Set the body (content) of a MIME part. The MIME parts encoding (*Content-Transfer-Encoding*) will be changed to the best readable match, that can be either *7bit*, *quoted-printable* or *base64* and the data will encoded as such.

* **Parameters:**
  * **data** (*string*) – the body content
  * **options** (*array*) – an options array
* **Returns:**
  this
* **Return type:**
  [`MIMEPart`](#_CPPv48MIMEPart) or none

The following options are available in the options array.

> * **encoding** (string) Force encoding of `7bit`, `8bit`, `binary`, `base64` or `quoted-printable`. The default is to use the best readable match.

> **Note**
> 
> Changes done to any MIME object will **not** be reflected on consecutive calls to “get” functions, however they will be applied to the message upon delivery.
> Also multiple calls to the same “set” function may yield undefined behaviour (like calling setBody twice).

<a id="MIMEPart.getPreamble"></a>

#### getPreamble()

Get the multipart MIME parts epilogue text. If the MIMEPart isn’t a multipart MIME, `none` is returned.

* **Return type:**
  string or none

<a id="MIMEPart.setPreamble"></a>

#### setPreamble(data)

Set the multipart MIME parts preamble text. If the MIMEPart isn’t a multipart MIME, `none` is returned.

* **Parameters:**
  **data** (*string*) – the preamble text
* **Returns:**
  this
* **Return type:**
  [`MIMEPart`](#_CPPv48MIMEPart) or none

<a id="MIMEPart.getEpilogue"></a>

#### getEpilogue()

Get the multipart MIME parts epilogue text. If the MIMEPart isn’t a multipart MIME, `none` is returned.

* **Return type:**
  string or none

<a id="MIMEPart.setEpilogue"></a>

#### setEpilogue(data)

Set the multipart MIME parts epilogue text. If the MIMEPart isn’t a multipart MIME, `none` is returned.

* **Parameters:**
  **data** (*string*) – the epilogue text
* **Returns:**
  this
* **Return type:**
  [`MIMEPart`](#_CPPv48MIMEPart) or none

<a id="MIMEPart.prependPart"></a>

#### prependPart(part[, options])

Add a MIME part before this part. If the MIMEPart isn’t a multipart MIME, `none` is returned.

* **Parameters:**
  * **part** ([*MIME*](#MIME)) – a [`MIME`](#MIME) or [`MIMEPart`](#_CPPv48MIMEPart) object
  * **options** (*array*) – an options array
* **Returns:**
  this
* **Return type:**
  [`MIMEPart`](#_CPPv48MIMEPart) or none

The following options are available in the options array.

> * **type** (string) The multipart content type to use. The default is `multipart/mixed`.

<a id="MIMEPart.appendPart"></a>

#### appendPart(part[, options])

Add a MIME part after this part. If the MIMEPart isn’t a multipart MIME, `none` is returned.

* **Parameters:**
  * **part** ([*MIME*](#MIME)) – a [`MIME`](#MIME) or [`MIMEPart`](#_CPPv48MIMEPart) object
  * **options** (*array*) – an options array
* **Returns:**
  this
* **Return type:**
  [`MIMEPart`](#_CPPv48MIMEPart) or none

The following options are available in the options array.

> * **type** (string) The multipart content type to use. The default is `multipart/mixed`.

<a id="MIMEPart.replacePart"></a>

#### replacePart(part)

Replace the current MIME part.

* **Parameters:**
  **part** ([*MIME*](#MIME)) – a [`MIME`](#MIME) or [`MIMEPart`](#_CPPv48MIMEPart) object
* **Return type:**
  none

<a id="MIMEPart.findByType"></a>

#### findByType(type)

Find descendant parts (on any depth) based on their *Content-Type*. If type is given as a string, it’s compiled as a regex with `/type/i` (partial, case-insensitive).

* **Parameters:**
  **type** ([Regex](literals.html.md#regextype) or string) – type as regex
* **Returns:**
  MIME parts
* **Return type:**
  array of [`MIMEPart`](#_CPPv48MIMEPart) objects

<a id="MIMEPart.findByFileName"></a>

#### findByFileName(filename)

Find descendant parts (on any depth) based on their file name. If filename is given as a string, it’s compiled as a regex with `/filename/i` (partial, case-insensitive).

* **Parameters:**
  **filename** ([Regex](literals.html.md#regextype) or string) – filename as regex
* **Returns:**
  MIME parts
* **Return type:**
  array of [`MIMEPart`](#_CPPv48MIMEPart) objects

<a id="MIMEPart.getByID"></a>

#### getByID(id)

Get a MIME part by ID (on any depth, including the current part). If the part is not found `none` is returned.

* **Parameters:**
  **id** (*string*) – the MIME part id
* **Returns:**
  MIME part
* **Return type:**
  [`MIMEPart`](#_CPPv48MIMEPart) object or none

<a id="MIMEPart.getParts"></a>

#### getParts()

Return child parts.

* **Returns:**
  MIME parts
* **Return type:**
  array of [`MIMEPart`](#_CPPv48MIMEPart) objects

<a id="MIMEPart.getErrors"></a>

#### getErrors()

Return a list of all errors affecting this MIME part. The following errors are available; `bad_header` and `unclosed_boundary`.

* **Returns:**
  list of errors
* **Return type:**
  array of string

<a id="misc"></a>

## Misc

<a id="gethostname"></a>

### gethostname()

The hostname of the installation, this can be used to identify a software instance.

* **Returns:**
  the hostname
* **Return type:**
  string

<a id="uuid"></a>

### uuid()

Return a unique ID.

* **Returns:**
  a unique ID
* **Return type:**
  string

<a id="uuidv5"></a>

### uuidv5(uuidnamespace, value)

Return a deterministic unique ID.

* **Parameters:**
  * **uuidnamespace** (*string*) – the UUIDv5 namespace
  * **value** (*string*) – the value to hash
* **Returns:**
  a unique ID
* **Return type:**
  string

```hsl
echo uuidv5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "halon.io"); // 97665414-d057-5f50-9a76-a3dc23d321a1
```

<a id="echo"></a>

### echo()

Print a message to the log.

```hsl
echo "Log message";
```

> **Note**
> 
> *echo* is not a function, therefore do not call it with parentheses. The text messages is logged with [`syslog()`](#syslog) level *debug* or stdout, with `$messageid` prefixed (when applicable).

<a id="syslog"></a>

### syslog(priority, message)

The syslog function complements the `echo` statement by allowing messages with custom priorities to be logged.

* **Parameters:**
  * **priority** (*string* *or* *number*) – message priority
  * **message** (*string*) – message
* **Return type:**
  none

Priority may be any of

| Name    |    |
|---------|----|
| emerg   | 0  |
| alert   | 1  |
| crit    | 2  |
| err     | 3  |
| warning | 4  |
| notice  | 5  |
| info    | 6  |
| debug   | 7  |

It’s possible to change the facility of a log message by adding a facility value (see rfc5424).

```hsl
syslog(3 + (4<<3), "This is sent as LOG_ERR to LOG_AUTH");
```

> **Note**
> 
> If you want your log message to appear when the message log is viewed (as it does with [`echo()`](#echo), you should prefix the message parameter with `"[$messageid] "`.

<a id="inet_includes"></a>

### inet_includes(ip, network)

Returns true if *ip* is in the subnet or range of *network*. Both IPv4 and IPv6 are supported (comparison between different protocols always yields *false*). On error `none` is returned.

* **Parameters:**
  * **ip** (*string*) – ip address
  * **network** (*string*) – address, subnet or range.
* **Returns:**
  true if ip is in network
* **Return type:**
  boolean or none

```hsl
inet_includes("127.0.0.1", "127.0.0.1/8");
inet_includes("127.0.0.1", "127.0.0.0-127.255.255.255");
inet_includes("127.0.0.1", "127.0.0.1");
inet_includes("2001:4860:4860::8888", "2001:4860:4860::/48");
```

<a id="inet_ntop"></a>

### inet_ntop(ip)

Converts an IP from a binary string format (4 char for IPv4 and 16 char for IPv6) to a printable string format (eg *10.0.0.1*). On error `none` is returned.

* **Parameters:**
  **ip** (*string*) – the ip in binary string format
* **Returns:**
  an ip in printable string format
* **Return type:**
  string or none

<a id="inet_pton"></a>

### inet_pton(ip)

Converts an IP from printable string format (eg *10.0.0.1*) to a binary string format (4 char for IPv4 and 16 char for IPv6). On error `none` is returned.

* **Parameters:**
  **ip** (*string*) – the ip in printable format
* **Returns:**
  an ip in binary string format
* **Return type:**
  string or none

```hsl
$x = unpack("N*", inet_pton($ip));
if (length($x) == 1)
        $x[0] = $x[0] & 0xffffff00; // mask ipv4 to /24
if (length($x) == 4)
        $x[3] = 0; // mask ipv6 to /96
echo inet_ntop(pack("N*", ...$x));
```

<a id="inet_reverse"></a>

### inet_reverse(ip[, zone])

> Converts an IPv4 or IPv6 to a reverse DNS compatible format (to be used with PTR lookups or DNSxL lookups). By default the zone correspons to the ARPA address for each IP family. On error `none` is returned.

* **Parameters:**
  * **ip** (*string*) – the ip in printable format
  * **zone** (*string*) – the zone to append
* **Returns:**
  an reverse DNS hostname
* **Return type:**
  string or none

```hsl
echo inet_reverse("8.8.8.8"); // 8.8.8.8.in-addr.arpa
echo inet_reverse("12.34.56.78", "example.com"); // 78.56.34.12.example.com
```

<a id="protocols"></a>

## Protocols

<a id="smtp_lookup_rcpt"></a>

### smtp_lookup_rcpt(server, sender, recipient[, options])

Check if sender is allowed to send mail to recipient.

* **Parameters:**
  * **server** (*string* *or* *array*) – array with server settings or transport profile ID
  * **sender** (*string* *or* *array*) – the sender (MAIL FROM), either as a string or an associative array with a `localpart` and `domain`
  * **recipient** (*string* *or* *array*) – the recipient (RCPT TO), either as a string or an associative array with a `localpart` and `domain`
  * **options** (*array*) – options array
* **Returns:**
  `1` if the command succeeded, `0` if the command failed and `-1` if an error occurred. The `extended_result` option may change this behaviour.
* **Return type:**
  number or array

The following server settings are available in the server array.

> * **server** (string or array) The destination IP-address or hostname as a string, or an associative array with `host` (string) and `mx` (boolean). The default is to use MX lookup for the recipient domain.
> * **port** (number) TCP port. The default is `25`.
> * **helo** (string) The default is to use the system hostname.
> * **sourceip** (string) Explicitly bind an IP address. The default is to be chosen by the system.
> * **sourceipid** (string) Explicitly bind an IP address ID. The default is to be chosen by the system.
> * **nonlocal_source** (boolean) Allow binding of non-local addresses (BINDANY). The default is `false`.
> * **saslusername** (string) If specified issue a AUTH LOGIN before MAIL FROM.
> * **saslpassword** (string) If specified issue a AUTH LOGIN before MAIL FROM.
> * **saslmechanism** (string) If specified issue the SASL mechanism and the saslpassword (used for eg. XOAUTH2).
> * **tls** (string) Use any of the following TLS modes; `disabled`, `optional`, `optional_verify`, `dane`, `dane_fallback_require`, `dane_fallback_require_verify`, `dane_require`, `require`, `require_verify` or `trust`. The default is `disabled`.
> * **tls_implicit** (boolean) Use implicit TLS (do not use STARTTLS). The default is `false`.
> * **tls_trust_anchor** (array) An array containing *X509Resource* and/or associative arrays of `selector` (The trust selector), `mtype` (The trust match type) and `data` (The trust data (hex encoded)).
> * **tls_sni** (string or boolean) Request a certificate using the SNI extension. If `true` the connected hostname will be used. The default is not to use SNI (`false`).
> * **tls_protocols** (string) Use one or many of the following TLS protocols; `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2` or `TLSv1.3`. Protocols may be separated by `,` and excluded by `!`. The default is `!SSLv2,!SSLv3`.
> * **tls_ciphers** (string) List of ciphers to support. The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_ciphersuites** (string) List of TLS ciphersuites to support (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_groups** (string) List of TLS groups to offer for TLS key exchange. (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_verify_host** (boolean) Verify certificate hostname (CN). The default is `false`.
> * **tls_verify_name** (array) Hostnames to verify against the certificate’s CN and SAN (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **tls_verify_name_include_host** (boolean) Include the peer you’re connecting to in the verify name list. Unlink `tls_verify_host` which requires it to match regardless of items in the list. The default is `false`.
> * **tls_client_cert** (array or string) If given as an associative array it should include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*. If given as a string use the following id of a certificate in the configuration as client certificate. The default is to not send a client certificate.
> * **tls_capture_peer_cert** (boolean) If set to true, the peer certificate will be available in the extended results. The default is `true`.
> * **xclient** (array) Associative array of XCLIENT attributes to send.
> * **protocol** (string) The protocol to use; `smtp` or `lmtp`. The default is `smtp`.
> * **mx_include** (array) Filter the MX lookup result, only including ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **mx_exclude** (array) Filter the MX lookup result, removing ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **mx_exclude_bypass** (array) Before applying `mx_exclude`, allow the once matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **ip_exclude** (array) Filter the IP addresses or networks, removing addresses listed.
> * **ip_exclude_temporary** (boolean) Specify if empty results due to filtered IP or MX addresses should result in a temporary or permanent error. The default is `false` (permanent error).
> * **timeout** (array) Associative array of [state](postdelivery.html.md#as1) and the timeout in seconds. The default is set according to RFC2821.
> * **connect_timeout** (number) The connect timeout in seconds. The default is `30` seconds.
> * **proxyprotocol** (array) Associative array of `server` (IP) and `port` as well as local `sourceip` to use when connecting to the outbound PROXY server.

The following options are available in the options array.

> * **extended_result** (boolean) If `true` an associative array with `error_code`, `error_message`, `on_rcptto` and `tls` is returned. The default is `false`.

<a id="smtp_lookup_auth"></a>

### smtp_lookup_auth(server, username, password)

Try to authenticate the username against a SMTP server.

* **Parameters:**
  * **server** (*string* *or* *array*) – array with server settings or transport profile ID
  * **username** (*string*) – username
  * **password** (*string*) – password
* **Returns:**
  `1` if the authentication succeeded, `0` if the authentication failed and `-1` if an error occurred.
* **Return type:**
  number

The following server settings are available in the server array.

> * **server** (string or array) The destination IP-address or hostname as a string, or an associative array with `host` (string) and `mx` (boolean). There is no default destination server.
> * **port** (number) TCP port. The default is `25`.
> * **helo** (string) The default is to use the system hostname.
> * **sourceip** (string) Explicitly bind an IP address. The default is to be chosen by the system.
> * **sourceipid** (string) Explicitly bind an IP address ID. The default is to be chosen by the system.
> * **nonlocal_source** (boolean) Allow binding of non-local addresses (BINDANY). The default is `false`.
> * **saslusername** (string) If specified issue a AUTH LOGIN before MAIL FROM.
> * **saslpassword** (string) If specified issue a AUTH LOGIN before MAIL FROM.
> * **saslmechanism** (string) If specified issue the SASL mechanism and the saslpassword (used for eg. XOAUTH2).
> * **tls** (string) Use any of the following TLS modes; `disabled`, `optional`, `optional_verify`, `dane`, `dane_fallback_require`, `dane_fallback_require_verify`, `dane_require`, `require`, `require_verify` or `trust`. The default is `disabled`.
> * **tls_implicit** (boolean) Use implicit TLS (do not use STARTTLS). The default is `false`.
> * **tls_trust_anchor** (array) An array containing *X509Resource* and/or associative arrays of `selector` (The trust selector), `mtype` (The trust match type) and `data` (The trust data (hex encoded)).
> * **tls_sni** (string or boolean) Request a certificate using the SNI extension. If `true` the connected hostname will be used. The default is not to use SNI (`false`).
> * **tls_protocols** (string) Use one or many of the following TLS protocols; `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2` or `TLSv1.3`. Protocols may be separated by `,` and excluded by `!`. The default is `!SSLv2,!SSLv3`.
> * **tls_ciphers** (string) List of ciphers to support. The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_ciphersuites** (string) List of TLS ciphersuites to support (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_groups** (string) List of TLS groups to offer for TLS key exchange. (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_verify_host** (boolean) Verify certificate hostname (CN). The default is `false`.
> * **tls_verify_name** (array) Hostnames to verify against the certificate’s CN and SAN (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **tls_verify_name_include_host** (boolean) Include the peer you’re connecting to in the verify name list. Unlink `tls_verify_host` which requires it to match regardless of items in the list. The default is `false`.
> * **tls_client_cert** (array or string) If given as an associative array it should include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*. If given as a string use the following id of a certificate in the configuration as client certificate. The default is to not send a client certificate.
> * **xclient** (array) Associative array of XCLIENT attributes to send.
> * **protocol** (string) The protocol to use; `smtp` or `lmtp`. The default is `smtp`.
> * **mx_include** (array) Filter the MX lookup result, only including ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **mx_exclude** (array) Filter the MX lookup result, removing ones matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **mx_exclude_bypass** (array) Before applying `mx_exclude`, allow the once matching the hostnames/wildcards (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **ip_exclude** (array) Filter the IP addresses or networks, removing addresses listed.
> * **ip_exclude_temporary** (boolean) Specify if empty results due to filtered IP or MX addresses should result in a temporary or permanent error. The default is `false` (permanent error).
> * **timeout** (array) Associative array of [state](postdelivery.html.md#as1) and the timeout in seconds. The default is set according to RFC2821.
> * **connect_timeout** (number) The connect timeout in seconds. The default is `30` seconds.
> * **proxyprotocol** (array) Associative array of `server` (IP) and `port` as well as local `sourceip` to use when connecting to the outbound PROXY server.

<a id="id4"></a>

## String

<a id="chr"></a>

### chr(number)

Returns ASCII character from a number. This function complements [`ord()`](#ord).

* **Parameters:**
  **number** (*number*) – the ASCII number
* **Returns:**
  ASCII character
* **Return type:**
  string

<a id="ord"></a>

### ord(character)

Return ASCII value of a character. This function complements [`chr()`](#chr).

* **Parameters:**
  **character** (*string*) – the ASCII character
* **Returns:**
  the ASCII value
* **Return type:**
  number

<a id="str_repeat"></a>

### str_repeat(string, multiplier)

Returns the string repeated multiplier times.

* **Parameters:**
  * **string** (*string*) – the input string
  * **multiplier** (*number*) – the string multiplier
* **Returns:**
  the repeated string
* **Return type:**
  string

> **See also**
> 
> It’s significantly faster to use the string repeat `*` operator since it’s an operator and not a function.

<a id="str_replace"></a>

### str_replace(search, replace, subject)

Returns the string subject with the string search replace with replace.

* **Parameters:**
  * **search** (*string*) – the search string
  * **replace** (*string*) – the replace string
  * **subject** (*string*) – the string acted upon
* **Returns:**
  subject with searched replaced with replace
* **Return type:**
  string

```hsl
str_replace("Hello", "Hej", "Hello World") // "Hej World"
```

<a id="str_split"></a>

### str_split(string, delimiter[, limit = 0])

Splits the string into an array on the delimiter.

* **Parameters:**
  * **string** (*string*) – the string
  * **delimiter** (*string*) – the delimiter
  * **limit** (*number*) – the maximum number of parts returned
* **Returns:**
  an array of strings
* **Return type:**
  array

```hsl
str_split("how are you", " ",  2) // ["how","are you"]
str_split("how are you", " ", -2) // ["how are","you"]
```

> **See also**
> 
> To join an array to a string, see [`array_join()`](#array_join).

<a id="str_find"></a>

### str_find(string, substring[, offset = 0])

Return the position (starting from zero) of the first occurrence of substring in the string (starting from the offset). If the substring is **not** found -1 is returned.

* **Parameters:**
  * **string** (*string*) – the input string
  * **substring** (*string*) – the string to look for
  * **offset** (*number*) – the offset from the start
* **Returns:**
  the position where substring is found or -1
* **Return type:**
  number

<a id="str_rfind"></a>

### str_rfind(string, substring[, offset])

Return the position (starting from zero) of the last occurrence of substring in the string, searching backward.
If offset is given, only occurrences starting at or before position offset (counted from the beginning of the string) are considered.
If omitted, the whole string is searched. If the substring is not found, -1 is returned.

* **Parameters:**
  * **string** (*string*) – the input string
  * **substring** (*string*) – the string to look for
  * **offset** (*number*) – the offset from the start
* **Returns:**
  the position where substring is found or -1
* **Return type:**
  number

<a id="str_lower"></a>

### str_lower(string)

Returns string with all US-ASCII characters lowercased.

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string lowercased
* **Return type:**
  string

<a id="str_upper"></a>

### str_upper(string)

Returns string with all US-ASCII characters uppercased.

* **Parameters:**
  **string** (*string*) – the input string
* **Returns:**
  the string uppercased
* **Return type:**
  string

<a id="str_slice"></a>

### str_slice(string, offset[, length])

Return the substring of string.

* **Parameters:**
  * **string** (*string*) – the input string
  * **offset** (*number*) – the start position
  * **length** (*number*) – the length limit if given
* **Returns:**
  the substring
* **Return type:**
  string

> **See also**
> 
> It’s significantly faster to use the slice `[:]` operator since it’s an operator and not a function.

<a id="str_strip"></a>

### str_strip(string[, characters])

Returns string with whitespace strip characters (`\s\t\r\n`) removed from the start and end of the string.

* **Parameters:**
  * **string** (*string*) – the input string
  * **characters** (*string*) – the strip characters
* **Returns:**
  the trimmed string
* **Return type:**
  string

<a id="str_lstrip"></a>

### str_lstrip(string[, characters])

Returns string with whitespace strip characters (`\s\t\r\n`) removed from the start of the string.

* **Parameters:**
  * **string** (*string*) – the input string
  * **characters** (*string*) – the strip characters
* **Returns:**
  the trimmed string
* **Return type:**
  string

<a id="str_rstrip"></a>

### str_rstrip(string[, characters])

Returns string with whitespace strip characters (`\s\t\r\n`) removed from the end of the string.

* **Parameters:**
  * **string** (*string*) – the input string
  * **characters** (*string*) – the strip characters
* **Returns:**
  the trimmed string
* **Return type:**
  string

<a id="str_chunk"></a>

### str_chunk(string, length[, firstlength])

Return the string chunks into an array of strings.

* **Parameters:**
  * **string** (*string*) – the input string
  * **length** (*number*) – the length of chunks
  * **firstlength** (*number*) – the length of the first chunk
* **Returns:**
  the chunked string
* **Return type:**
  array of string

```hsl
str_chunk("xxxxxxxxx", 3) // ["xxx","xxx","xxx"]
str_chunk("xxxxxxxxx", 3, 1) // ["x","xxx","xxx", "xx"]
```

<a id="regular-expression"></a>

## Regular expression

<a id="pcre_match"></a>

### pcre_match(pattern, subject)

PCRE matching in subject.

* **Parameters:**
  * **pattern** ([Regex](literals.html.md#regextype) or string) – the regular expression
  * **subject** (*string*) – the string to match against
* **Returns:**
  returns matches, if no result is found an empty array is returned.
* **Return type:**
  array

Perl compatible regular expression data matching and extraction, requires capture groups. All modifiers supported by `=~` operator are available.

> **Note**
> 
> Use [raw strings](literals.html.md#rawstring) so you don’t have to escape the pattern.

> **See also**
> 
> For matching only the [regular expression](operators.html.md#regex) operator can be used.

<a id="pcre_match_all"></a>

### pcre_match_all(pattern, subject)

The implementation is identical to [`pcre_match()`](#pcre_match) except the return type.

* **Parameters:**
  * **pattern** ([Regex](literals.html.md#regextype) or string) – the regular expression
  * **subject** (*string*) – the string to match against
* **Returns:**
  returns multiple results group by capture groups, and matched result.
* **Return type:**
  array

<a id="pcre_quote"></a>

### pcre_quote(string)

Quote all metacharacters which has special meaning in a regular expression.

* **Parameters:**
  **string** (*string*) – the string
* **Returns:**
  a quoted string
* **Return type:**
  string

<a id="pcre_compile"></a>

### pcre_compile(string)

Pre-compile a regex to a regular expression object.

* **Parameters:**
  **string** (*string*) – the regular expression
* **Returns:**
  a regex object
* **Return type:**
  [Regex](literals.html.md#regextype)

<a id="pcre_replace"></a>

### pcre_replace(pattern, replace, subject[, limit = 0])

Perl compatible regular expression data matching and replacing.

* **Parameters:**
  * **pattern** ([Regex](literals.html.md#regextype) or string) – the regular expression to match
  * **replace** (*function* *or* *string*) – the pattern to replace as string or a callback function
  * **subject** (*string*) – the string acted upon
  * **limit** (*number*) – max occurrences to replace (*0* equals *unlimited*)
* **Returns:**
  return subject with the replacements done
* **Return type:**
  string

In *replace* matches are available using `$0` to `$n`. `$0` will be the entire match, and `$1` (and forward) each match group.

The replace function should take one argument (array of values `[$0, $n...]`) and return a string value.

```hsl
echo pcre_replace("\\[link](.*?)\\[/link]",
        "<a href=\"$1\">$1</a>",
                        "[link]http://halon.se[/link]");
// <a href="http://halon.se">http://halon.se</a>

echo pcre_replace("\\d", "($0)", "foo1bar2baz");
// foo(1)bar(2)baz

// "ucfirst()"
echo pcre_replace(''\b[a-z]'', function ($i) { return str_upper($i[0]); }, "hello world");
// Hello World
```

<a id="socket"></a>

## Socket

<a id="Socket"></a>

### *class* Socket

This class allows POSIX like socket(2) code. A socket resource is created for each Socket instance, this resource is automatically garbage collected (closed) once the object is destroyed.

<a id="Socket.constructor"></a>

#### constructor(family, type)

* **Parameters:**
  * **family** (*string*) – address family either `AF_INET`, `AF_INET6` or `AF_UNIX`
  * **type** (*string*) – socket type either `SOCK_STREAM` (TCP) or `SOCK_DGRAM` (UDP)

```hsl
$socket = Socket("AF_INET", "SOCK_STREAM");
$socket->close();

$socket2 = Socket(Socket::AF($address), "SOCK_STREAM");
$socket2->close();
```

<a id="Socket.bind"></a>

#### bind(address[, port[, options]])

Bind the socket to *address* and *port*. The address must match the Sockets address family. On error `none` is returned.

* **Parameters:**
  * **address** (*string*) – address to bind
  * **port** (*number*) – port to bind
  * **options** (*array*) – options array
* **Returns:**
  this
* **Return type:**
  [`Socket`](#Socket) or none

The following options are available in the options array.

> * **nonlocal** (boolean) Allow binding of a nonlocal source address (BINDANY). The default is `false`.

<a id="Socket.close"></a>

#### close()

Close the socket and destroy the internal socket resource. On error `none` is returned.

* **Returns:**
  this
* **Return type:**
  [`Socket`](#Socket) or none

> **Note**
> 
> Sockets are automatically garbage collected (closed). However you may want to explicitly call close.

<a id="Socket.connect"></a>

#### connect(address[, port])

Connect the socket to *address* and *port*. The address must match the Sockets address family. On error `none` is returned.

* **Parameters:**
  * **address** (*string*) – address to connect to
  * **port** (*number*) – port to connect to
* **Returns:**
  this
* **Return type:**
  [`Socket`](#Socket) or none

<a id="Socket.errno"></a>

#### errno()

Get the latest errno returned from the underlying POSIX socket API.

* **Returns:**
  errno
* **Return type:**
  number

<a id="Socket.recv"></a>

#### recv(length[, flags])

Receive data on socket. On error `none` is returned.

* **Parameters:**
  * **length** (*number*) – up to length bytes to receive (max 65536)
  * **flags** (*array*) – flags to control the behaviour
* **Returns:**
  data
* **Return type:**
  string or none

Flags may be any of, the default is no POSIX recv(3) flag. If multiple flags are given in the array, they are bitwise OR-ed.

| Name         | Behaviour                      |
|--------------|--------------------------------|
| MSG_PEEK     | peek at incoming message       |
| MSG_WAITALL  | wait for full request or error |
| MSG_DONTWAIT | do not block                   |

<a id="Socket.send"></a>

#### send(data)

Send data on socket. On error `none` is returned.

* **Parameters:**
  **data** (*string*) – data to send
* **Returns:**
  bytes sent
* **Return type:**
  number or none

<a id="Socket.settimeout"></a>

#### settimeout(timeout)

Set the timeout for socket operations.

* **Parameters:**
  **timeout** (*number*) – timeout in seconds. The default is no timeout.
* **Returns:**
  this
* **Return type:**
  [`Socket`](#Socket)

<a id="Socket.shutdown"></a>

#### shutdown(how)

Shutdown the socket for receiving, sending or both. On error `none` is returned.

* **Parameters:**
  **how** (*string*) – how to shutdown either `SHUT_RD`, `SHUT_WR` or `SHUT_RDWR`.
* **Returns:**
  this
* **Return type:**
  [`Socket`](#Socket) or none

> **Note**
> 
> Sockets are automatically closed.

<a id="Socket.toFFIValue"></a>

#### toFFIValue()

Return the file descriptor representing the current socket. On error `none` is returned.

* **Returns:**
  An FFIValue of sint32 type
* **Return type:**
  [`FFIValue`](#FFIValue) or none

> **Note**
> 
> The returned file descriptor must not be closed.

<a id="Socket.AF"></a>

#### *static* AF(address)

Return the AF family of an address (either `AF_INET` or `AF_INET6`). A utility function helpful when constructing a [`Socket`](#Socket) class. On error `none` is returned.

* **Parameters:**
  **address** (*string*) – address
* **Returns:**
  AF family
* **Return type:**
  string or none

<a id="Socket.Resource"></a>

#### *static* Resource(socket)

Return a Socket object from a SocketResource.

* **Parameters:**
  **socket** (*SocketResource*) – a SocketResource
* **Returns:**
  A Socket resource
* **Return type:**
  [`Socket`](#Socket) or none

<a id="TLSSocket"></a>

### *class* TLSSocket

This class allows OpenSSL like SSL(3) code. The TLSSocket class takes a connected [`Socket`](#Socket) instance (SOCK_STREAM) and encapsulates any read and writes in TLS/SSL.

<a id="TLSSocket.constructor"></a>

#### constructor(socket, options)

* **Parameters:**
  * **socket** ([*Socket*](#Socket)) – a socket
  * **options** (*array*) – options array

The following options are available in the options array.

> * **tls_protocols** (string) Use one or many of the following TLS protocols; `SSLv2`, `SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2` or `TLSv1.3`. Protocols may be separated by `,` and excluded by `!`. The default is `!SSLv2,!SSLv3`.
> * **tls_ciphers** (string) List of ciphers to support. The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_ciphersuites** (string) List of TLS ciphersuites to support (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_groups** (string) List of TLS groups to offer for TLS key exchange. (TLSv1.3). The default is decided by OpenSSL for each `tls_protocol`.
> * **tls_verify_name** (array) Hostnames to verify against the certificate’s CN and SAN (NO_PARTIAL_WILDCARDS | SINGLE_LABEL_SUBDOMAINS).
> * **tls_verify_ca** (boolean) Verify certificate against known CAs. The default is `false`.
> * **tls_sni** (string) Request a certificate using the SNI extension. The default is not to use SNI.
> * **tls_client_cert** (array or string) If given as an associative array it should include a `x509` (*X509Resource*), `privatekey` (`*PrivateKeyResource`) and optionally a `chain` (*array*) of *X509Resources*. If given as a string use the following id of a certificate in the configuration as client certificate. The default is to not send a client certificate.

> **Note**
> 
> By default, no certificate nor hostname validation is done.

<a id="TLSSocket.handshake"></a>

#### handshake()

Perform the TLS/SSL handshake. If the handshake fails or the validation fails `none` is returned.

* **Returns:**
  this
* **Return type:**
  [`TLSSocket`](#TLSSocket) or none

<a id="TLSSocket.recv"></a>

#### recv(length)

Receive data on TLS/SSL socket. This function may perform an implicit handshake. On error `none` is returned.

* **Parameters:**
  **length** (*number*) – up to length bytes to receive (max 65536)
* **Returns:**
  data
* **Return type:**
  string or none

<a id="TLSSocket.send"></a>

#### send(data)

Send data on TLS/SSL socket. This function may perform an implicit handshake. On error `none` is returned.

* **Parameters:**
  **data** (*string*) – data to send
* **Returns:**
  bytes sent
* **Return type:**
  number or none

<a id="TLSSocket.shutdown"></a>

#### shutdown()

Shut down the TLS/SSL connection. This function may need to be called multiple times. See SSL_shutdown(3) for details. On error `none` is returned.

* **Returns:**
  shutdown status
* **Return type:**
  number or none

<a id="TLSSocket.errno"></a>

#### errno()

Get the latest errno returned from the underlying OpenSSL SSL(3) socket API.

* **Returns:**
  errno
* **Return type:**
  number

<a id="TLSSocket.getpeerx509"></a>

#### getpeerx509()

Get the peer certificate (X.509) as a [`X509`](#X509) instance. On error `none` is returned.

* **Returns:**
  The peer certificate
* **Return type:**
  [`X509`](#X509) or none

<a id="TLSSocket.toSocket"></a>

#### toSocket()

Return a [`Socket`](#Socket) class for the current TLSSocket object (upcast).

* **Returns:**
  A Socket class for the current TLSSocket object.
* **Return type:**
  [`Socket`](#Socket)

<a id="X509"></a>

### *class* X509

This class allows you to parse an X509 resource. The X509 class takes a *X509Resource*.

<a id="X509.constructor"></a>

#### constructor(x509resource)

* **Parameters:**
  **x509resource** (*X509Resource*) – a X509Resource

<a id="X509.subject"></a>

#### subject()

The subject of the certificate. The first field in the tuple is the name (eg. CN, OU) and the second is the value.

* **Returns:**
  The subject
* **Return type:**
  array of [string, string]

<a id="X509.issuer"></a>

#### issuer()

The issuer of the certificate. The first field in the tuple is the name (eg. CN, OU) and the second is the value.

* **Returns:**
  The issuer
* **Return type:**
  array of [string, string]

<a id="X509.subject_alt_name"></a>

#### subject_alt_name()

The subject alt names (DNS) items

* **Returns:**
  The SAN
* **Return type:**
  array

<a id="X509.version"></a>

#### version()

The version of the X.509 certificate

* **Returns:**
  The version
* **Return type:**
  number

<a id="X509.serial_number"></a>

#### serial_number()

The serial number in HEX

* **Returns:**
  The serial
* **Return type:**
  string

<a id="X509.not_valid_before"></a>

#### not_valid_before()

The start date of the certificate (in unix time)

* **Returns:**
  The certificate start date
* **Return type:**
  number

<a id="X509.not_valid_after"></a>

#### not_valid_after()

The end date of the certificate (in unix time)

* **Returns:**
  The certificate end date
* **Return type:**
  number

<a id="X509.public_key"></a>

#### public_key([options])

Export the public key in binary DER format (default) or in PEM format.

* **Parameters:**
  **options** (*array*) – options array
* **Returns:**
  The public key
* **Return type:**
  string

The following options are available in the options array.

> * **pem** (boolean) Export the public key in PEM format. The default is `false`.

<a id="X509.verify"></a>

#### verify(calist[, intermediates[, revokelist]])

Verify the certificate against a list of CA’s (with optional intermediate certificates).

* **Parameters:**
  * **calist** (*array*) – array of X509
  * **intermediates** (*array*) – array of X509
  * **revokelist** (*array*) – array of X509CRL
* **Returns:**
  The verification result
* **Return type:**
  array

The return value is an associative arrays with `result` (boolean) or `error` (string), `errno` (number) and `depth` (number). For details see OpenSSL’s `X509_verify_cert` and `X509_STORE_CTX_get_error`.

```hsl
if ($c->verify($calist)["result"])
 echo "ok";
```

<a id="X509.chain"></a>

#### chain(calist[, intermediates[, options]])

Resolve a chain from the X509 to the calist root (if not none), with the longest intermediates chain that can be built.

* **Parameters:**
  * **calist** (*array*) – array of X509 or none
  * **intermediates** (*array*) – array of X509
  * **options** (*array*) – options array
* **Returns:**
  The chain
* **Return type:**
  array

The following options are available in the options array.

> * **selfsigned** (boolean) Include selfsigned certificate in the chain (often the CA trust). The default is `false`.

The return value is an associative arrays with either `error` (string) or an array `result` of X509 certificates.

```hsl
if ($c->chain($calist)["result"])
 echo "ok";
```

<a id="X509.export"></a>

#### export([options])

Export the certificate in binary DER format (default) or in PEM format.

* **Parameters:**
  **options** (*array*) – options array
* **Returns:**
  The certificate
* **Return type:**
  string

The following options are available in the options array.

> * **pem** (boolean) Export the X.509 in PEM format. The default is `false`.

```hsl
// SHA256 fingerprint
echo sha2($c->export(), 256);
```

<a id="X509.extensions"></a>

#### extensions([options])

Return all extensions in the certificate.

* **Parameters:**
  **options** (*array*) – options array
* **Returns:**
  List of extensions
* **Return type:**
  array

The following options are available in the options array.

> * **text** (boolean) Decode known extensions to friendly text. The default is `false`.

The return value is an array of associative arrays with `oid`, `name`, `critical`, `value` and optionally `text`.

```hsl
echo $c->extensions(["text" => true]); // [0=>["oid"=>"2.5.29.19","name"=>"basicConstraints","critical"=>false,"value"=>"...","text"=>"CA:FALSE"]]
```

<a id="X509.toResource"></a>

#### toResource()

Return the objects X509 resource.

* **Returns:**
  The internal X509 resource
* **Return type:**
  `X509Resource`

<a id="X509.toFFIValue"></a>

#### toFFIValue()

Return a pointer to a [OpenSSL X509](https://www.openssl.org/docs/man1.1.1/man7/x509.html) object representing the current X509 resource.

* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue)

> **Note**
> 
> The X509 pointer must not be deleted.
> 
> ```c
> #include <openssl/x509.h>
> 
> void processx509(X509* x509) {
> }
> ```

<a id="X509.String"></a>

#### *static* String(data[, options])

Return a X509 resource containing the data.

* **Parameters:**
  * **data** (*string*) – the content
  * **options** (*array*) – options array
* **Returns:**
  A X509 resource
* **Return type:**
  [`X509`](#X509)

The following options are available in the options array.

> * **pem** (boolean) The X.509 in PEM format. The default is `false` (DER).
> * **multiple** (boolean) Import multiple X509 certificates as an array. This option changes the return value to an array of X509 resources. The default is `false`.

<a id="is_x509_resource"></a>

### is_x509_resource(resource)

Return a true if resource is a X509 resource.

* **Parameters:**
  **resource** (*any*) – the resource
* **Returns:**
  if the argument is X509 resource
* **Return type:**
  boolean

<a id="X509CRL"></a>

### *class* X509CRL

This class allows you to parse an X509 Certificate Revocation List resource. The X509CRL class takes a *X509CRLResource*.

<a id="X509CRL.constructor"></a>

#### constructor(x509CRLresource)

* **Parameters:**
  **x509CRLresource** (*X509CRLResource*) – a X509CRLResource

<a id="X509CRL.issuer"></a>

#### issuer()

The issuer of the CRL. The first field in the tuple is the name (eg. CN, OU) and the second is the value.

* **Returns:**
  The issuer
* **Return type:**
  array of [string, string]

<a id="X509CRL.revoked"></a>

#### revoked()

Get the list of revoked CRL, the `serial_number` and `reason`.

* **Returns:**
  The revoked certificates
* **Return type:**
  array of array

<a id="X509CRL.version"></a>

#### version()

The version of the X.509 CRL

* **Returns:**
  The version
* **Return type:**
  number

<a id="X509CRL.last_update"></a>

#### last_update()

The last update date of the CRL (in unix time)

* **Returns:**
  The last update date
* **Return type:**
  number

<a id="X509CRL.next_update"></a>

#### next_update()

The next update date of the CRL (in unix time)

* **Returns:**
  The next update date
* **Return type:**
  number

<a id="X509CRL.export"></a>

#### export([options])

Export the CRL in binary DER format (default) or in PEM format.

* **Parameters:**
  **options** (*array*) – options array
* **Returns:**
  The CRL
* **Return type:**
  string

The following options are available in the options array.

> * **pem** (boolean) Export the X.509 CRL in PEM format. The default is `false`.

```hsl
// SHA256 fingerprint
echo sha2($c->export(), 256);
```

<a id="X509CRL.extensions"></a>

#### extensions([options])

Return all extensions in the CRL.

* **Parameters:**
  **options** (*array*) – options array
* **Returns:**
  List of extensions
* **Return type:**
  array

The following options are available in the options array.

> * **text** (boolean) Decode known extensions to friendly text. The default is `false`.

The return value is an array of associative arrays with `oid`, `name`, `critical`, `value` and optionally `text`.

```hsl
echo $c->extensions(["text" => true]); // [0=>["oid"=>"2.5.29.19","name"=>"basicConstraints","critical"=>false,"value"=>"...","text"=>"CA:FALSE"]]
```

<a id="X509CRL.toResource"></a>

#### toResource()

Return the objects X509CRL resource.

* **Returns:**
  The internal X509CRL resource
* **Return type:**
  `X509CRLResource`

<a id="X509CRL.String"></a>

#### *static* String(data[, options])

Return a X509CRL resource containing the data.

* **Parameters:**
  * **data** (*string*) – the content
  * **options** (*array*) – options array
* **Returns:**
  A X509CRL resource
* **Return type:**
  [`X509CRL`](#X509CRL)

The following options are available in the options array.

> * **pem** (boolean) The X.509 CRL in PEM format. The default is `false` (DER).
> * **multiple** (boolean) Import multiple X509 CRL as an array. This option changes the return value to an array of X509CRL resources. The default is `false`.

<a id="is_x509crl_resource"></a>

### is_x509crl_resource(resource)

Return a true if resource is a X509 resource.

* **Parameters:**
  **resource** (*any*) – the resource
* **Returns:**
  if the argument is X509 resource
* **Return type:**
  boolean

<a id="ffi"></a>

## FFI

The foreign function interface (FFI) enables loading of shared libraries following C interface calling conventions. The FFI interface has its own types (C types) and memory. It’s very easy to crash the Halon script engine if not used properly. The FFI feature is not enabled by default and needs to be enabled in the .yaml configuration for each program.

<a id="FFI"></a>

### *class* FFI

This class allows you to load a shared object/library.

<a id="FFI.constructor"></a>

#### constructor(path)

* **Parameters:**
  **path** (*string*) – a library (eg. libc.so.7)

```hsl
$libc = FFI("libc.so.7");
```

<a id="FFI.func"></a>

#### func(name, arguments, returntype)

The name of the function to load, use [`FFI.type()`](#FFI.type) to define the correct function signature. If the function is not found, `none` is returned.

* **Parameters:**
  * **name** (*string*) – the function name
  * **arguments** (*FFIType*) – the list of argument types
  * **returntype** (*FFIType*) – the return type
* **Returns:**
  A function object
* **Return type:**
  [`FFIFunction`](#FFIFunction) or none

```hsl
$malloc = $libc->func("malloc", [ FFI::type("uint64") ], FFI::type("pointer"));
$free = $libc->func("free", [ FFI::type("pointer") ], FFI::type("void"));
$printf = $libc->func("printf", [ FFI::type("pointer"), FFI::type("...") ], FFI::type("sint32")); // variadic
```

The `...` type prepresents functions having a variadic arguments list. All values in the variadic arguments list must have an explicit type since they are unknown in the function definition.

<a id="FFI.symbol"></a>

#### symbol(name)

Return a pointer to a global symbol in the library (eg. a variable). This function is the equivalent of dlsym(2). If the symbol is not found, `none` is returned.

* **Parameters:**
  **name** (*string*) – a symbol name
* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue) or none

<a id="FFI.type"></a>

#### *static* type(name)

A factory function for FFI types. This function is usually used to declare the function signature of an [`FFIFunction`](#FFIFunction).

* **Parameters:**
  **name** (*string*) – a type name
* **Returns:**
  An FFI type
* **Return type:**
  [`FFIType`](#FFIType)

The following types are available.

* `void` (can only be used as return value)
* `uint8`, `sint8`, `uint16`, `sint16`, `uint32`, `sint32`, `uint64`, `sint64`
* `float`, `double`
* `pointer`
* `...` (can only be used as function argument)

<a id="FFI.cnumber"></a>

#### *static* cnumber(type, number)

Create an [`FFIValue`](#FFIValue) containing a C number. It’s a basic type, which exists for the lifetime of the returned value and passed by value.

* **Parameters:**
  * **type** (*FFIType*) – an FFI C number type
  * **number** (*number*) – a number
* **Returns:**
  An FFI value
* **Return type:**
  [`FFIValue`](#FFIValue)

The following FFI number types are available:

* `uint8`, `sint8`, `uint16`, `sint16`, `uint32`, `sint32`, `uint64`, `sint64`, `float`, `double`

```hsl
$malloc = $libc->func("malloc", [ FFI::type("uint64") ], FFI::type("pointer"));
$ptr = $malloc(FFI::cnumber(FFI::type("uint64"), 32));
```

<a id="FFI.cstring"></a>

#### *static* cstring(value)

Allocate a null-terminated C string (`char *`) in memory from a HSL string and return an [`FFIValue`](#FFIValue) of `pointer` type pointing to that memory. This memory is owned by the [`FFIValue`](#FFIValue) resource (use the [`FFI.detach()`](#FFI.detach) function to disclaim ownership). This function is intentionally not binary safe.

* **Parameters:**
  **value** (*string*) – a string
* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue)

```hsl
$fopen = $libc->func("fopen", [ FFI::type("pointer"), FFI::type("pointer") ], FFI::type("pointer"));
$fp = $fopen(FFI::cstring("/dev/zero"), FFI::cstring("r"));
```

<a id="FFI.callback"></a>

#### *static* callback(arguments, returntype, callback)

Allocate a FFI callback function and return a [`FFIValue`](#FFIValue) of `pointer` type pointing to that function. This pointer can be passed a pointer to a FFI function taking a C function pointer. This memory is owned by the [`FFIValue`](#FFIValue) resource (use the [`FFI.detach()`](#FFI.detach) function to disclaim ownership). The callback function argument will be FFI types and the return type needs to be of FFI type as well.

* **Parameters:**
  * **arguments** (*FFIType*) – the list of argument types
  * **returntype** (*FFIType*) – the return type
  * **callback** (*function*) – a callback function
* **Returns:**
  An FFIValue of pointer type pointing to a C function callback
* **Return type:**
  [`FFIValue`](#FFIValue)

```hsl
$math = $lib->func("math", [ FFI::type("pointer"), FFI::type("sint32"), FFI::type("sint32") ], FFI::type("sint32"));
$cb = FFI::callback([ FFI::type("sint32"), FFI::type("sint32") ], FFI::type("sint32"), function ($a, $b) {
            return FFI::cnumber(FFI::type("sint32"), FFI::number($a) * FFI::number($b));
      });
echo FFI::number($math($cb, 10, 5));
```

For the corresponding C library function

```c
typedef int (*mathcb)(int, int);
extern "C" int math(mathcb cb, int a, int b) {
      return cb(a, b);
}
```

<a id="FFI.nullptr"></a>

#### *static* nullptr()

Create an [`FFIValue`](#FFIValue) containing a NULL pointer.

* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue)

> **Note**
> 
> The C equivalent of this function is `NULL`.

<a id="FFI.allocate"></a>

#### *static* allocate(size)

Allocate memory of *size* in bytes and return an [`FFIValue`](#FFIValue) of `pointer` type pointing to that memory. This memory is owned by the [`FFIValue`](#FFIValue) resource (use the [`FFI.detach()`](#FFI.detach) function to disclaim ownership). The memory is initially filled with zeros.

* **Parameters:**
  **size** (*any*) – the memory size in bytes
* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue)

> **Note**
> 
> The C equivalent of this function is `malloc(size)` with a `memset(pointer, size, 0)`.

<a id="FFI.memcpy"></a>

#### *static* memcpy(pointer, data)

Copy the binary content of (string) data into memory location pointed to by an [`FFIValue`](#FFIValue) of `pointer` type. The caller must make sure the pointer location is of sufficient length.

* **Parameters:**
  * **pointer** (*FFIValue*) – an FFIValue of pointer type
  * **data** (*string*) – the data to copied
* **Returns:**
  An FFIValue
* **Return type:**
  [`FFIValue`](#FFIValue)

> **Note**
> 
> The C equivalent of this function is `memcpy(pointer, data, datalen)`.

<a id="FFI.byref"></a>

#### *static* byref(value)

Return an [`FFIValue`](#FFIValue) of `pointer` type pointing to the [`FFIValue`](#FFIValue) *value*.

* **Parameters:**
  **value** (*FFIValue*) – an FFI value
* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue)

> **Note**
> 
> The C equivalent of this function is `&value`.

<a id="FFI.deref"></a>

#### *static* deref(value[, type])

Return an [`FFIValue`](#FFIValue) with [`FFIType`](#FFIType) of *type* with the value at the address pointed at by the [`FFIValue`](#FFIValue) value. The default type is `pointer`. If the type is a pointer and dereferenced pointer points to NULL then `none` is returned.

* **Parameters:**
  * **value** (*FFIValue*) – an FFI value
  * **type** (*FFIType*) – an FFI type
* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue) or none

> **Note**
> 
> The C equivalent of this function is `*value`.

<a id="FFI.offset"></a>

#### *static* offset(pointer, offset)

Return a new [`FFIValue`](#FFIValue) of `pointer` type pointing the same memory with an offset.

* **Parameters:**
  * **pointer** (*FFIValue*) – an FFI value of pointer type
  * **offset** (*number*) – the offset in bytes
* **Returns:**
  An FFIValue of pointer type
* **Return type:**
  [`FFIValue`](#FFIValue)

> **Note**
> 
> The C equivalent of this function is `pointer + 32`.

<a id="FFI.string"></a>

#### *static* string(pointer[, size])

Copy the binary content of a memory location pointed to by an [`FFIValue`](#FFIValue) of `pointer` type to a HSL string. If the size is omitted the memory will be copied up to the first NULL character as a null-terminated C string (`char *`).

* **Parameters:**
  * **pointer** (*FFIValue*) – an FFI value of pointer type
  * **size** (*number*) – bytes to copy
* **Returns:**
  A binary safe string
* **Return type:**
  string

<a id="FFI.number"></a>

#### *static* number(value)

Convert an FFI value to a HSL number. The number type can safely represent all integers between  *+/-9007199254740991* (the equivalent of `(2 ** 53) - 1`). If you expect to work with greater numbers use [`FFI.number64()`](#FFI.number64).

* **Parameters:**
  **value** (*FFIValue*) – an FFI value
* **Returns:**
  A number
* **Return type:**
  number

<a id="FFI.number64"></a>

#### *static* number64(value)

Convert an FFI value (`uint64`, `sint64` or `pointer`) to a pair of two 32 bit integers ([high, low]). For signed negative numbers a two complement representation is used.

* **Parameters:**
  **value** (*FFIValue*) – an FFI value
* **Returns:**
  A number pair
* **Return type:**
  array of number

<a id="FFI.attach"></a>

#### *static* attach(pointer[, destructor])

Assign the ownership of the data pointed to by the pointer argument ([`FFIValue`](#FFIValue) of `pointer` type). The default destructor is *free*. An optional destructor [`FFIFunction`](#FFIFunction) (should have one `pointer` argument) may be given.

* **Parameters:**
  * **pointer** (*FFIValue*) – an FFIValue of pointer type
  * **destructor** (*FFIFunction*) – a destructor function
* **Returns:**
  The pointer argument
* **Return type:**
  [`FFIValue`](#FFIValue)

```hsl
$fopen = $libc->func("fopen", [ FFI::type("pointer"), FFI::type("pointer") ], FFI::type("pointer"));
$fclose = $libc->func("fclose", [ FFI::type("pointer") ], FFI::type("void"));
$fp = FFI::attach($fopen->call("/dev/zero", "r"), $fclose);
```

<a id="FFI.detach"></a>

#### *static* detach(pointer)

Remove the ownership of the data pointed to by the pointer argument ([`FFIValue`](#FFIValue) of `pointer` type).

* **Parameters:**
  **pointer** (*FFIValue*) – an FFI value of pointer type
* **Returns:**
  The pointer argument
* **Return type:**
  [`FFIValue`](#FFIValue)

<a id="FFIFunction"></a>

### FFIFunction(...args)

A callable Function object of type FFIFunction.

* **Parameters:**
  **args** (*FFIValue*) – FFIValues or a HSL value
* **Returns:**
  Return value of function call
* **Return type:**
  [`FFIValue`](#FFIValue) or none (for `void` or a `pointer` returning *NULL*)

Implicit conversion can be made if the function signature has once of the following types and the argument HSL type match. Note that the lifetime of converted values are for the duration of the function call.

> | Declaration type   | HSL type   | Conversion                                                     |
> |--------------------|------------|----------------------------------------------------------------|
> | `pointer`          | String     | [`FFI.cstring()`](#FFI.cstring) |
> | `pointer`          | None       | [`FFI.nullptr()`](#FFI.nullptr) |
> | *any number*       | Number     | Be causes of value truncations                                 |
> | `...`              | FFIValue   | Argument must be of explicit type                              |

```hsl
$fopen = $libc->func("fopen", [ FFI::type("pointer"), FFI::type("pointer") ], FFI::type("pointer"));
$fp1 = $fopen(FFI::cstring("/dev/zero"), FFI::cstring("r"));
$fp2 = $fopen("/dev/zero", "r"); // implicit conversion
$printf("%s %zu\n", FFI::cstring("hello"), FFI::cnumber(FFI::type("uint64"), 123));
```

<a id="FFIType"></a>

### FFIType

An FFIType resource holds information about a function signature.

The following types are available.

> * `void` (can only be used as return value)
> * `uint8`, `sint8`, `uint16`, `sint16`, `uint32`, `sint32`, `uint64`, `sint64`
> * `float`, `double`
> * `pointer`
> * `...` (can only be used as function argument)

<a id="FFIValue"></a>

### FFIValue

An FFIValue resource is a container for an FFI value (it also contains the FFIType) so that the correct conversions can be made. If the value is of a pointer type you may control the lifetime of the object using the [`FFI.attach()`](#FFI.attach) and [`FFI.detach()`](#FFI.detach) functions.

<a id="shared-memory"></a>

<a id="id5"></a>

## Shared memory

The memory function API provides shared, atomic and synchronized memory access between parallel script executions within the same program. The memory resides in runtime memory (heap) hence it is automatically cleared upon program restart. Access to this memory is also available through the protobuf control socket API. The memory functions share the same memory and lock as the [barrier](structures.html.md#barrier) structure.

<a id="memory_add"></a>

### memory_add(key, value)

Adds the value to the store, but only if the key doesn’t already exist.

* **Parameters:**
  * **key** (*string*) – the key name
  * **value** (*any*) – the value
* **Returns:**
  if the value was added
* **Return type:**
  boolean

<a id="memory_dec"></a>

### memory_dec(key[, offset=1, remove_if_zero=false])

Decrements a number value in the store. If the key doesn’t exist, it’s created and the value is initialized to 0 before the decrement. If the value is not a number, this function fail and will return *none*.

* **Parameters:**
  * **key** (*string*) – the key name
  * **offset** (*number*) – the offset to decrement
  * **remove_if_zero** (*boolean*) – remove key if number reaches zero
* **Returns:**
  the decremeted value
* **Return type:**
  number or none

<a id="memory_delete"></a>

### memory_delete(key[, callback])

Deletes a key from the store. If the key existed, the callback (if provided) will be called with the key and value as arguments.

* **Parameters:**
  * **key** (*string*) – the key name
  * **callback** (*function*) – a callback function
* **Returns:**
  if the key was removed
* **Return type:**
  boolean

<a id="memory_exists"></a>

### memory_exists(key[, callback])

Checks if a key in the store exists. If the key exists the callback (if provided) will be called with the key and value as arguments.

* **Parameters:**
  * **key** (*string*) – the key name
  * **callback** (*function*) – a callback function
* **Returns:**
  if the key exists
* **Return type:**
  boolean

<a id="memory_fetch"></a>

### memory_fetch(key[, callback])

Returns the value of a key in the store. If the entry doesn’t exist and no callback is provided, `none` will be returned. If the entry doesn’t exist and a callback is provided, it will be called with the key as argument, and the return value of the callback will be used as return value for this function.

* **Parameters:**
  * **key** (*string*) – the key name
  * **callback** (*function*) – a callback function
* **Returns:**
  the value of key
* **Return type:**
  any

```hsl
// fetch or create+fetch
echo memory_fetch("x", function ($k) {
        $v = 123;
        memory_store("x", $v);
        return $v;
    });
```

> **Note**
> 
> Since this function may return `none` if the key doesn’t exist, it’s not possible to differentiate between keys with the value `none` and a non-existing key. If it’s important to differentiate between those, use [`memory_exists()`](#memory_exists) with a callback.

<a id="memory_inc"></a>

### memory_inc(key[, offset=1])

Increments a number value in the store. If the key doesn’t exist, it’s created and the value is initialized to 0 before the increment. If the value is not a number, this function fail and will return *none*.

* **Parameters:**
  * **key** (*string*) – the key name
  * **offset** (*number*) – the offset to increment
* **Returns:**
  the incremeted value
* **Return type:**
  number or none

<a id="memory_store"></a>

### memory_store(key, value[, callback])

Update or create the value of key in the store. If the key exists, the callback (if provided) will be called with the key and the current value as arguments in order to know what value was overwritten.

* **Parameters:**
  * **key** (*string*) – the key name
  * **value** (*any*) – the value
  * **callback** (*function*) – a callback function
* **Returns:**
  if the key exists
* **Return type:**
  boolean

<a id="memory_update"></a>

### memory_update(key, value, callback[, initial])

Update the value of key in the store, if it exists. The return value of the callback function (called with the key, current value and value as argument) will be used as the stored value.

If the key doesn’t exist, and…

> * …no initial value is provided, no action will take place.
> * …an initial value is provided, the callback will be called with the initial value as the current value.

* **Parameters:**
  * **key** (*string*) – the key name
  * **value** (*any*) – the value
  * **callback** (*function*) – a callback function
  * **initial** (*any*) – an initial value
* **Returns:**
  if the key exists
* **Return type:**
  boolean

```hsl
// append items to an array (create the array if it doesn't exist)
memory_update("list", "item", function ($k, $c, $v) {
    $c[] = $v;
    return $c;
}, []);

// compare-and-swap (CAS) example between 3 and 5
$swapped = false;
if (memory_update("x", 5, function ($k, $c, $v) closure ($swapped) {
        if ($c != 3) return $c;
        $swapped = true;
        return $v;
    }) and $swapped)
{
    echo "swapped";
}
```

<a id="server"></a>

<a id="id6"></a>

## Server

<a id="server_concurrency"></a>

### server_concurrency(serverid[, address])

Return the current server concurrency for a specific IP or network.

* **Parameters:**
  * **serverid** (*string*) – the serverid name
  * **address** (*string*) – the address (may be IP or a network)
* **Returns:**
  concurrency if successful
* **Return type:**
  number or none

```hsl
// Block if concurrency > 5
$concurrency = server_concurrency($arguments["serverid"], $arguments["remoteip"]);
if (is_number($concurrency) and $concurrency > 5)
    Reject("Too many concurrent connections");
```

<a id="queue"></a>

<a id="id7"></a>

## Queue

<a id="queue_suspend"></a>

### queue_suspend(fields, ttl[, options])

Add a dynamic queue pickup suspend for the following fields, this will cause no more messages matching this condition to be picked up for delivery during the ttl of the suspend. If a matching suspend already exists only the TTL is updated. On error `none` is returned.

* **Parameters:**
  * **fields** (*array*) – fields array
  * **ttl** (*number*) – ttl in seconds
  * **options** (*array*) – options array
* **Return type:**
  array

The following fields are available in the fields array.

> * **transportid** (string) Transport ID
> * **localip** (string) Local IP
> * **remoteip** (string) Remote IP
> * **remotemx** (string) Remote MX
> * **recipientdomain** (string) Recipient domain
> * **tenantid** (string) Tenant ID
> * **jobid** (string) Job ID
> * **grouping** (string) Grouping

The following options are available in the options array.

> * **tag** (string) Apply tag to suspend.
> * **properties** (array) List of properties to be added (associative string-string array)
> * **update** (boolean) If we should update the suspend. The default is `true`.
> * **id** (string) Set the UUID for the suspend (instead of auto-generate). If the UUID exists the policy is updated.

The return value is always an associative array with `id`.

```hsl
// Suspend matching traffic for one minute
queue_suspend(
       ["remotemx" => "*.protection.example.com"],
       60
    );
```

<a id="queue_policy"></a>

### queue_policy(fields, condition, policy, ttl[, options])

Add a dynamic queue pickup policy for the specific fields, matching a specific condition. If a matching policy (fields and condition) already exists the condition and TTL is updated. On error `none` is returned.

* **Parameters:**
  * **fields** (*array*) – fields array
  * **condition** (*array*) – condition array
  * **policy** (*array*) – policy array
  * **ttl** (*number*) – ttl in seconds
  * **options** (*array*) – options array
* **Return type:**
  array

The following field values are available in the fields array. The counter for those fields needs to exists in the policy configuration before it can have dynamic condition added to it.

> * `transportid`
> * `localip`
> * `remoteip`
> * `remotemx`
> * `recipientdomain`
> * `tenantid`
> * `jobid`
> * `grouping`

The following condition are available in the condition array.

> * **transportid** (string) Transport ID
> * **localip** (string) Local IP
> * **remoteip** (string) Remote IP
> * **remotemx** (string) Remote MX
> * **recipientdomain** (string) Recipient domain
> * **tenantid** (string) Tenant ID
> * **jobid** (string) Job ID
> * **grouping** (string) Grouping

The following policies are available in the policy array.

> * **concurrency** (number) The concurrency limit.
> * **rate** (array) The rate given as [messages, interval]. The interval is given in seconds.
> * **connectinterval** The connect interval that should be enforced, specified in seconds.
> * **properties** (array) An associative array of properties
> * **tag** (string) Tag if concurrency or rate applies.
> * **stop** (boolean) If stop-on-match should be enabled. The default is `false`.
> * **cluster** (boolean) If clustering should be enabled. The default is `true`.

The following options are available in the options array.

* **update** (boolean) If we should update the policy. The default is `true`.
* **id** (string) Set the UUID for the policy (instead of auto-generate). If the UUID exists the policy is updated.
* **type** (string) Set the policy type (`backoff`, `warmup`). The default is `dynamic`.

The return value is always an associative array with `id`.

```hsl
// Enforce a 10 messages per minute limit for an hour
queue_policy(
      ["localip", "recipientdomain"],
      ["recipientdomain" => "example.com"],
      ["rate" => [10, 60]],
      3600
    );
```

> **Note**
> 
> If you have groupings and you add a condition matching a grouping, then the condition will be applied on the grouping and not the individual item. For example if you have a grouping named `#exampleRollup` (`*.example.com`) and you add a condition for `mx1.example.com` the condition will be applied on the `#exampleRollup` grouping instead.

<a id="queue_policy_delete"></a>

### queue_policy_delete(id)

Remove the queue policy reference by the id. Return a boolean value if the policy was removed. On error `none` is returned.

* **Parameters:**
  **id** (*string*) – a queue policy id
* **Return type:**
  boolean or none

<a id="queue_quota"></a>

### queue_quota(name)

Get the usage for a specific quota. Messages may be assigned to one or more quotas when calling eg. [`eod.EODMailMessage.queue()`](eod.html.md#eod.EODMailMessage.queue) which is then incremented accordingly. When the messages is removed from the queue (delivered or not) the quota is decremented.

* **Parameters:**
  **name** (*string*) – the quota name
* **Returns:**
  the quota information
* **Return type:**
  array

The return value is always an associative array with `count` and `bytes`.

```hsl
// Enforce a limit of 1 GiB of message data in queue for a specific senderdomain
// In this example we have a made-up namespace called "senderdomain:"
// but that is not necessary
//
// Do not forget to specificying the same quota name when accepting messages
//
if (queue_quota("senderdomain:$senderdomain")["bytes"] > 1024 * 1024 * 1024)
    Defer("Too many mail in queue from $senderdomain");
```

<a id="metrics"></a>

## Metrics

<a id="metrics_increment"></a>

### metrics_increment(name, labels[, value])

Increment a metric of type gauge or counter.

* **Parameters:**
  * **name** (*string*) – the metric name
  * **labels** (*array*) – the labels (may be empty)
  * **value** (*number*) – the increment value (default 1)
* **Returns:**
  true if successful
* **Return type:**
  boolean or none

<a id="metrics_decrement"></a>

### metrics_decrement(name, labels[, value])

Decrement a metric of type gauge.

* **Parameters:**
  * **name** (*string*) – the metric name
  * **labels** (*array*) – the labels (may be empty)
  * **value** (*number*) – the decrement value (default 1)
* **Returns:**
  true if successful
* **Return type:**
  boolean or none

<a id="metrics_set"></a>

### metrics_set(name, labels, value)

Set a metric of type gauge, counter or histogram.

* **Parameters:**
  * **name** (*string*) – the metric name
  * **labels** (*array*) – the labels (may be empty)
  * **value** (*number*) – the increment value (default 1)
* **Returns:**
  true if successful
* **Return type:**
  boolean or none

<a id="metrics_get"></a>

### metrics_get(name, labels)

Get a metric of type gauge, counter or histogram.

* **Parameters:**
  * **name** (*string*) – the metric name
  * **labels** (*array*) – the labels (may be empty)
* **Returns:**
  an associative array with `value` and optionally `buckets`, none if not found
* **Return type:**
  array or none

<a id="classes"></a>

## Classes

<a id="_CPPv49Exception"></a>

<a id="_CPPv39Exception"></a>

<a id="_CPPv29Exception"></a>

<a id="Exception"></a>

### class Exception

This builtin class is used to create Exception objects. Similar to the built in exceptions [thrown](structures.html.md#throw).

<a id="Exception.constructor"></a>

#### constructor(message)

Create an instance of the Exception class.

* **Parameters:**
  **message** (*string*) – the exception message

```hsl
try {
   throw Exception("Error");
} catch ($e) {
  echo $e->toString();
}
```

<a id="Exception.toString"></a>

#### toString()

Return a user-friendly represention of the exception message including file, line or column if available.

* **Returns:**
  exception message
* **Return type:**
  string

<a id="Exception.message"></a>

#### message()

Return the error message without any additional information regarding file, line or column.

* **Returns:**
  exception message
* **Return type:**
  string

<a id="Exception.file"></a>

#### file()

Return the file which caused the exception. This function will only return the file for builin exceptions.

* **Returns:**
  file
* **Return type:**
  string or none

<a id="Exception.line"></a>

#### line()

Return the line which caused the exception. This function will only return the line for builin exceptions.

* **Returns:**
  line number
* **Return type:**
  number or none

<a id="Exception.column"></a>

#### column()

Return the column which caused the exception. This function will only return the column for builin exceptions.

* **Returns:**
  column number
* **Return type:**
  number or none
