Mappers

A mapper in Alumio converts a value to another value. Mappers are usually used inside transformers to convert the values or keys that are provided by accessor.

Example use of a mapper in a transformer

In the following example a mapper is used to make the SKU of a product uppercase.

{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "string-upper"
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"sku"
]
}
}
}
}

Input:

{
"sku": "tnt"
}

Output:

{
"sku": "TNT"
}

A mapper can also be used to map keys of the data:

{
"prototype": "key-mapper",
"parameters": {
"mappers": [
{
"prototype": "string-upper"
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"sku"
]
}
}
}
}

Input:

{
"sku": "tnt"
}

Output:

{
"SKU": "tnt"
}

Combining mappers

Mappers can be combined using a chain mapper. A mapper can be made conditional by using a conditional mapper.

Chain mapper

Code: chain

{
"prototype": "chain",
"parameters": {
"transformers": [
{
"prototype": "value-mapper",
"parameters": {
"mappers": [
{
"prototype": "string-prepend",
"parameters": {
"prepend": "EXPLOSIVE-"
}
},
{
"prototype": "string-upper"
}
],
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"sku"
]
}
}
}
}
]
}
}

Input:

{
"sku": "tnt"
}

Output:

{
"sku": "EXPLOSIVE-TNT"
}

Conditional mapper

Code: conditional

{
"prototype": "conditional",
"parameters": {
"filters": [
{
"prototype": "value-condition",
"parameters": {
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"number"
]
}
},
"conditions": [
{
"prototype": "type-numeric"
}
]
}
}
],
"transformers": [
{
"prototype": "value-mapper",
"parameters": {
"accessor": {
"prototype": "key",
"parameters": {
"keys": [
"number"
]
}
},
"mappers": [
{
"prototype": "cast-int"
}
]
}
}
]
}
}
{
"number": "10" => 10
}
{
"number": "10.5" => 10
}
{
"number": "foo" => "foo"
}

Available mappers

The following mappers are available by default.

To introduce custom mapping logic, !! a new mapper !! can be created.

Standard

Code: standard

The standard mapper maps one value to another value.

{
"prototype": "standard",
"parameters": {
"to": "Trinitrotoluene",
"from": "tnt"
}
}
> "tnt"      => "Trinitrotoluene"
> "dynamite" => "dynamite"

An optional comparator can be supplied to change the way the value is compared.

{
"prototype": "standard",
"parameters": {
"to": "high",
"from": 100,
"comparator": "greater-than"
}
}
> 80  => 80
> 101 => "high"
> 200 => "high"

Dictionary map

Code: dictionary-map

To map multiple values with a single mapper the dictionary map can be used.

{
"prototype": "dictionary-map",
"parameters": {
"map": [
[
"tnt",
"Trinitrotoluene"
],
[
"dynamite",
"Dynamite"
],
[
"c4",
"Composition C-4"
]
]
}
}
> "tnt"      => "Trinitrotoluene"
> "dynamite" => "Dynamite"
> "c4" => "Composition C-4"

Cast: boolean

Code: cast-bool

> 100 => true
> 0 => false

Cast: float

Code: cast-float

> "10.5" => 10.5

Cast: integer

Code: cast-int

> "10"  => 10
> 10.2 => 10
> 10.5 => 11

Cast: string

Code: cast-string

> 10   => "10"
> 10.5 => "10.5"

Format: number

Code: format-number

{
"prototype": "format-number",
"parameters": {
"decimals": 2,
"decimalPoint": ".",
"thousandSeparator": ","
}
}
> 99999 => "99,999.00"

Format: date

Code: format-date

{
"prototype": "format-date",
"parameters": {
"toFormat": "Y-m-d\\TH:i:sO"
}
}
> "now" => "2019-03-01T12:00:00+0800"

A from-format can be added to support dates in any format:

{
"prototype": "format-date",
"parameters": {
"toFormat": "Y-m-d\\TH:i:sO",
"fromFormat": "d-m-Y"
}
}
> "01-03-2019" => "2019-03-01T00:00:00+0800"

Timezones can be added to convert between timezones.

{
"prototype": "format-date",
"parameters": {
"toFormat": "Y-m-d H:i:s",
"fromFormat": "Y-m-d H:i:s",
"toTimezone": "Europe\\London",
"fromTimezone": "Europe\\Amsterdam"
}
}
> 2019-03-01 00:00:00  => 2019-02-28 23:00:00

Filter: Allow only letters and digits

Code: string-filter-alnum

> "foo!@#123" => "foo123"

Filter: Allow only letters

Code: string-filter-letters

> "foo!@#123" => "foo"

Filter: Allow only digits

Code: string-filter-numbers

> "foo!@#123" => "123"

String: cut

Code: string-cut

{
"prototype": "string-cut",
"parameters": {
"start": 3,
"length": 2
}
}Copy to clipboardErrorCopied
> "foo123"  => "12"

String: append

Code: string-append

{
"prototype": "string-append",
"parameters": {
"append": "-00"
}
}Copy to clipboardErrorCopied
> "foo" => "foo-00"

String: prepend

