Merge branch 'main' into node_categories

Author: rowanseymour

cmd/docgen/docs/base_test.go

@@ -43,7 +43,7 @@ func TestGenerateDocs(t *testing.T) {
 	context := completion["context"].(map[string]any)
 	functions := completion["functions"].([]any)
 
-	assert.Equal(t, 89, len(functions))
+	assert.Equal(t, 90, len(functions))
 
 	types := context["types"].([]any)
 	assert.Equal(t, 21, len(types))

excellent/functions/builtin.go

@@ -103,14 +103,15 @@ func init() {
 		"time_from_parts": ThreeIntegerFunction(TimeFromParts),
 
 		// array functions
-		"contains": TwoArgFunction(Contains),
-		"join":     TwoArgFunction(Join),
+		"slice":    InitialArrayFunction(1, 2, Slice),
+		"contains": InitialArrayFunction(1, 1, Contains),
+		"join":     InitialArrayFunction(1, 1, Join),
 		"reverse":  OneArrayFunction(Reverse),
 		"sort":     OneArrayFunction(Sort),
 		"sum":      OneArrayFunction(Sum),
 		"unique":   OneArrayFunction(Unique),
 		"concat":   TwoArrayFunction(Concat),
-		"filter":   TwoArgFunction(Filter),
+		"filter":   InitialArrayFunction(1, 1, Filter),
 
 		// encoded text functions
 		"urn_parts":        OneTextFunction(URNParts),
@@ -1518,23 +1519,55 @@ func TimeFromParts(env envs.Environment, hour, minute, second int) types.XValue
 // Array Functions
 //------------------------------------------------------------------------------------------
 
+// Slice extracts a sub-sequence of items from `array`.
+//
+// The returned items are those from `start` up to but not-including `end`. Indexes start at zero and a negative
+// end value counts back from the end.
+//
+//	@(slice(array("a", "b", "c"), 0, 2)) -> [a, b]
+//	@(slice(array("a", "b", "c"), 1, 3)) -> [b, c]
+//	@(slice(array("a", "b", "c"), 0, -1)) -> [a, b]
+//	@(slice(array("a", "b", "c"), 1)) -> [b, c]
+//	@(slice(array("a", "b", "c"), 10)) -> []
+//
+// @function slice(array, start, [,end])
+func Slice(env envs.Environment, array *types.XArray, args ...types.XValue) types.XValue {
+	start, xerr := types.ToInteger(env, args[0])
+	if xerr != nil {
+		return xerr
+	}
+	if start < 0 {
+		return types.NewXErrorf("must start with a positive index")
+	}
+
+	end := array.Count()
+	if len(args) == 2 {
+		if end, xerr = types.ToInteger(env, args[1]); xerr != nil {
+			return xerr
+		}
+	}
+
+	start = min(start, array.Count())
+	if end < 0 {
+		end = max(start, array.Count()+end)
+	}
+
+	return array.Slice(start, end)
+}
+
 // Contains returns whether `array` contains `value`.
 //
 //	@(contains(array("a", "b", "c"), "a")) -> true
 //	@(contains(array(1, 2, 3), 4)) -> false
 //
 // @function contains(array, value)
-func Contains(env envs.Environment, arg1 types.XValue, value types.XValue) types.XValue {
-	array, xerr := types.ToXArray(env, arg1)
-	if xerr != nil {
-		return xerr
-	}
-	if types.IsXError(value) {
-		return value
+func Contains(env envs.Environment, array *types.XArray, args ...types.XValue) types.XValue {
+	if types.IsXError(args[0]) {
+		return args[0]
 	}
 
-	for i := 0; i < array.Count(); i++ {
-		if types.Equals(array.Get(i), value) {
+	for i := range array.Count() {
+		if types.Equals(array.Get(i), args[0]) {
 			return types.XBooleanTrue
 		}
 	}
@@ -1548,13 +1581,8 @@ func Contains(env envs.Environment, arg1 types.XValue, value types.XValue) types
 //	@(join(split("a.b.c", "."), " ")) -> a b c
 //
 // @function join(array, separator)
-func Join(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue {
-	array, xerr := types.ToXArray(env, arg1)
-	if xerr != nil {
-		return xerr
-	}
-
-	separator, xerr := types.ToXText(env, arg2)
+func Join(env envs.Environment, array *types.XArray, args ...types.XValue) types.XValue {
+	separator, xerr := types.ToXText(env, args[0])
 	if xerr != nil {
 		return xerr
 	}
@@ -1700,12 +1728,8 @@ func Concat(env envs.Environment, array1 *types.XArray, array2 *types.XArray) ty
 //	@(filter(array("a", "b", "c"), (x) => x != "c")) -> [a, b]
 //
 // @function filter(array, func)
-func Filter(env envs.Environment, arg1 types.XValue, arg2 types.XValue) types.XValue {
-	array, xerr := types.ToXArray(env, arg1)
-	if xerr != nil {
-		return xerr
-	}
-	function, xerr := types.ToXFunction(arg2)
+func Filter(env envs.Environment, array *types.XArray, args ...types.XValue) types.XValue {
+	function, xerr := types.ToXFunction(args[0])
 	if xerr != nil {
 		return xerr
 	}

excellent/functions/builtin_test.go

@@ -586,6 +586,14 @@ func TestFunctions(t *testing.T) {
 		{"round_up", dmy, []types.XValue{xs("not_num")}, ERROR},
 		{"round_up", dmy, []types.XValue{}, ERROR},
 
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(0), xi(2)}, xa(xs("a"), xs("b"))},
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(1), xi(3)}, xa(xs("b"), xs("c"))},
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(1)}, xa(xs("b"), xs("c"))},
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(0), xi(-1)}, xa(xs("a"), xs("b"))},
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(10)}, xa()},
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(0), xi(-10)}, xa()},
+		{"slice", dmy, []types.XValue{xa(xs("a"), xs("b"), xs("c")), xi(-1)}, ERROR},
+
 		{"sort", dmy, []types.XValue{xa()}, xa()},
 		{"sort", dmy, []types.XValue{xa(xn("3"))}, xa(xn("3"))},
 		{"sort", dmy, []types.XValue{xa(xn("3"), xn("1"), xn("2"))}, xa(xn("1"), xn("2"), xn("3"))},

excellent/functions/wrappers.go

@@ -192,6 +192,17 @@ func InitialTextFunction(minOtherArgs int, maxOtherArgs int, f func(envs.Environ
 	})
 }
 
