bloblang: create category general and register functions without cate…

…gory under a proper category

internal/bloblang/query/docs.go

@@ -164,6 +164,7 @@ func NewHiddenFunctionSpec(name string) FunctionSpec {
 
 // Method categories.
 var (
+	MethodCategoryGeneral        = "General"
 	MethodCategoryStrings        = "String Manipulation"
 	MethodCategoryNumbers        = "Number Manipulation"
 	MethodCategoryTime           = "Timestamp Manipulation"

internal/bloblang/query/methods.go

@@ -13,9 +13,8 @@ import (
 )
 
 var _ = registerMethod(
-	NewMethodSpec(
-		"apply",
-		"Apply a declared mapping to a target value.",
+	NewMethodSpec("apply", "Apply a declared mapping to a target value.").InCategory(
+		MethodCategoryGeneral, "",
 		NewExampleSpec("",
 			`map thing {
   root.inner = this.first
@@ -146,9 +145,8 @@ func boolMethod(target Function, args *ParsedParams) (Function, error) {
 //------------------------------------------------------------------------------
 
 var _ = registerMethod(
-	NewMethodSpec(
-		"catch",
-		"If the result of a target query fails (due to incorrect types, failed parsing, etc) the argument is returned instead.",
+	NewMethodSpec("catch", "If the result of a target query fails (due to incorrect types, failed parsing, etc) the argument is returned instead.").InCategory(
+		MethodCategoryGeneral, "",
 		NewExampleSpec("",
 			`root.doc.id = this.thing.id.string().catch(uuid_v4())`,
 		),
@@ -185,9 +183,8 @@ func catchMethod(fn Function, args *ParsedParams) (Function, error) {
 //------------------------------------------------------------------------------
 
 var _ = registerMethod(
-	NewMethodSpec(
-		"from",
-		"Modifies a target query such that certain functions are executed from the perspective of another message in the batch. This allows you to mutate events based on the contents of other messages. Functions that support this behavior are `content`, `json` and `meta`.",
+	NewMethodSpec("from", "Modifies a target query such that certain functions are executed from the perspective of another message in the batch. This allows you to mutate events based on the contents of other messages. Functions that support this behavior are `content`, `json` and `meta`.").InCategory(
+		MethodCategoryGeneral, "",
 		NewExampleSpec("For example, the following map extracts the contents of the JSON field `foo` specifically from message index `1` of a batch, effectively overriding the field `foo` for all messages of a batch to that of message 1:",
 			`root = this
 root.foo = json("foo").from(1)`,
@@ -227,9 +224,8 @@ func (f *fromMethod) QueryTargets(ctx TargetsContext) (TargetsContext, []TargetP
 //------------------------------------------------------------------------------
 
 var _ = registerMethod(
-	NewMethodSpec(
-		"from_all",
-		"Modifies a target query such that certain functions are executed from the perspective of each message in the batch, and returns the set of results as an array. Functions that support this behavior are `content`, `json` and `meta`.",
+	NewMethodSpec("from_all", "Modifies a target query such that certain functions are executed from the perspective of each message in the batch, and returns the set of results as an array. Functions that support this behavior are `content`, `json` and `meta`.").InCategory(
+		MethodCategoryGeneral, "",
 		NewExampleSpec("",
 			`root = this
 root.foo_summed = json("foo").from_all().sum()`,
@@ -334,8 +330,9 @@ func getMethodCtor(target Function, args *ParsedParams) (Function, error) {
 //------------------------------------------------------------------------------
 
 var _ = registerMethod(
-	NewHiddenMethodSpec("map").
-		Param(ParamQuery("query", "A query to execute on the target.", false)),
+	NewMethodSpec("map", "Executes a query on the target value, allowing you to transform or extract data from the current context.").InCategory(
+		MethodCategoryGeneral, "",
+	).Param(ParamQuery("query", "A query to execute on the target.", false)),
 	mapMethod,
 )
 
@@ -366,7 +363,12 @@ func mapMethod(target Function, args *ParsedParams) (Function, error) {
 
 //------------------------------------------------------------------------------
 
-var _ = registerMethod(NewHiddenMethodSpec("not"), notMethodCtor)
+var _ = registerMethod(
+	NewMethodSpec("not", "Returns the logical NOT (negation) of a boolean value. Converts true to false and false to true.").InCategory(
+		MethodCategoryGeneral, "",
+	),
+	notMethodCtor,
+)
 
 type notMethod struct {
 	fn Function
@@ -512,8 +514,8 @@ func timestampCoerceMethod(target Function, args *ParsedParams) (Function, error
 //------------------------------------------------------------------------------
 
 var _ = registerMethod(
-	NewMethodSpec(
-		"or", "If the result of the target query fails or resolves to `null`, returns the argument instead. This is an explicit method alternative to the coalesce pipe operator `|`.",
+	NewMethodSpec("or", "If the result of the target query fails or resolves to `null`, returns the argument instead. This is an explicit method alternative to the coalesce pipe operator `|`.").InCategory(
+		MethodCategoryGeneral, "",
 		NewExampleSpec("", `root.doc.id = this.thing.id.or(uuid_v4())`),
 	).Param(ParamQuery("fallback", "A value to yield, or query to execute, if the target query fails or resolves to `null`.", true)),
 	orMethod,

internal/bloblang/query/methods_strings.go

@@ -1570,7 +1570,9 @@ var _ = registerSimpleMethod(
 //------------------------------------------------------------------------------
 
 var _ = registerSimpleMethod(
-	NewHiddenMethodSpec("replace").
+	NewMethodSpec("replace", "Replaces all occurrences of a substring with another string. Use for text transformation, cleaning data, or normalizing strings.").InCategory(
+		MethodCategoryStrings, "",
+	).
 		Param(ParamString("old", "A string to match against.")).
 		Param(ParamString("new", "A string to replace with.")),
 	replaceAllImpl,
@@ -1622,7 +1624,9 @@ func replaceAllImpl(args *ParsedParams) (simpleMethod, error) {
 //------------------------------------------------------------------------------
 
 var _ = registerSimpleMethod(
-	NewHiddenMethodSpec("replace_many").
+	NewMethodSpec("replace_many", "Performs multiple find-and-replace operations in sequence using an array of `[old, new]` pairs. More efficient than chaining multiple `replace_all` calls. Use for bulk text transformations.").InCategory(
+		MethodCategoryStrings, "",
+	).
 		Param(ParamArray("values", "An array of values, each even value will be replaced with the following odd value.")),
 	replaceAllManyImpl,
 )
@@ -1966,7 +1970,9 @@ var _ = registerSimpleMethod(
 //------------------------------------------------------------------------------
 
 var _ = registerSimpleMethod(
-	NewHiddenMethodSpec("re_replace").
+	NewMethodSpec("re_replace", "Replaces all regex matches with a replacement string that can reference capture groups using `$1`, `$2`, etc. Use for pattern-based transformations or data reformatting.").InCategory(
+		MethodCategoryRegexp, "",
+	).
 		Param(ParamString("pattern", "The pattern to match against.")).
 		Param(ParamString("value", "The value to replace with.")),
 	reReplaceAllImpl,

internal/bloblang/query/methods_structured.go

@@ -300,9 +300,8 @@ var _ = registerSimpleMethod(
 //------------------------------------------------------------------------------
 
 var _ = registerSimpleMethod(
-	NewMethodSpec(
-		"exists",
-		"Checks whether a field exists at the specified dot path within an object. Returns true if the field is present (even if null), false otherwise.",
+	NewMethodSpec("exists", "Checks whether a field exists at the specified dot path within an object. Returns true if the field is present (even if null), false otherwise.").InCategory(
+		MethodCategoryObjectAndArray, "",
 		NewExampleSpec("",
 			`root.result = this.foo.exists("bar.baz")`,
 			`{"foo":{"bar":{"baz":"yep, I exist"}}}`,