Code: string-prepend

{
"prototype": "string-prepend",
"parameters": {
"prepend": "00-"
}
}
> "foo" => "00-foo"

String: replace

Code: string-replace

{
"prototype": "string-replace",
"parameters": {
"search": "fruit",
"replace": "pizza"
}
}
> "Eat fruit every day" => "Eat pizza every day"

String: slugify

Code: string-slugify

> "Hello world" => "hello-world"

String: strip HTML

Code: string-strip-html

{
"prototype": "string-strip-html",
"parameters": {
"excludeTags": "<em><strong>"
}
}
> "<em><a>click</a></em>" => "<em>click</em>"

String: trim

Code: string-trim

{
"prototype": "string-trim",
"parameters": {
"side": "left",
"characters": "^"
}
}
> "^^tnt^^" => "tnt^^"

String: lower

Code: string-lower

> "TNT" => "tnt"

String: upper

Code: string-upper

> "tnt" => "TNT"

String: upper first

Code: string-upper-first

> "tnt" => "Tnt"

String: PCRE replace

Code: string-regex-replace

{
"prototype": "string-regex-replace",
"parameters": {
"replace": "pizza",
"searchRegex": "/fruit/i"
}
}
> "Eat FRUIT every day" => "Eat pizza every day"

String: add dispersion to a file name

Code: string-dispersion

> "flower.jpg" => "f/l/flower.jpg"

String: explode to an array

Code: string-explode

{
"prototype": "string-explode",
"parameters": {
"delimiter": "|"
}
}
> "tnt|dynamite" => ["tnt", "dynamite"]

String: explode to an array using a PCRE expression

Code: string-preg-split

{
"prototype": "string-preg-split",
"parameters": {
"pattern": "/,\\s*/"
}
}
> "tnt, dynamite" => ["tnt", "dynamite"]

Json: Decode to array

Code: json-decode

> "{\"foo\": \"bar\"}" => {"foo": "bar"}

Json: Encode

Code: json-encode

> {"foo": "bar"} => "{\"foo\": \"bar\"}"

List: inherit from

Code: list-inherit-from

{
"prototype": "list-inherit-from",
"parameters": {
"array": {
"price": 99.5,
"weight": 10
}
}
}
> {"sku": "foo", "price": 40} => {"sku": "foo", "price": 40, "weight": 10}

Note that in this example the price has not been overwritten.

List: extend with

Code: list-extend-with

{
"prototype": "list-extend-with",
"parameters": {
"array": {
"price": 99.5,
"weight": 10
}
}
}
> {"sku": "foo", "price": 40} => {"sku": "foo", "price": 99.50, "weight": 10}

Note that in this example the price has been overwritten.

List: intersect values

Code: list-intersect

{
"prototype": "list-intersect",
"parameters": {
"array": [
"tnt",
"dynamite"
]
}
}
> ["c4", "tnt"] => ["tnt"]

List: intersect keys

Code: list-intersect-keys

{
"prototype": "list-intersect-keys",
"parameters": {
"array": {
"sku": true,
"price": true
}
}
}
> {"sku": "tnt", "weight": 100} => {"sku": "tnt"}

List: diff values

Code: list-diff

{
"prototype": "list-intersect",
"parameters": {
"array": [
"tnt",
"dynamite"
]
}
}
> ["c4", "tnt"] => ["c4"]

List: diff keys

Code: list-diff-keys

{
"prototype": "list-diff-keys",
"parameters": {
"array": {
"sku": true,
"price": true
}
}
}
> {"sku": "tnt", "weight": 100} => {"weight": 100}

List: reverse values

Code: list-reverse

> ["tnt", "dynamite"] => ["dynamite", "tnt"]

List: flip keys and values

Code: list-flip

> ["tnt", "dynamite"] => {"tnt": 0, "dynamite": 1}

List: get values

Code: list-values

> {12: "tnt", 30: "dynamite"} => ["tnt", "dynamite"]

List: get keys

Code: list-keys

> {12: "tnt", 30: "dynamite"} => [12, 30]

List: get count

Code: list-count

> ["tnt", "dynamite"] => 2

List: implode

Code: list-implode

{
"prototype": "list-implode",
"parameters": {
"glue": "|"
}
}
> ["tnt", "dynamite"] => "tnt|dynamite"

Locale: Display region

Code: locale-display-region

{
"prototype": "locale-display-region",
"parameters": {
"language": "en"
}
}
> DE => Germany

Operator

Code: operator

The operator mapper takes multiple values and applies an operator on them.

{
"prototype": "operator",
"parameters": {
"operator": "addition"
}
}
> [2, 3]      => 5
> [10, 15, 7] => 32

Prepared operator

Code: prepared operator

The prepared operator mapper differs from the operator mapper in that it gets part of the values from its configuration.

{
"prototype": "prepared-operator",
"parameters": {
"operator": "addition",
"left": 2
}
}
> 3  => 5
> 10 => 12
{
"prototype": "prepared-operator",
"parameters": {
"operator": "division",
"right": 2
}
}
> 100 => 50
> 11 => 5.5