+// InitialArrayFunction creates an XFunc from a function that takes an initial array arg followed by other args
+func InitialArrayFunction(minOtherArgs int, maxOtherArgs int, f func(envs.Environment, *types.XArray, ...types.XValue) types.XValue) types.XFunc {
+	return MinAndMaxArgsCheck(minOtherArgs+1, maxOtherArgs+1, func(env envs.Environment, args ...types.XValue) types.XValue {
+		arr, xerr := types.ToXArray(env, args[0])
+		if xerr != nil {
+			return xerr
+		}
+		return f(env, arr, args[1:]...)
+	})
+}
+
 // OneNumberFunction creates an XFunc from a single number function
 func OneNumberFunction(f func(envs.Environment, *types.XNumber) types.XValue) types.XFunc {
 	return NumArgsCheck(1, func(env envs.Environment, args ...types.XValue) types.XValue {

excellent/types/array.go

@@ -44,6 +44,11 @@ func (x *XArray) Get(index int) XValue {
 	return x.values()[index]
 }
 
+// Get is called when this object is indexed
+func (x *XArray) Slice(start, end int) *XArray {
+	return NewXArray(x.values()[start:end]...)
+}
+
 // Count is called when the length of this object is requested in an expression
 func (x *XArray) Count() int {
 	return len(x.values())

locale/cs/flows.po

@@ -6,7 +6,7 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"POT-Creation-Date: 2025-04-02 15:22-0500\n"
+"POT-Creation-Date: 2025-04-03 14:28-0500\n"
 "Last-Translator: trendspotter <[email protected]>, 2021\n"
 "Language-Team: Czech (https://www.transifex.com/rapidpro/teams/226/cs/)\n"
 "Language: cs\n"
@@ -69,6 +69,11 @@ msgstr ""
 msgid "Encodes `text` for use as a URL parameter."
 msgstr "Zakóduje `text` pro použití jako parametr URL."
 
+#, fuzzy
+#| msgid "Extracts a sub-sequence of words from `text`."
+msgid "Extracts a sub-sequence of items from `array`."
+msgstr "Extrahuje dílčí posloupnost slov z `text`."
+
 msgid "Extracts a sub-sequence of words from `text`."
 msgstr "Extrahuje dílčí posloupnost slov z `text`."
 
@@ -344,6 +349,9 @@ msgstr "Vrátí nové pole s hodnotami `array` seřazenými."
 msgid "Returns a new datetime with the time part replaced by the `time`."
 msgstr "Vrátí nový datetime s časovou částí nahrazenou hodnotou `time`."
 
+msgid "Returns a pre-defined LLM prompt."
+msgstr ""
+
 msgid "Returns a single random number between [0.0-1.0)."
 msgstr "Vrátí jedno náhodné číslo v rozsahu [0.0-1.0)."
 
@@ -594,6 +602,16 @@ msgid ""
 "and 1 if `text1` comes after `text2`."
 msgstr "Návratová hodnota bude -1, pokud je `text1` před `text2`, 0, pokud jsou stejné, a 1, pokud je `text1` za `text2`."
 
+#, fuzzy
+#| msgid ""
+#| "The returned words are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+#| "end value means that all words after the start should be returned. There is an optional final parameter `delimiters`\n"
+#| "which is string of characters used to split the text into words."
+msgid ""
+"The returned items are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+"end value counts back from the end."
+msgstr "Vrácená slova jsou slova od `start` až po `end`, ale bez něj. Indexy začínají nulou a záporná hodnota konce znamená, že by měla být vrácena všechna slova po začátku. K dispozici je nepovinný koncový parametr `delimiters`, což je řetězec znaků použitý k rozdělení textu na slova."
+
 msgid "The returned number can contain fractional seconds."
 msgstr "Vrácené číslo může obsahovat zlomky sekund."
 

locale/en_US/flows.po

@@ -3,7 +3,7 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"POT-Creation-Date: 2025-04-02 15:22-0500\n"
+"POT-Creation-Date: 2025-04-03 14:28-0500\n"
 "Language: en_US\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
@@ -61,6 +61,9 @@ msgstr ""
 msgid "Encodes `text` for use as a URL parameter."
 msgstr ""
 
+msgid "Extracts a sub-sequence of items from `array`."
+msgstr ""
+
 msgid "Extracts a sub-sequence of words from `text`."
 msgstr ""
 
@@ -272,6 +275,9 @@ msgstr ""
 msgid "Returns a new datetime with the time part replaced by the `time`."
 msgstr ""
 
+msgid "Returns a pre-defined LLM prompt."
+msgstr ""
+
 msgid "Returns a single random number between [0.0-1.0)."
 msgstr ""
 
@@ -467,6 +473,11 @@ msgid ""
 "and 1 if `text1` comes after `text2`."
 msgstr ""
 
+msgid ""
+"The returned items are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+"end value counts back from the end."
+msgstr ""
+
 msgid "The returned number can contain fractional seconds."
 msgstr ""
 

locale/es/flows.po

@@ -8,7 +8,7 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"POT-Creation-Date: 2025-04-02 15:22-0500\n"
+"POT-Creation-Date: 2025-04-03 14:28-0500\n"
 "Last-Translator: Rowan Seymour <[email protected]>, 2022\n"
 "Language-Team: Spanish (https://www.transifex.com/rapidpro/teams/226/es/)\n"
 "Language: es\n"
@@ -71,6 +71,11 @@ msgstr ""
 msgid "Encodes `text` for use as a URL parameter."
 msgstr "Codifica `text` para utilizarlo como parámetro de URL."
 
+#, fuzzy
+#| msgid "Extracts a sub-sequence of words from `text`."
+msgid "Extracts a sub-sequence of items from `array`."
+msgstr "Extrae una subsecuencia de palabras de `text`."
+
 msgid "Extracts a sub-sequence of words from `text`."
 msgstr "Extrae una subsecuencia de palabras de `text`."
 
@@ -360,6 +365,9 @@ msgstr "Devuelve un nuevo array de los valores de `array` ordenados."
 msgid "Returns a new datetime with the time part replaced by the `time`."
 msgstr "Devuelve una nueva fecha y hora con la parte de la hora reemplazada por `hour`."
 
+msgid "Returns a pre-defined LLM prompt."
+msgstr ""
+
 msgid "Returns a single random number between [0.0-1.0)."
 msgstr "Devuelve un solo número aleatorio entre [0.0-1.0)."
 
@@ -619,6 +627,19 @@ msgstr ""
 "El valor de retorno será -1 si `text1` viene antes de` text2`, 0 si son iguales\n"
 "y 1 si `text1` viene después de` text2`."
 
+#, fuzzy
+#| msgid ""
+#| "The returned words are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+#| "end value means that all words after the start should be returned. There is an optional final parameter `delimiters`\n"
+#| "which is string of characters used to split the text into words."
+msgid ""
+"The returned items are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+"end value counts back from the end."
+msgstr ""
+"Las palabras devueltas son las que van desde `start` hasta `end`, pero sin incluirlas. Los índices comienzan en cero y en negativo.\n"
+"valor final significa que se deben devolver todas las palabras después del inicio. Hay un parámetro final opcional `delimiters`\n"
+"que es una cadena de caracteres utilizada para dividir el texto en palabras."
+
 msgid "The returned number can contain fractional seconds."
 msgstr "El número devuelto puede contener fracciones de segundo."
 

locale/fr/flows.po

@@ -3,7 +3,7 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"POT-Creation-Date: 2025-04-02 15:22-0500\n"
+"POT-Creation-Date: 2025-04-03 14:28-0500\n"
 "Language-Team: French (https://www.transifex.com/rapidpro/teams/226/fr/)\n"
 "Language: fr\n"
 "MIME-Version: 1.0\n"
@@ -63,6 +63,9 @@ msgstr ""
 msgid "Encodes `text` for use as a URL parameter."
 msgstr ""
 
+msgid "Extracts a sub-sequence of items from `array`."
+msgstr ""
+
 msgid "Extracts a sub-sequence of words from `text`."
 msgstr ""
 
@@ -274,6 +277,9 @@ msgstr ""
 msgid "Returns a new datetime with the time part replaced by the `time`."
 msgstr ""
 
+msgid "Returns a pre-defined LLM prompt."
+msgstr ""
+
 msgid "Returns a single random number between [0.0-1.0)."
 msgstr ""
 
@@ -469,6 +475,11 @@ msgid ""
 "and 1 if `text1` comes after `text2`."
 msgstr ""
 
+msgid ""
+"The returned items are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+"end value counts back from the end."
+msgstr ""
+
 msgid "The returned number can contain fractional seconds."
 msgstr ""
 

locale/mn/flows.po

@@ -3,7 +3,7 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"POT-Creation-Date: 2025-04-02 15:22-0500\n"
+"POT-Creation-Date: 2025-04-03 14:28-0500\n"
 "Language-Team: Mongolian (https://www.transifex.com/rapidpro/teams/226/mn/)\n"
 "Language: mn\n"
 "MIME-Version: 1.0\n"
@@ -63,6 +63,9 @@ msgstr ""
 msgid "Encodes `text` for use as a URL parameter."
 msgstr ""
 
+msgid "Extracts a sub-sequence of items from `array`."
+msgstr ""
+
 msgid "Extracts a sub-sequence of words from `text`."
 msgstr ""
 
@@ -274,6 +277,9 @@ msgstr ""
 msgid "Returns a new datetime with the time part replaced by the `time`."
 msgstr ""
 
+msgid "Returns a pre-defined LLM prompt."
+msgstr ""
+
 msgid "Returns a single random number between [0.0-1.0)."
 msgstr ""
 
@@ -469,6 +475,11 @@ msgid ""
 "and 1 if `text1` comes after `text2`."
 msgstr ""
 
+msgid ""
+"The returned items are those from `start` up to but not-including `end`. Indexes start at zero and a negative\n"
+"end value counts back from the end."
+msgstr ""
+
 msgid "The returned number can contain fractional seconds."
 msgstr ""