functions

package
v0.29.5 Latest Latest
Warning

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

 Go to latest Published: Mar 5, 2019 License: AGPL-3.0 Imports: 13 Imported by: 4

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var XFUNCTIONS = map[string]XFunction{

	"text":     OneArgFunction(Text),
	"boolean":  OneArgFunction(Boolean),
	"number":   OneArgFunction(Number),
	"date":     OneArgFunction(Date),
	"datetime": OneArgFunction(DateTime),
	"time":     OneArgFunction(Time),
	"array":    Array,

	"char":              OneNumberFunction(Char),
	"code":              OneTextFunction(Code),
	"split":             TwoTextFunction(Split),
	"join":              TwoArgFunction(Join),
	"title":             OneTextFunction(Title),
	"word":              InitialTextFunction(1, 2, Word),
	"remove_first_word": OneTextFunction(RemoveFirstWord),
	"word_count":        InitialTextFunction(0, 1, WordCount),
	"word_slice":        InitialTextFunction(1, 3, WordSlice),
	"field":             InitialTextFunction(2, 2, Field),
	"clean":             OneTextFunction(Clean),
	"left":              TextAndIntegerFunction(Left),
	"lower":             OneTextFunction(Lower),
	"right":             TextAndIntegerFunction(Right),
	"regex_match":       InitialTextFunction(1, 2, RegexMatch),
	"text_compare":      TwoTextFunction(TextCompare),
	"repeat":            TextAndIntegerFunction(Repeat),
	"replace":           ThreeTextFunction(Replace),
	"upper":             OneTextFunction(Upper),
	"percent":           OneNumberFunction(Percent),
	"url_encode":        OneTextFunction(URLEncode),

	"and": ArgCountCheck(1, -1, And),
	"if":  ThreeArgFunction(If),
	"or":  ArgCountCheck(1, -1, Or),

	"round":        OneNumberAndOptionalIntegerFunction(Round, 0),
	"round_up":     OneNumberAndOptionalIntegerFunction(RoundUp, 0),
	"round_down":   OneNumberAndOptionalIntegerFunction(RoundDown, 0),
	"max":          ArgCountCheck(1, -1, Max),
	"min":          ArgCountCheck(1, -1, Min),
	"mean":         ArgCountCheck(1, -1, Mean),
	"mod":          TwoNumberFunction(Mod),
	"rand":         NoArgFunction(Rand),
	"rand_between": TwoNumberFunction(RandBetween),
	"abs":          OneNumberFunction(Abs),

	"parse_datetime":      ArgCountCheck(2, 3, ParseDateTime),
	"datetime_from_epoch": OneNumberFunction(DateTimeFromEpoch),
	"datetime_diff":       ThreeArgFunction(DateTimeDiff),
	"datetime_add":        DateTimeAdd,
	"replace_time":        ArgCountCheck(2, 2, ReplaceTime),
	"tz":                  OneDateTimeFunction(TZ),
	"tz_offset":           OneDateTimeFunction(TZOffset),
	"now":                 NoArgFunction(Now),
	"epoch":               OneDateTimeFunction(Epoch),

	"date_from_parts": ThreeIntegerFunction(DateFromParts),
	"weekday":         OneDateFunction(Weekday),
	"today":           NoArgFunction(Today),

	"parse_time":      ArgCountCheck(2, 2, ParseTime),
	"time_from_parts": ThreeIntegerFunction(TimeFromParts),

	"json":       OneArgFunction(JSON),
	"parse_json": OneTextFunction(ParseJSON),

	"format_date":     ArgCountCheck(1, 2, FormatDate),
	"format_datetime": ArgCountCheck(1, 3, FormatDateTime),
	"format_time":     ArgCountCheck(1, 2, FormatTime),
	"format_location": OneTextFunction(FormatLocation),
	"format_number":   FormatNumber,
	"format_urn":      OneTextFunction(FormatURN),

	"length":     OneArgFunction(Length),
	"default":    TwoArgFunction(Default),
	"legacy_add": TwoArgFunction(LegacyAdd),
	"read_chars": OneTextFunction(ReadChars),
}

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

Functions

func Abs 

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

Abs returns the absolute value of `num`. 

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

@function abs(num)

func And 

