# Expressions

## Overview

Expressions present a powerful tool to derive values or rules conditions from inputs. It is useful to derive arbitrary attributes like tax-included prices, tax, shipping, etc.

Expressions compose of tokens (variables that are put between single quotes, representing context data like variant price, options, etc), constants (strings that are put between double quotes), operators (math operators) and self expressive keywords like "if", "then", "else".

Some examples where expressions can be used:

- A custom field representing tax that equal to 21% of product price.
- A "Shipping and included" price that equal product price added with a shipping fee for a marketplace that take only shipping and tax included prices.
- A condition to include or exclude variant from feed based on its metafield and/or other data

Following screenshot is showing a condition that match when one of following conditions are met

- quantity > 10
- price between 10 and 20
- has a product metafield with namespace "my_fields" and key "always_include" which has value "yes"

To aid expression editing, supported tokens will be listed in a dropdown and one needs to be selected from the list to be added into the expression box. Added tokens have a greyed background and can be changed by clicking on it.

## Examples

#### String concatenation

#### Regular expression match

Regular expression is really powerful (and complicated) way to check for patterns in string values. Examples include:

- If Product description include one of the following words: "shirt", "jean", "child" or "women":
- 'Product description' ~= "(shirt|jean|child|women)"

- If Product tile starts with "Men" or "Boy". This does not include titles that have the word men somewhere else in the sentence
- 'Product title' ~= "(^men|^boy)" will match "Men's wear" and "Boy's jeans" but not "T-shirt for men"

#### "Looking-up" expression

Following screenshot is showing an expression derive a tax-included price value from the value of product type.

- If the product is clothing then the price should include a 10% rise for tax
- if it's is kitchen ware or household then the tax included is 20%
- otherwise the price stay the same

#### "Price range" expression

Sometime you may need to specify shipping cost for product according to its price and/or weight

Following is an expression for

- If price > 100 shipping is free
- if 50 < price < 100 shipping is 10% of price
- if price < 50 then shipping is 5

## Reference

There are 2 basic types of consts: numbers and strings. Numbers may be floating point or integers. Strings should always be double-quoted. Types get automatically converted when possible, for example:

"1" + 2 == "12"

"12" - 1 == 11

"12" * 1 == 12

Values | Description |
---|---|

43, -1.234 | Numbers |

"hello" | String |

" \" \\ " | Escaping of double-quotes and blackslash in string |

**BEWARE!**

Strings must be double-quoted! Single quotes are for tokens.

Numeric arithmetic | Description |
---|---|

x + y | Add |

x - y | Subtract |

x * y | Multiply |

x / y | Divide |

x ^ y | Power |

x mod y | Modulo |

**BEWARE!**Modulo always returns a positive number:

`-1 mod 3 == 2`

.
Comparisons | Description |
---|---|

x == y | Equals |

x != y | Does not equal |

x < y | Less than |

x <= y | Less than or equal to |

x > y | Greater than |

x >= y | Greater than or equal to |

x == y <= z | Chained relation, equivalent to (x == y and y <= z) |

x ~= y | Regular expression match |

x in (a, b, c) | Equivalent to (x == a or x == b or x == c) |

x not in (a, b, c) | Equivalent to (x != a and x != b and x != c) |

Boolean logic | Description |
---|---|

x or y | Boolean or |

x and y | Boolean and |

not x | Boolean not |

if x then y else z | If boolean x is true, return value y, else return z |

( x ) | Explicit operator precedence |

Objects and arrays | Description |
---|---|

(a, b, c) | Array |

a in b | Array a is a subset of array b |

x of y | Property x of object y |

To return a date 3 months from now: date('{now}', 3, "month") Same time tomorrow: date('{now}', 1, "month")

Functions | Description |
---|---|

abs(x) | Absolute value |

ceil(x) | Round floating point up |

empty(x) | True if x is `undefined` , `null` , an empty array or an empty string, or an invalid number (result of division by zero, for example) |

exists(x) | True unless x is `undefined` or `null` |

floor(x) | Round floating point down |

log(x) | Natural logarithm |

log2(x) | Logarithm base two |

log10(x) | Logarithm base ten |

max(a, b, c...) | Max value (variable length of args) |

min(a, b, c...) | Min value (variable length of args) |

round(x) | Round floating point |

sqrt(x) | Square root |

replace(x,searchRegex,replaceWith,fallback) | Look for all regular expression matches by `searchRegex` in `x` , and replace with `replaceWith` . The optional `fallback` if presented will be returned if no matches is found. |

default(x,fallback1,fallback2,...,fallbackN) | Look from left to right and return the first non-empty value found. This function is helpful to cascade fallback values for optional expression (non-existing metafield, etc.). |

toFixed(x,decimalPlaces) | Converts a number to a string, rounding the number a specified number of decimal. |

date(dateValue, deviation, deviationType) | Modify input date by `deviation` amount of time. `deviationType` could be "second", "minute", "hour", "day", "week", "month", "year".To get a date 3 months from now date('{now}', 3, "month") Same time last week date('{now}', -1, "week") |

substring(stringValue, start, end?) | Return a sub string of the `stringValue` which starts at index `start` and ends up to (but not including) index `end` . First character is at index 0. |