functions

package
v0.143.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2021 License: AGPL-3.0 Imports: 18 Imported by: 4

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var XFUNCTIONS = map[string]*types.XFunction{}

XFUNCTIONS is our map of functions available in Excellent which aren't tests

Functions

func Abs 

func Abs(env envs.Environment, num types.XNumber) types.XValue

Abs returns the absolute value of `number`. 

@(abs(-10)) -> 10
@(abs(10.5)) -> 10.5
@(abs("foo")) -> ERROR

@function abs(number)

func And 

func And(env envs.Environment, values ...types.XValue) types.XValue

And returns whether all the given `values` are truthy. 

@(and(true)) -> true
@(and(true, false, true)) -> false

@function and(values...)

func Array 

func Array(env envs.Environment, values ...types.XValue) types.XValue

Array takes multiple `values` and returns them as an array. 

@(array("a", "b", 356)[1]) -> b
@(join(array("a", "b", "c"), "|")) -> a|b|c
@(count(array())) -> 0
@(count(array("a", "b"))) -> 2

@function array(values...)

func AttachmentParts added in v0.32.0 

func AttachmentParts(env envs.Environment, attachment types.XText) types.XValue

AttachmentParts parses an attachment into its different parts 

@(attachment_parts("image/jpeg:https://example.com/test.jpg")) -> {content_type: image/jpeg, url: https://example.com/test.jpg}

@function attachment_parts(attachment)

func Boolean added in v0.9.0 

func Boolean(env envs.Environment, value types.XValue) types.XValue

Boolean tries to convert `value` to a boolean.

An error is returned if the value can't be converted. 

@(boolean(array(1, 2))) -> true
@(boolean("FALSE")) -> false
@(boolean(1 / 0)) -> ERROR

@function boolean(value)

func Char 

func Char(env envs.Environment, num types.XNumber) types.XValue

Char returns the character for the given UNICODE `code`.

It is the inverse of [function:code]. 

@(char(33)) -> !
@(char(128512)) -> 😀
@(char("foo")) -> ERROR

@function char(code)

func Clean 

func Clean(env envs.Environment, text types.XText) types.XValue

Clean removes any non-printable characters from `text`. 

@(clean("😃 Hello \nwo\tr\rld")) -> 😃 Hello world
@(clean(123)) -> 123

@function clean(text)

func Code 

func Code(env envs.Environment, text types.XText) types.XValue

Code returns the UNICODE code for the first character of `text`.

It is the inverse of [function:char]. 

@(code("a")) -> 97
@(code("abc")) -> 97
@(code("😀")) -> 128512
@(code("15")) -> 49
@(code(15)) -> 49
@(code("")) -> ERROR

@function code(text)

func Count added in v0.34.0 

func Count(env envs.Environment, value types.XValue) types.XValue

Count returns the number of items in the given array or properties on an object.

It will return an error if it is passed an item which isn't countable. 

@(count(contact.fields)) -> 6
@(count(array())) -> 0
@(count(array("a", "b", "c"))) -> 3
@(count(1234)) -> ERROR

@function count(value)

func Date 

func Date(env envs.Environment, value types.XValue) types.XValue

Date tries to convert `value` to a date.

If it is text then it will be parsed into a date using the default date format. An error is returned if the value can't be converted. 

@(date("1979-07-18")) -> 1979-07-18
@(date("1979-07-18T10:30:45.123456Z")) -> 1979-07-18
@(date("10/05/2010")) -> 2010-05-10
@(date("NOT DATE")) -> ERROR

@function date(value)

func DateFromParts 

func DateFromParts(env envs.Environment, year, month, day int) types.XValue

DateFromParts creates a date from `year`, `month` and `day`. 

@(date_from_parts(2017, 1, 15)) -> 2017-01-15
@(date_from_parts(2017, 2, 31)) -> 2017-03-03
@(date_from_parts(2017, 13, 15)) -> ERROR

@function date_from_parts(year, month, day)

func DateTime added in v0.9.1 

func DateTime(env envs.Environment, value types.XValue) types.XValue

DateTime tries to convert `value` to a datetime.

If it is text then it will be parsed into a datetime using the default date and time formats. An error is returned if the value can't be converted. 

@(datetime("1979-07-18")) -> 1979-07-18T00:00:00.000000-05:00
@(datetime("1979-07-18T10:30:45.123456Z")) -> 1979-07-18T10:30:45.123456Z
@(datetime("10/05/2010")) -> 2010-05-10T00:00:00.000000-05:00
@(datetime("NOT DATE")) -> ERROR

@function datetime(value)

func DateTimeAdd added in v0.9.0 

func DateTimeAdd(env envs.Environment, args ...types.XValue) types.XValue

DateTimeAdd calculates the date value arrived at by adding `offset` number of `unit` to the `datetime`

Valid durations are "Y" for years, "M" for months, "W" for weeks, "D" for days, "h" for hour, "m" for minutes, "s" for seconds 

@(datetime_add("2017-01-15", 5, "D")) -> 2017-01-20T00:00:00.000000-05:00
@(datetime_add("2017-01-15 10:45", 30, "m")) -> 2017-01-15T11:15:00.000000-05:00

@function datetime_add(datetime, offset, unit)

func DateTimeDiff added in v0.9.0 

func DateTimeDiff(env envs.Environment, arg1 types.XValue, arg2 types.XValue, arg3 types.XValue) types.XValue

DateTimeDiff returns the duration between `date1` and `date2` in the `unit` specified.

Valid durations are "Y" for years, "M" for months, "W" for weeks, "D" for days, "h" for hour, "m" for minutes, "s" for seconds. 

@(datetime_diff("2017-01-15", "2017-01-17", "D")) -> 2
@(datetime_diff("2017-01-15", "2017-05-15", "W")) -> 17
@(datetime_diff("2017-01-15", "2017-05-15", "M")) -> 4
@(datetime_diff("2017-01-17 10:50", "2017-01-17 12:30", "h")) -> 1
@(datetime_diff("2017-01-17", "2015-12-17", "Y")) -> -2

@function datetime_diff(date1, date2, unit)

func DateTimeFromEpoch added in v0.28.6 

func DateTimeFromEpoch(env envs.Environment, num types.XNumber) types.XValue

DateTimeFromEpoch converts the UNIX epoch time `seconds` into a new date. 

@(datetime_from_epoch(1497286619)) -> 2017-06-12T11:56:59.000000-05:00
@(datetime_from_epoch(1497286619.123456)) -> 2017-06-12T11:56:59.123456-05:00

@function datetime_from_epoch(seconds)

func Default 

func Default(env envs.Environment, value types.XValue, def types.XValue) types.XValue

Default returns `value` if is not empty or an error, otherwise it returns `default`. 

@(default(undeclared.var, "default_value")) -> default_value
@(default("10", "20")) -> 10
@(default("", "value")) -> value
@(default("  ", "value")) -> \x20\x20
@(default(datetime("invalid-date"), "today")) -> today
@(default(format_urn("invalid-urn"), "ok")) -> ok

@function default(value, default)

func Epoch added in v0.13.1 

func Epoch(env envs.Environment, date types.XDateTime) types.XValue

Epoch converts `date` to a UNIX epoch time.

The returned number can contain fractional seconds. 

@(epoch("2017-06-12T16:56:59.000000Z")) -> 1497286619
@(epoch("2017-06-12T18:56:59.000000+02:00")) -> 1497286619
@(epoch("2017-06-12T16:56:59.123456Z")) -> 1497286619.123456
@(round_down(epoch("2017-06-12T16:56:59.123456Z"))) -> 1497286619

@function epoch(date)

func Extract added in v0.31.0 

func Extract(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue

Extract takes an object and extracts the named property. 

@(extract(contact, "name")) -> Ryan Lewis
@(extract(contact.groups[0], "name")) -> Testers

@function extract(object, properties)

func ExtractObject added in v0.34.0 

func ExtractObject(env envs.Environment, args ...types.XValue) types.XValue

ExtractObject takes an object and returns a new object by extracting only the named properties. 

@(extract_object(contact.groups[0], "name")) -> {name: Testers}

@function extract_object(object, properties...)

func Field 

func Field(env envs.Environment, text types.XText, args ...types.XValue) types.XValue

Field splits `text` using the given `delimiter` and returns the field at `index`.

The index starts at zero. When splitting with a space, the delimiter is considered to be all whitespace. 

@(field("a,b,c", 1, ",")) -> b
@(field("a,,b,c", 1, ",")) ->
@(field("a   b c", 1, " ")) -> b
@(field("a		b	c	d", 1, "	")) ->
@(field("a\t\tb\tc\td", 1, " ")) ->
@(field("a,b,c", "foo", ",")) -> ERROR

@function field(text, index, delimiter)

func ForEach added in v0.32.0 

func ForEach(env envs.Environment, args ...types.XValue) types.XValue

ForEach creates a new array by applying `func` to each value in `values`.

If the given function takes more than one argument, you can pass additional arguments after the function. 

@(foreach(array("a", "b", "c"), upper)) -> [A, B, C]
@(foreach(array("a", "b", "c"), (x) => x & "1")) -> [a1, b1, c1]
@(foreach(array("a", "b", "c"), (x) => object("v", x))) -> [{v: a}, {v: b}, {v: c}]
@(foreach(array("the man", "fox", "jumped up"), word, 0)) -> [the, fox, jumped]

@function foreach(values, func, [args...])

func ForEachValue added in v0.41.10 

func ForEachValue(env envs.Environment, args ...types.XValue) types.XValue

ForEachValue creates a new object by applying `func` to each property value of `object`.

If the given function takes more than one argument, you can pass additional arguments after the function. 

@(foreach_value(object("a", "x", "b", "y"), upper)) -> {a: X, b: Y}
@(foreach_value(object("a", "hi there", "b", "good bye"), word, 1)) -> {a: there, b: bye}

@function foreach_value(object, func, [args...])

func Format added in v0.34.1 

func Format(env envs.Environment, value types.XValue) types.XValue

Format formats `value` according to its type. 

@(format(1234.5670)) -> 1,234.567
@(format(now())) -> 11-04-2018 13:24
@(format(today())) -> 11-04-2018

@function format(value)

func FormatDate 

func FormatDate(env envs.Environment, args ...types.XValue) types.XValue

FormatDate formats `date` as text according to the given `format`.

If `format` is not specified then the environment's default format is used. The format string can consist of the following characters. The characters ' ', ':', ',', 'T', '-' and '_' are ignored. Any other character is an error.

* `YY` - last two digits of year 0-99 * `YYYY` - four digits of year 0000-9999 * `M` - month 1-12 * `MM` - month, zero padded 01-12 * `MMM` - month Jan-Dec (localized) * `MMMM` - month January-December (localized) * `D` - day of month, 1-31 * `DD` - day of month, zero padded 01-31 * `EEE` - day of week Mon-Sun (localized) * `EEEE` - day of week Monday-Sunday (localized) 

@(format_date("1979-07-18T15:00:00.000000Z")) -> 18-07-1979
@(format_date("1979-07-18T15:00:00.000000Z", "YYYY-MM-DD")) -> 1979-07-18
@(format_date("2010-05-10T19:50:00.000000Z", "YYYY M DD")) -> 2010 5 10
@(format_date("1979-07-18T15:00:00.000000Z", "YYYY")) -> 1979
@(format_date("1979-07-18T15:00:00.000000Z", "M")) -> 7
@(format_date("NOT DATE", "YYYY-MM-DD")) -> ERROR

@function format_date(date, [,format])

func FormatDateTime added in v0.9.1 

func FormatDateTime(env envs.Environment, args ...types.XValue) types.XValue

FormatDateTime formats `datetime` as text according to the given `format`.

If `format` is not specified then the environment's default format is used. The format string can consist of the following characters. The characters ' ', ':', ',', 'T', '-' and '_' are ignored. Any other character is an error.

* `YY` - last two digits of year 0-99 * `YYYY` - four digits of year 0000-9999 * `M` - month 1-12 * `MM` - month, zero padded 01-12 * `MMM` - month Jan-Dec (localized) * `MMMM` - month January-December (localized) * `D` - day of month, 1-31 * `DD` - day of month, zero padded 01-31 * `EEE` - day of week Mon-Sun (localized) * `EEEE` - day of week Monday-Sunday (localized) * `h` - hour of the day 1-12 * `hh` - hour of the day, zero padded 01-12 * `t` - twenty four hour of the day 0-23 * `tt` - twenty four hour of the day, zero padded 00-23 * `m` - minute 0-59 * `mm` - minute, zero padded 00-59 * `s` - second 0-59 * `ss` - second, zero padded 00-59 * `fff` - milliseconds * `ffffff` - microseconds * `fffffffff` - nanoseconds * `aa` - am or pm (localized) * `AA` - AM or PM (localized) * `Z` - hour and minute offset from UTC, or Z for UTC * `ZZZ` - hour and minute offset from UTC

Timezone should be a location name as specified in the IANA Time Zone database, such as "America/Guayaquil" or "America/Los_Angeles". If not specified, the current timezone will be used. An error will be returned if the timezone is not recognized. 

@(format_datetime("1979-07-18T15:00:00.000000Z")) -> 18-07-1979 10:00
@(format_datetime("1979-07-18T15:00:00.000000Z", "YYYY-MM-DD")) -> 1979-07-18
@(format_datetime("2010-05-10T19:50:00.000000Z", "YYYY M DD tt:mm")) -> 2010 5 10 14:50
@(format_datetime("2010-05-10T19:50:00.000000Z", "YYYY-MM-DD hh:mm AA", "America/Los_Angeles")) -> 2010-05-10 12:50 PM
@(format_datetime("1979-07-18T15:00:00.000000Z", "YYYY")) -> 1979
@(format_datetime("1979-07-18T15:00:00.000000Z", "M")) -> 7
@(format_datetime("NOT DATE", "YYYY-MM-DD")) -> ERROR

@function format_datetime(datetime [,format [,timezone]])

func FormatLocation added in v0.9.4 

func FormatLocation(env envs.Environment, path types.XText) types.XValue

FormatLocation formats the given `location` as its name. 

@(format_location("Rwanda")) -> Rwanda
@(format_location("Rwanda > Kigali")) -> Kigali

@function format_location(location)

func FormatNumber added in v0.9.0 

func FormatNumber(env envs.Environment, args ...types.XValue) types.XValue

FormatNumber formats `number` to the given number of decimal `places`.

An optional third argument `humanize` can be false to disable the use of thousand separators. 

@(format_number(1234)) -> 1,234
@(format_number(1234.5670)) -> 1,234.567
@(format_number(1234.5670, 2, true)) -> 1,234.57
@(format_number(1234.5678, 0, false)) -> 1235
@(format_number("foo", 2, false)) -> ERROR

@function format_number(number, places [, humanize])

func FormatTime added in v0.28.0 

func FormatTime(env envs.Environment, args ...types.XValue) types.XValue

FormatTime formats `time` as text according to the given `format`.

If `format` is not specified then the environment's default format is used. The format string can consist of the following characters. The characters ' ', ':', ',', 'T', '-' and '_' are ignored. Any other character is an error.

* `h` - hour of the day 1-12 * `hh` - hour of the day, zero padded 01-12 * `t` - twenty four hour of the day 0-23 * `tt` - twenty four hour of the day, zero padded 00-23 * `m` - minute 0-59 * `mm` - minute, zero padded 00-59 * `s` - second 0-59 * `ss` - second, zero padded 00-59 * `fff` - milliseconds * `ffffff` - microseconds * `fffffffff` - nanoseconds * `aa` - am or pm (localized) * `AA` - AM or PM (localized) 

@(format_time("14:50:30.000000")) -> 14:50
@(format_time("14:50:30.000000", "h:mm aa")) -> 2:50 pm
@(format_time("15:00:27.000000", "s")) -> 27
@(format_time("NOT TIME", "hh:mm")) -> ERROR

@function format_time(time [,format])

func FormatURN 

func FormatURN(env envs.Environment, arg types.XText) types.XValue

FormatURN formats `urn` into human friendly text. 

@(format_urn("tel:+250781234567")) -> 0781 234 567
@(format_urn("twitter:134252511151#billy_bob")) -> billy_bob
@(format_urn(contact.urn)) -> (202) 456-1111
@(format_urn(urns.tel)) -> (202) 456-1111
@(format_urn(urns.mailto)) -> foo@bar.com
@(format_urn("NOT URN")) -> ERROR

@function format_urn(urn)

func HTMLDecode added in v0.78.1 

func HTMLDecode(env envs.Environment, text types.XText) types.XValue

HTMLDecode HTML decodes `text` 

@(html_decode("Red & Blue")) -> Red & Blue
@(html_decode("5 + 10")) -> 5 + 10

@function html_decode(text)

func If 

func If(env envs.Environment, test types.XValue, value1 types.XValue, value2 types.XValue) types.XValue

If returns `value1` if `test` is truthy or `value2` if not.

If the first argument is an error that error is returned. 

@(if(1 = 1, "foo", "bar")) -> foo
@(if("foo" > "bar", "foo", "bar")) -> ERROR

@function if(test, value1, value2)

func InitialTextFunction added in v0.10.17 

func InitialTextFunction(minOtherArgs int, maxOtherArgs int, f func(envs.Environment, types.XText, ...types.XValue) types.XValue) types.XFunc

InitialTextFunction creates an XFunc from a function that takes an initial text arg followed by other args

func IsError added in v0.33.9 

func IsError(env envs.Environment, value types.XValue) types.XValue

IsError returns whether `value` is an error 

@(is_error(datetime("foo"))) -> true
@(is_error(run.not.existing)) -> true
@(is_error("hello")) -> false

@function is_error(value)

func JSON 

func JSON(env envs.Environment, value types.XValue) types.XValue

JSON returns the JSON representation of `value`. 

@(json("string")) -> "string"
@(json(10)) -> 10
@(json(null)) -> null
@(json(contact.uuid)) -> "5d76d86b-3bb9-4d5a-b822-c9d86f5d8e4f"

@function json(value)

func Join 

func Join(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue

Join joins the given `array` of strings with `separator` to make text. 

@(join(array("a", "b", "c"), "|")) -> a|b|c
@(join(split("a.b.c", "."), " ")) -> a b c

@function join(array, separator)

func LegacyAdd 

func LegacyAdd(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue

LegacyAdd simulates our old + operator, which operated differently based on whether one of the parameters was a date or not. If one is a date, then the other side is expected to be an integer with a number of days to add to the date, otherwise a normal decimal addition is attempted.

func Lookup added in v0.32.0 

func Lookup(name string) *types.XFunction

Lookup returns the function with the given name (case-insensitive) or nil

func Lower 

func Lower(env envs.Environment, text types.XText) types.XValue

Lower converts `text` to lowercase. 

@(lower("HellO")) -> hello
@(lower("hello")) -> hello
@(lower("123")) -> 123
@(lower("😀")) -> 😀

@function lower(text)

func Max 

func Max(env envs.Environment, values ...types.XValue) types.XValue

Max returns the maximum value in `numbers`. 

@(max(1, 2)) -> 2
@(max(1, -1, 10)) -> 10
@(max(1, 10, "foo")) -> ERROR

@function max(numbers...)

func Mean 

func Mean(env envs.Environment, args ...types.XValue) types.XValue

Mean returns the arithmetic mean of `numbers`. 

@(mean(1, 2)) -> 1.5
@(mean(1, 2, 6)) -> 3
@(mean(1, "foo")) -> ERROR

@function mean(numbers...)

func Min 

func Min(env envs.Environment, values ...types.XValue) types.XValue

Min returns the minimum value in `numbers`. 

@(min(1, 2)) -> 1
@(min(2, 2, -10)) -> -10
@(min(1, 2, "foo")) -> ERROR

@function min(numbers...)

func MinAndMaxArgsCheck added in v0.51.0 

func MinAndMaxArgsCheck(min int, max int, f types.XFunc) types.XFunc

MinAndMaxArgsCheck wraps an XFunc and checks the number of args

func MinArgsCheck added in v0.51.0 

func MinArgsCheck(min int, f types.XFunc) types.XFunc

MinArgsCheck wraps an XFunc and checks the minimum number of args

func Mod 

func Mod(env envs.Environment, num1 types.XNumber, num2 types.XNumber) types.XValue

Mod returns the remainder of the division of `dividend` by `divisor`. 

@(mod(5, 2)) -> 1
@(mod(4, 2)) -> 0
@(mod(5, "foo")) -> ERROR

@function mod(dividend, divisor)

func NoArgFunction 

func NoArgFunction(f func(envs.Environment) types.XValue) types.XFunc

NoArgFunction creates an XFunc from a no-arg function

func Now 

func Now(env envs.Environment) types.XValue

Now returns the current date and time in the current timezone. 

@(now()) -> 2018-04-11T13:24:30.123456-05:00

@function now()

func NumArgsCheck added in v0.51.0 

func NumArgsCheck(num int, f types.XFunc) types.XFunc

NumArgsCheck wraps an XFunc and checks the number of args

func Number 

func Number(env envs.Environment, value types.XValue) types.XValue

Number tries to convert `value` to a number.

An error is returned if the value can't be converted. 

@(number(10)) -> 10
@(number("123.45000")) -> 123.45
@(number("what?")) -> ERROR

@function number(value)

func Object added in v0.34.0 

func Object(env envs.Environment, pairs ...types.XValue) types.XValue

Object takes property name value pairs and returns them as a new object. 

@(object()) -> {}
@(object("a", 123, "b", "hello")) -> {a: 123, b: hello}
@(object("a")) -> ERROR

@function object(pairs...)

func ObjectAndTextsFunction added in v0.51.0 

func ObjectAndTextsFunction(f func(envs.Environment, *types.XObject, ...types.XText) types.XValue) types.XFunc

ObjectAndTextsFunction creates an XFunc from a function that takes an object and any number of text values

func ObjectTextAndNumberFunction added in v0.51.0 

func ObjectTextAndNumberFunction(f func(envs.Environment, *types.XObject, types.XText, types.XNumber) types.XValue) types.XFunc

ObjectTextAndNumberFunction creates an XFunc from a function that takes an object, text and a number

func OneArgFunction 

func OneArgFunction(f func(envs.Environment, types.XValue) types.XValue) types.XFunc

OneArgFunction creates an XFunc from a single-arg function

func OneArrayFunction added in v0.128.0 

func OneArrayFunction(f func(envs.Environment, *types.XArray) types.XValue) types.XFunc

OneArrayFunction creates an XFunc from a single array function

func OneDateFunction 

func OneDateFunction(f func(envs.Environment, types.XDate) types.XValue) types.XFunc

OneDateFunction creates an XFunc from a single date function

func OneDateTimeFunction added in v0.9.0 

func OneDateTimeFunction(f func(envs.Environment, types.XDateTime) types.XValue) types.XFunc

OneDateTimeFunction creates an XFunc from a single datetime function

func OneNumberAndOptionalIntegerFunction 

func OneNumberAndOptionalIntegerFunction(f func(envs.Environment, types.XNumber, int) types.XValue, defaultVal int) types.XFunc

OneNumberAndOptionalIntegerFunction creates an XFunc from a function that takes a number and an optional integer

func OneNumberFunction 

func OneNumberFunction(f func(envs.Environment, types.XNumber) types.XValue) types.XFunc

OneNumberFunction creates an XFunc from a single number function

func OneTextFunction added in v0.9.0 

func OneTextFunction(f func(envs.Environment, types.XText) types.XValue) types.XFunc

OneTextFunction creates an XFunc from a function that takes a single text arg

func Or 

func Or(env envs.Environment, values ...types.XValue) types.XValue

Or returns whether if any of the given `values` are truthy. 

@(or(true)) -> true
@(or(true, false, true)) -> true

@function or(values...)

func ParseDateTime added in v0.9.0 

func ParseDateTime(env envs.Environment, args ...types.XValue) types.XValue

ParseDateTime parses `text` into a date using the given `format`.

The format string can consist of the following characters. The characters ' ', ':', ',', 'T', '-' and '_' are ignored. Any other character is an error.

* `YY` - last two digits of year 0-99 * `YYYY` - four digits of year 0000-9999 * `M` - month 1-12 * `MM` - month, zero padded 01-12 * `D` - day of month, 1-31 * `DD` - day of month, zero padded 01-31 * `h` - hour of the day 1-12 * `hh` - hour of the day 01-12 * `t` - twenty four hour of the day 1-23 * `tt` - twenty four hour of the day, zero padded 01-23 * `m` - minute 0-59 * `mm` - minute, zero padded 00-59 * `s` - second 0-59 * `ss` - second, zero padded 00-59 * `fff` - milliseconds * `ffffff` - microseconds * `fffffffff` - nanoseconds * `aa` - am or pm * `AA` - AM or PM * `Z` - hour and minute offset from UTC, or Z for UTC * `ZZZ` - hour and minute offset from UTC

Timezone should be a location name as specified in the IANA Time Zone database, such as "America/Guayaquil" or "America/Los_Angeles". If not specified, the current timezone will be used. An error will be returned if the timezone is not recognized.

Note that fractional seconds will be parsed even without an explicit format identifier. You should only specify fractional seconds when you want to assert the number of places in the input format.

parse_datetime will return an error if it is unable to convert the text to a datetime. 

@(parse_datetime("1979-07-18", "YYYY-MM-DD")) -> 1979-07-18T00:00:00.000000-05:00
@(parse_datetime("2010 5 10", "YYYY M DD")) -> 2010-05-10T00:00:00.000000-05:00
@(parse_datetime("2010 5 10 12:50", "YYYY M DD tt:mm", "America/Los_Angeles")) -> 2010-05-10T12:50:00.000000-07:00
@(parse_datetime("NOT DATE", "YYYY-MM-DD")) -> ERROR

@function parse_datetime(text, format [,timezone])

func ParseJSON 

func ParseJSON(env envs.Environment, text types.XText) types.XValue

ParseJSON tries to parse `text` as JSON.

If the given `text` is not valid JSON, then an error is returned 

@(parse_json("{\"foo\": \"bar\"}").foo) -> bar
@(parse_json("[1,2,3,4]")[2]) -> 3
@(parse_json("invalid json")) -> ERROR

@function parse_json(text)

func ParseTime added in v0.28.0 

func ParseTime(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue

ParseTime parses `text` into a time using the given `format`.

The format string can consist of the following characters. The characters ' ', ':', ',', 'T', '-' and '_' are ignored. Any other character is an error.

* `h` - hour of the day 1-12 * `hh` - hour of the day, zero padded 01-12 * `t` - twenty four hour of the day 1-23 * `tt` - twenty four hour of the day, zero padded 01-23 * `m` - minute 0-59 * `mm` - minute, zero padded 00-59 * `s` - second 0-59 * `ss` - second, zero padded 00-59 * `fff` - milliseconds * `ffffff` - microseconds * `fffffffff` - nanoseconds * `aa` - am or pm * `AA` - AM or PM

Note that fractional seconds will be parsed even without an explicit format identifier. You should only specify fractional seconds when you want to assert the number of places in the input format.

parse_time will return an error if it is unable to convert the text to a time. 

@(parse_time("15:28", "tt:mm")) -> 15:28:00.000000
@(parse_time("2:40 pm", "h:mm aa")) -> 14:40:00.000000
@(parse_time("NOT TIME", "tt:mm")) -> ERROR

@function parse_time(text, format)

func Percent 

func Percent(env envs.Environment, num types.XNumber) types.XValue

Percent formats `number` as a percentage. 

@(percent(0.54234)) -> 54%
@(percent(1.2)) -> 120%
@(percent("foo")) -> ERROR

@function percent(number)

func Rand 

func Rand(env envs.Environment) types.XValue

Rand returns a single random number between [0.0-1.0). 

@(rand()) -> 0.6075520156746239
@(rand()) -> 0.48467757094734026

@function rand()

func RandBetween 

func RandBetween(env envs.Environment, min types.XNumber, max types.XNumber) types.XValue

RandBetween a single random integer in the given inclusive range. 

@(rand_between(1, 10)) -> 10
@(rand_between(1, 10)) -> 2

@function rand_between()

func ReadChars added in v0.9.4 

func ReadChars(env envs.Environment, val types.XText) types.XValue

ReadChars converts `text` into something that can be read by IVR systems.

ReadChars will split the numbers such as they are easier to understand. This includes splitting in 3s or 4s if appropriate. 

@(read_chars("1234")) -> 1 2 3 4
@(read_chars("abc")) -> a b c
@(read_chars("abcdef")) -> a b c , d e f

@function read_chars(text)

func RegexMatch added in v0.19.0 

func RegexMatch(env envs.Environment, text types.XText, args ...types.XValue) types.XValue

RegexMatch returns the first match of the regular expression `pattern` in `text`.

An optional third parameter `group` determines which matching group will be returned. 

@(regex_match("sda34dfddg67", "\d+")) -> 34
@(regex_match("Bob Smith", "(\w+) (\w+)", 1)) -> Bob
@(regex_match("Bob Smith", "(\w+) (\w+)", 2)) -> Smith
@(regex_match("Bob Smith", "(\w+) (\w+)", 5)) -> ERROR
@(regex_match("abc", "[\.")) -> ERROR

@function regex_match(text, pattern [,group])

func RegisterXFunction 

func RegisterXFunction(name string, f types.XFunc)

RegisterXFunction registers a new function in Excellent

func RemoveFirstWord 

func RemoveFirstWord(env envs.Environment, text types.XText) types.XValue

RemoveFirstWord removes the first word of `text`. 

@(remove_first_word("foo bar")) -> bar
@(remove_first_word("Hi there. I'm a flow!")) -> there. I'm a flow!

@function remove_first_word(text)

func Repeat 

func Repeat(env envs.Environment, text types.XText, count int) types.XValue

Repeat returns `text` repeated `count` number of times. 

@(repeat("*", 8)) -> ********
@(repeat("*", "foo")) -> ERROR

@function repeat(text, count)

func Replace 

func Replace(env envs.Environment, args ...types.XValue) types.XValue

Replace replaces up to `count` occurrences of `needle` with `replacement` in `text`.

If `count` is omitted or is less than 0 then all occurrences are replaced. 

@(replace("foo bar foo", "foo", "zap")) -> zap bar zap
@(replace("foo bar foo", "foo", "zap", 1)) -> zap bar foo
@(replace("foo bar", "baz", "zap")) -> foo bar

@function replace(text, needle, replacement [, count])

func ReplaceTime added in v0.28.0 

func ReplaceTime(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue

ReplaceTime returns a new datetime with the time part replaced by the `time`. 

@(replace_time(now(), "10:30")) -> 2018-04-11T10:30:00.000000-05:00
@(replace_time("2017-01-15", "10:30")) -> 2017-01-15T10:30:00.000000-05:00
@(replace_time("foo", "10:30")) -> ERROR

@function replace_time(datetime)

func Reverse added in v0.140.0 

func Reverse(env envs.Environment, array *types.XArray) types.XValue

Reverse returns a new array with the values of `array` reversed. 

@(reverse(array(3, 1, 2))) -> [2, 1, 3]
@(reverse(array("C", "A", "B"))) -> [B, A, C]

@function reverse(array)

func Round 

func Round(env envs.Environment, num types.XNumber, places int) types.XValue

Round rounds `number` to the nearest value.

You can optionally pass in the number of decimal places to round to as `places`. If `places` < 0, it will round the integer part to the nearest 10^(-places). 

@(round(12)) -> 12
@(round(12.141)) -> 12
@(round(12.6)) -> 13
@(round(12.141, 2)) -> 12.14
@(round(12.146, 2)) -> 12.15
@(round(12.146, -1)) -> 10
@(round("notnum", 2)) -> ERROR

@function round(number [,places])

func RoundDown 

func RoundDown(env envs.Environment, num types.XNumber, places int) types.XValue

RoundDown rounds `number` down to the nearest integer value.

You can optionally pass in the number of decimal places to round to as `places`. 

@(round_down(12)) -> 12
@(round_down(12.141)) -> 12
@(round_down(12.6)) -> 12
@(round_down(12.141, 2)) -> 12.14
@(round_down(12.146, 2)) -> 12.14
@(round_down("foo")) -> ERROR

@function round_down(number [,places])

func RoundUp 

func RoundUp(env envs.Environment, num types.XNumber, places int) types.XValue

RoundUp rounds `number` up to the nearest integer value.

You can optionally pass in the number of decimal places to round to as `places`. 

@(round_up(12)) -> 12
@(round_up(12.141)) -> 13
@(round_up(12.6)) -> 13
@(round_up(12.141, 2)) -> 12.15
@(round_up(12.146, 2)) -> 12.15
@(round_up("foo")) -> ERROR

@function round_up(number [,places])

func Sort added in v0.139.0 

func Sort(env envs.Environment, array *types.XArray) types.XValue

Sort returns a new array with the values of `array` sorted. 

@(sort(array(3, 1, 2))) -> [1, 2, 3]
@(sort(array("C", "A", "B"))) -> [A, B, C]

@function sort(array)

func Split 

func Split(env envs.Environment, text types.XText, delimiters types.XText) types.XValue

Split splits `text` into an array of separated words.

Empty values are removed from the returned list. There is an optional final parameter `delimiters` which is string of characters used to split the text into words. 

@(split("a b c")) -> [a, b, c]
@(split("a", " ")) -> [a]
@(split("abc..d", ".")) -> [abc, d]
@(split("a.b.c.", ".")) -> [a, b, c]
@(split("a|b,c  d", " .|,")) -> [a, b, c, d]

@function split(text, [,delimiters])

func Sum added in v0.123.0 

func Sum(env envs.Environment, array *types.XArray) types.XValue

Sum sums the items in the given `array`. 

@(sum(array(1, 2, "3"))) -> 6

@function sum(array)

func TZ 

func TZ(env envs.Environment, date types.XDateTime) types.XValue

TZ returns the name of the timezone of `date`.

If no timezone information is present in the date, then the current timezone will be returned. 

@(tz("2017-01-15T02:15:18.123456Z")) -> UTC
@(tz("2017-01-15 02:15:18PM")) -> America/Guayaquil
@(tz("2017-01-15")) -> America/Guayaquil
@(tz("foo")) -> ERROR

@function tz(date)

func TZOffset 

func TZOffset(env envs.Environment, date types.XDateTime) types.XValue

TZOffset returns the offset of the timezone of `date`.

The offset is returned in the format `[+/-]HH:MM`. If no timezone information is present in the date, then the current timezone offset will be returned. 

@(tz_offset("2017-01-15T02:15:18.123456Z")) -> +0000
@(tz_offset("2017-01-15 02:15:18PM")) -> -0500
@(tz_offset("2017-01-15")) -> -0500
@(tz_offset("foo")) -> ERROR

@function tz_offset(date)

func Text added in v0.9.0 

func Text(env envs.Environment, value types.XValue) types.XValue

Text tries to convert `value` to text.

An error is returned if the value can't be converted. 

@(text(3 = 3)) -> true
@(json(text(123.45))) -> "123.45"
@(text(1 / 0)) -> ERROR

@function text(value)

func TextAndDateFunction added in v0.9.0 

func TextAndDateFunction(f func(envs.Environment, types.XText, types.XDateTime) types.XValue) types.XFunc

TextAndDateFunction creates an XFunc from a function that takes a text and a date arg

func TextAndIntegerFunction added in v0.9.0 

func TextAndIntegerFunction(f func(envs.Environment, types.XText, int) types.XValue) types.XFunc

TextAndIntegerFunction creates an XFunc from a function that takes a text and an integer arg

func TextAndNumberFunction added in v0.9.0 

func TextAndNumberFunction(f func(envs.Environment, types.XText, types.XNumber) types.XValue) types.XFunc

TextAndNumberFunction creates an XFunc from a function that takes a text and a number arg

func TextAndOptionalTextFunction added in v0.76.2 

func TextAndOptionalTextFunction(f func(envs.Environment, types.XText, types.XText) types.XValue, defaultVal types.XText) types.XFunc

TextAndOptionalTextFunction creates an XFunc from a function that takes either one or two text args

func TextCompare added in v0.9.0 

func TextCompare(env envs.Environment, text1 types.XText, text2 types.XText) types.XValue

TextCompare returns the dictionary order of `text1` and `text2`.

The return value will be -1 if `text1` comes before `text2`, 0 if they are equal and 1 if `text1` comes after `text2`. 

@(text_compare("abc", "abc")) -> 0
@(text_compare("abc", "def")) -> -1
@(text_compare("zzz", "aaa")) -> 1

@function text_compare(text1, text2)

func TextLength added in v0.34.0 

func TextLength(env envs.Environment, value types.XText) types.XValue

TextLength returns the length (number of characters) of `value` when converted to text. 

@(text_length("abc")) -> 3
@(text_length(array(2, 3))) -> 6

@function text_length(value)

func TextSlice added in v0.37.0 

func TextSlice(env envs.Environment, text types.XText, args ...types.XValue) types.XValue

TextSlice returns the portion of `text` between `start` (inclusive) and `end` (exclusive).

If `end` is not specified then the entire rest of `text` will be included. Negative values for `start` or `end` start at the end of `text`. 

@(text_slice("hello", 2)) -> llo
@(text_slice("hello", 1, 3)) -> el
@(text_slice("hello😁", -3, -1)) -> lo
@(text_slice("hello", 7)) ->

@function text_slice(text, start [, end])

func ThreeArgFunction 

func ThreeArgFunction(f func(envs.Environment, types.XValue, types.XValue, types.XValue) types.XValue) types.XFunc

ThreeArgFunction creates an XFunc from a three-arg function

func ThreeIntegerFunction added in v0.28.0 

func ThreeIntegerFunction(f func(envs.Environment, int, int, int) types.XValue) types.XFunc

ThreeIntegerFunction creates an XFunc from a function that takes a text and an integer arg

func Time added in v0.28.0 

func Time(env envs.Environment, value types.XValue) types.XValue

Time tries to convert `value` to a time.

If it is text then it will be parsed into a time using the default time format. An error is returned if the value can't be converted. 

@(time("10:30")) -> 10:30:00.000000
@(time("10:30:45 PM")) -> 22:30:45.000000
@(time(datetime("1979-07-18T10:30:45.123456Z"))) -> 10:30:45.123456
@(time("what?")) -> ERROR

@function time(value)

func TimeFromParts added in v0.28.0 

func TimeFromParts(env envs.Environment, hour, minute, second int) types.XValue

TimeFromParts creates a time from `hour`, `minute` and `second` 

@(time_from_parts(14, 40, 15)) -> 14:40:15.000000
@(time_from_parts(8, 10, 0)) -> 08:10:00.000000
@(time_from_parts(25, 0, 0)) -> ERROR

@function time_from_parts(hour, minute, second)

func Title 

func Title(env envs.Environment, text types.XText) types.XValue

Title capitalizes each word in `text`. 

@(title("foo")) -> Foo
@(title("ryan lewis")) -> Ryan Lewis
@(title("RYAN LEWIS")) -> Ryan Lewis
@(title(123)) -> 123

@function title(text)

func Today 

func Today(env envs.Environment) types.XValue

Today returns the current date in the environment timezone. 

@(today()) -> 2018-04-11

@function today()

func Trim added in v0.76.2 

func Trim(env envs.Environment, text types.XText, chars types.XText) types.XValue

Trim removes whitespace from either end of `text`.

There is an optional final parameter `chars` which is string of characters to be removed instead of whitespace. 

@(trim(" hello world    ")) -> hello world
@(trim("+123157568", "+")) -> 123157568

@function trim(text, [,chars])

func TrimLeft added in v0.76.2 

func TrimLeft(env envs.Environment, text types.XText, chars types.XText) types.XValue

TrimLeft removes whitespace from the start of `text`.

There is an optional final parameter `chars` which is string of characters to be removed instead of whitespace. 

@("*" & trim_left(" hello world   ") & "*") -> *hello world   *
@(trim_left("+12345+", "+")) -> 12345+

@function trim_left(text, [,chars])

func TrimRight added in v0.76.2 

func TrimRight(env envs.Environment, text types.XText, chars types.XText) types.XValue

TrimRight removes whitespace from the end of `text`.

There is an optional final parameter `chars` which is string of characters to be removed instead of whitespace. 

@("*" & trim_right(" hello world   ") & "*") -> * hello world*
@(trim_right("+12345+", "+")) -> +12345

@function trim_right(text, [,chars])

func TwoArgFunction 

func TwoArgFunction(f func(envs.Environment, types.XValue, types.XValue) types.XValue) types.XFunc

TwoArgFunction creates an XFunc from a two-arg function

func TwoNumberFunction 

func TwoNumberFunction(f func(envs.Environment, types.XNumber, types.XNumber) types.XValue) types.XFunc

TwoNumberFunction creates an XFunc from a function that takes two numbers

func TwoTextFunction added in v0.9.0 

func TwoTextFunction(f func(envs.Environment, types.XText, types.XText) types.XValue) types.XFunc

TwoTextFunction creates an XFunc from a function that takes two text args

func URLEncode 

func URLEncode(env envs.Environment, text types.XText) types.XValue

URLEncode encodes `text` for use as a URL parameter. 

@(url_encode("two & words")) -> two%20%26%20words
@(url_encode(10)) -> 10

@function url_encode(text)

func URNParts added in v0.30.4 

func URNParts(env envs.Environment, urn types.XText) types.XValue

URNParts parses a URN into its different parts 

@(urn_parts("tel:+593979012345")) -> {display: , path: +593979012345, scheme: tel}
@(urn_parts("twitterid:3263621177#bobby")) -> {display: bobby, path: 3263621177, scheme: twitterid}
@(urn_parts("not a urn")) -> ERROR

@function urn_parts(urn)

func Unique added in v0.128.0 

func Unique(env envs.Environment, array *types.XArray) types.XValue

Unique returns the unique values in `array`. 

@(unique(array(1, 3, 2, 3))) -> [1, 3, 2]
@(unique(array("hi", "there", "hi"))) -> [hi, there]

@function unique(array)

func Upper 

func Upper(env envs.Environment, text types.XText) types.XValue

Upper converts `text` to uppercase. 

@(upper("Asdf")) -> ASDF
@(upper(123)) -> 123

@function upper(text)

func WeekNumber added in v0.44.0 

func WeekNumber(env envs.Environment, date types.XDate) types.XValue

WeekNumber returns the week number (1-54) of `date`.

The week is considered to start on Sunday and week containing Jan 1st is week number 1. 

@(week_number("2019-01-01")) -> 1
@(week_number("2019-07-23T16:56:59.000000Z")) -> 30
@(week_number("xx")) -> ERROR

@function week_number(date)

func Weekday 

func Weekday(env envs.Environment, date types.XDate) types.XValue

Weekday returns the day of the week for `date`.

The week is considered to start on Sunday so a Sunday returns 0, a Monday returns 1 etc. 

@(weekday("2017-01-15")) -> 0
@(weekday("foo")) -> ERROR

@function weekday(date)

func Word 

func Word(env envs.Environment, text types.XText, args ...types.XValue) types.XValue

Word returns the word at `index` in `text`.

Indexes start at zero. There is an optional final parameter `delimiters` which is string of characters used to split the text into words. 

@(word("bee cat dog", 0)) -> bee
@(word("bee.cat,dog", 0)) -> bee
@(word("bee.cat,dog", 1)) -> cat
@(word("bee.cat,dog", 2)) -> dog
@(word("bee.cat,dog", -1)) -> dog
@(word("bee.cat,dog", -2)) -> cat
@(word("bee.*cat,dog", 1, ".*=|")) -> cat,dog
@(word("O'Grady O'Flaggerty", 1, " ")) -> O'Flaggerty

@function word(text, index [,delimiters])

func WordCount 

func WordCount(env envs.Environment, text types.XText, delimiters types.XText) types.XValue

WordCount returns the number of words in `text`.

There is an optional final parameter `delimiters` which is string of characters used to split the text into words. 

@(word_count("foo bar")) -> 2
@(word_count(10)) -> 1
@(word_count("")) -> 0
@(word_count("😀😃😄😁")) -> 4
@(word_count("bee.*cat,dog", ".*=|")) -> 2
@(word_count("O'Grady O'Flaggerty", " ")) -> 2

@function word_count(text [,delimiters])

func WordSlice 

func WordSlice(env envs.Environment, text types.XText, args ...types.XValue) types.XValue

WordSlice extracts a sub-sequence of words from `text`.

The returned words are those from `start` up to but not-including `end`. Indexes start at zero and a negative end value means that all words after the start should be returned. There is an optional final parameter `delimiters` which is string of characters used to split the text into words. 

@(word_slice("bee cat dog", 0, 1)) -> bee
@(word_slice("bee cat dog", 0, 2)) -> bee cat
@(word_slice("bee cat dog", 1, -1)) -> cat dog
@(word_slice("bee cat dog", 1)) -> cat dog
@(word_slice("bee cat dog", 2, 3)) -> dog
@(word_slice("bee cat dog", 3, 10)) ->
@(word_slice("bee.*cat,dog", 1, -1, ".*=|,")) -> cat dog
@(word_slice("O'Grady O'Flaggerty", 1, 2, " ")) -> O'Flaggerty

@function word_slice(text, start, end [,delimiters])

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.