func And(env utils.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 utils.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
@(length(array())) -> 0
@(length(array("a", "b"))) -> 2

@function array(values...)

func Boolean added in v0.9.0 

func Boolean(env utils.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 utils.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 utils.Environment, text types.XText) types.XValue

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

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

@function clean(text)

func Code 

func Code(env utils.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 Date 

func Date(env utils.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("2010 05 10")) -> 2010-05-10
@(date("NOT DATE")) -> ERROR

@function date(value)

func DateFromParts 

func DateFromParts(env utils.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 utils.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("2010 05 10")) -> 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 utils.Environment, args ...types.XValue) types.XValue

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

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(date, offset, unit)

func DateTimeDiff added in v0.9.0 

func DateTimeDiff(env utils.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 utils.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 utils.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(array(1, 2), "value")) -> 1, 2
@(default(array(), "value")) -> value
@(default(datetime("invalid-date"), "today")) -> today

@function default(value, default)

func Epoch added in v0.13.1 

func Epoch(env utils.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 Field 

func Field(env utils.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 FormatDate 

func FormatDate(env utils.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 01-12 * `D` - day of month, 1-31 * `DD` - day of month, zero padded 0-31 

@(format_date("1979-07-18T15:00:00.000000Z")) -> 1979-07-18
@(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 utils.Environment, args ...types.XValue) types.XValue

FormatDateTime 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 01-12 * `D` - day of month, 1-31 * `DD` - day of month, zero padded 0-31 * `h` - hour of the day 1-12 * `hh` - hour of the day 01-12 * `tt` - twenty four hour of the day 01-23 * `m` - minute 0-59 * `mm` - minute 00-59 * `s` - second 0-59 * `ss` - second 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. 

@(format_datetime("1979-07-18T15:00:00.000000Z")) -> 1979-07-18 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 tt: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(date [,format [,timezone]])

func FormatDecimal added in v0.21.2 

func FormatDecimal(value decimal.Decimal, format *utils.NumberFormat, places int, groupDigits bool) string

FormatDecimal formats the given decimal

func FormatLocation added in v0.9.4 

func FormatLocation(env utils.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 utils.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(31337)) -> 31,337.00
@(format_number(31337, 2)) -> 31,337.00
@(format_number(31337, 2, true)) -> 31,337.00
@(format_number(31337, 0, false)) -> 31337
@(format_number("foo", 2, false)) -> ERROR

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

func FormatTime added in v0.28.0 

func FormatTime(env utils.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 01-12 * `tt` - twenty four hour of the day 01-23 * `m` - minute 0-59 * `mm` - minute 00-59 * `s` - second 0-59 * `ss` - second 00-59 * `fff` - milliseconds * `ffffff` - microseconds * `fffffffff` - nanoseconds * `aa` - am or pm * `AA` - AM or PM 

@(format_time("14:50:30.000000")) -> 02:50
@(format_time("14:50:30.000000", "h:mm aa")) -> 2:50 pm
@(format_time("14:50:30.000000", "tt:mm")) -> 14:50
@(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 utils.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)) -> (206) 555-1212
@(format_urn(contact.urns.mailto[0])) -> foo@bar.com
@(format_urn(contact.urns.telegram[0])) ->
@(format_urn(contact.urns[2])) -> foo@bar.com
@(format_urn("NOT URN")) -> ERROR

@function format_urn(urn)

func If 

func If(env utils.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 JSON 

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

JSON returns the JSON representation of `value`. 

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

@function json(value)

func Join 

func Join(env utils.Environment, array types.XValue, separator 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 Left 

func Left(env utils.Environment, text types.XText, count int) types.XValue

Left returns the `count` left-most characters in `text` 

@(left("hello", 2)) -> he
@(left("hello", 7)) -> hello
@(left("😀😃😄😁", 2)) -> 😀😃
@(left("hello", -1)) -> ERROR

@function left(text, count)

func LegacyAdd 

func LegacyAdd(env utils.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 Length 

func Length(env utils.Environment, value types.XValue) types.XValue

Length returns the length of the passed in text or array.

length will return an error if it is passed an item which doesn't have length. 

@(length("Hello")) -> 5
@(length(contact.fields.gender)) -> 4
@(length("😀😃😄😁")) -> 4
@(length(array())) -> 0
@(length(array("a", "b", "c"))) -> 3
@(length(1234)) -> ERROR

@function length(value)

func Lower 

func Lower(env utils.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 utils.Environment, values ...types.XValue) types.XValue

Max returns the maximum value in `values`. 

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

@function max(values...)

func Mean 

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

Mean returns the arithmetic mean of the numbers in `values`. 

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

@function mean(values)

func Min 

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

Min returns the minimum value in `values`. 

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

@function min(values)

func Mod 

func Mod(env utils.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 Now 

func Now(env utils.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 Number 

func Number(env utils.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 Or 

func Or(env utils.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 utils.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 01-12 * `D` - day of month, 1-31 * `DD` - day of month, zero padded 0-31 * `h` - hour of the day 1-12 * `hh` - hour of the day 01-12 * `tt` - twenty four hour of the day 01-23 * `m` - minute 0-59 * `mm` - minute 00-59 * `s` - second 0-59 * `ss` - second 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 utils.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 utils.Environment, args ...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 01-12 * `tt` - twenty four hour of the day 01-23 * `m` - minute 0-59 * `mm` - minute 00-59 * `s` - second 0-59 * `ss` - second 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 utils.Environment, num types.XNumber) types.XValue

Percent formats `num` as a percentage. 

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

@function percent(num)

func Rand 

func Rand(env utils.Environment) types.XValue

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

@(rand()) -> 0.3849275689214193274523267973563633859157562255859375
@(rand()) -> 0.607552015674623913099594574305228888988494873046875

@function rand()

func RandBetween 

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

RandBetween a single random integer in the given inclusive range. 

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

@function rand_between()

func ReadChars added in v0.9.4 

func ReadChars(env utils.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 utils.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, function XFunction)

RegisterXFunction registers a new function in Excellent

func RemoveFirstWord 

func RemoveFirstWord(env utils.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 utils.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 utils.Environment, text types.XText, needle types.XText, replacement types.XText) types.XValue

Replace replaces all occurrences of `needle` with `replacement` in `text`. 

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

@function replace(text, needle, replacement)

func ReplaceTime added in v0.28.0 

func ReplaceTime(env utils.Environment, args ...types.XValue) types.XValue

ReplaceTime returns the a new date time 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(date) 

func Right(env utils.Environment, text types.XText, count int) types.XValue

Right returns the `count` right-most characters in `text` 

@(right("hello", 2)) -> lo
@(right("hello", 7)) -> hello
@(right("😀😃😄😁", 2)) -> 😄😁
@(right("hello", -1)) -> ERROR

@function right(text, count)

func Round 

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

Round rounds `num` 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(num [,places])

func RoundDown 

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

RoundDown rounds `num` 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(num [,places])

func RoundUp 

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

RoundUp rounds `num` 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(num [,places])

func Split 

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

Split splits `text` based on the given characters in `delimiters`.

Empty values are removed from the returned list. 

@(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 TZ 

func TZ(env utils.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 utils.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 utils.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 TextCompare added in v0.9.0 

func TextCompare(env utils.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 Time added in v0.28.0 

func Time(env utils.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 utils.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 utils.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 utils.Environment) types.XValue

Today returns the current date in the environment timezone. 

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

@function today()

func URLEncode 

func URLEncode(env utils.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 Upper 

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

Upper converts `text` to lowercase. 

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

@function upper(text)

func Weekday 

func Weekday(env utils.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 utils.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 utils.Environment, text types.XText, args ...types.XValue) 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 utils.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

type XFunction 

type XFunction func(env utils.Environment, args ...types.XValue) types.XValue

XFunction defines the interface that Excellent functions must implement

func ArgCountCheck 

func ArgCountCheck(min int, max int, f XFunction) XFunction

ArgCountCheck wraps an XFunction and checks the number of args

func InitialTextFunction added in v0.10.17 

func InitialTextFunction(minOtherArgs int, maxOtherArgs int, f func(utils.Environment, types.XText, ...types.XValue) types.XValue) XFunction

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

func NoArgFunction 

func NoArgFunction(f func(utils.Environment) types.XValue) XFunction

NoArgFunction creates an XFunction from a no-arg function

func OneArgFunction 

func OneArgFunction(f func(utils.Environment, types.XValue) types.XValue) XFunction

OneArgFunction creates an XFunction from a single-arg function

func OneDateFunction 

func OneDateFunction(f func(utils.Environment, types.XDate) types.XValue) XFunction

OneDateFunction creates an XFunction from a single date function

func OneDateTimeFunction added in v0.9.0 

func OneDateTimeFunction(f func(utils.Environment, types.XDateTime) types.XValue) XFunction

OneDateTimeFunction creates an XFunction from a single datetime function

func OneNumberAndOptionalIntegerFunction 

func OneNumberAndOptionalIntegerFunction(f func(utils.Environment, types.XNumber, int) types.XValue, defaultVal int) XFunction

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

func OneNumberFunction 

func OneNumberFunction(f func(utils.Environment, types.XNumber) types.XValue) XFunction

OneNumberFunction creates an XFunction from a single number function

func OneTextFunction added in v0.9.0 

func OneTextFunction(f func(utils.Environment, types.XText) types.XValue) XFunction

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

func TextAndDateFunction added in v0.9.0 

func TextAndDateFunction(f func(utils.Environment, types.XText, types.XDateTime) types.XValue) XFunction

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

func TextAndIntegerFunction added in v0.9.0 

func TextAndIntegerFunction(f func(utils.Environment, types.XText, int) types.XValue) XFunction

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

func TextAndNumberFunction added in v0.9.0 

func TextAndNumberFunction(f func(utils.Environment, types.XText, types.XNumber) types.XValue) XFunction

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

func ThreeArgFunction 

func ThreeArgFunction(f func(utils.Environment, types.XValue, types.XValue, types.XValue) types.XValue) XFunction

ThreeArgFunction creates an XFunction from a three-arg function

func ThreeIntegerFunction added in v0.28.0 

func ThreeIntegerFunction(f func(utils.Environment, int, int, int) types.XValue) XFunction

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

func ThreeTextFunction added in v0.9.0 

func ThreeTextFunction(f func(utils.Environment, types.XText, types.XText, types.XText) types.XValue) XFunction

ThreeTextFunction creates an XFunction from a function that takes three text args

func TwoArgFunction 

func TwoArgFunction(f func(utils.Environment, types.XValue, types.XValue) types.XValue) XFunction

TwoArgFunction creates an XFunction from a two-arg function

func TwoNumberFunction 

func TwoNumberFunction(f func(utils.Environment, types.XNumber, types.XNumber) types.XValue) XFunction

TwoNumberFunction creates an XFunction from a function that takes two numbers

func TwoTextFunction added in v0.9.0 

func TwoTextFunction(f func(utils.Environment, types.XText, types.XText) types.XValue) XFunction

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

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.