AI docs

util/sprig/dict.go

@@ -1,5 +1,15 @@
 package sprig
 
+// get retrieves a value from a map by its key.
+// If the key exists, returns the corresponding value.
+// If the key doesn't exist, returns an empty string.
+//
+// Parameters:
+//   - d: The map to retrieve the value from
+//   - key: The key to look up
+//
+// Returns:
+//   - any: The value associated with the key, or an empty string if not found
 func get(d map[string]any, key string) any {
 	if val, ok := d[key]; ok {
 		return val
@@ -7,21 +17,58 @@ func get(d map[string]any, key string) any {
 	return ""
 }
 
+// set adds or updates a key-value pair in a map.
+// Modifies the map in place and returns the modified map.
+//
+// Parameters:
+//   - d: The map to modify
+//   - key: The key to set
+//   - value: The value to associate with the key
+//
+// Returns:
+//   - map[string]any: The modified map (same instance as the input map)
 func set(d map[string]any, key string, value any) map[string]any {
 	d[key] = value
 	return d
 }
 
+// unset removes a key-value pair from a map.
+// If the key doesn't exist, the map remains unchanged.
+// Modifies the map in place and returns the modified map.
+//
+// Parameters:
+//   - d: The map to modify
+//   - key: The key to remove
+//
+// Returns:
+//   - map[string]any: The modified map (same instance as the input map)
 func unset(d map[string]any, key string) map[string]any {
 	delete(d, key)
 	return d
 }
 
+// hasKey checks if a key exists in a map.
+//
+// Parameters:
+//   - d: The map to check
+//   - key: The key to look for
+//
+// Returns:
+//   - bool: True if the key exists in the map, false otherwise
 func hasKey(d map[string]any, key string) bool {
 	_, ok := d[key]
 	return ok
 }
 
+// pluck extracts values for a specific key from multiple maps.
+// Only includes values from maps where the key exists.
+//
+// Parameters:
+//   - key: The key to extract values for
+//   - d: A variadic list of maps to extract values from
+//
+// Returns:
+//   - []any: A slice containing all values associated with the key across all maps
 func pluck(key string, d ...map[string]any) []any {
 	var res []any
 	for _, dict := range d {
@@ -32,6 +79,14 @@ func pluck(key string, d ...map[string]any) []any {
 	return res
 }
 
+// keys collects all keys from one or more maps.
+// The returned slice may contain duplicate keys if multiple maps contain the same key.
+//
+// Parameters:
+//   - dicts: A variadic list of maps to collect keys from
+//
+// Returns:
+//   - []string: A slice containing all keys from all provided maps
 func keys(dicts ...map[string]any) []string {
 	var k []string
 	for _, dict := range dicts {
@@ -42,6 +97,15 @@ func keys(dicts ...map[string]any) []string {
 	return k
 }
 
+// pick creates a new map containing only the specified keys from the original map.
+// If a key doesn't exist in the original map, it won't be included in the result.
+//
+// Parameters:
+//   - dict: The source map
+//   - keys: A variadic list of keys to include in the result
+//
+// Returns:
+//   - map[string]any: A new map containing only the specified keys and their values
 func pick(dict map[string]any, keys ...string) map[string]any {
 	res := map[string]any{}
 	for _, k := range keys {
@@ -52,6 +116,15 @@ func pick(dict map[string]any, keys ...string) map[string]any {
 	return res
 }
 
+// omit creates a new map excluding the specified keys from the original map.
+// The original map remains unchanged.
+//
+// Parameters:
+//   - dict: The source map
+//   - keys: A variadic list of keys to exclude from the result
+//
+// Returns:
+//   - map[string]any: A new map containing all key-value pairs except those specified
 func omit(dict map[string]any, keys ...string) map[string]any {
 	res := map[string]any{}
 	omit := make(map[string]bool, len(keys))
@@ -66,6 +139,16 @@ func omit(dict map[string]any, keys ...string) map[string]any {
 	return res
 }
 
+// dict creates a new map from a list of key-value pairs.
+// The arguments are treated as key-value pairs, where even-indexed arguments are keys
+// and odd-indexed arguments are values.
+// If there's an odd number of arguments, the last key will be assigned an empty string value.
+//
+// Parameters:
+//   - v: A variadic list of alternating keys and values
+//
+// Returns:
+//   - map[string]any: A new map containing the specified key-value pairs
 func dict(v ...any) map[string]any {
 	dict := map[string]any{}
 	lenv := len(v)
@@ -80,6 +163,14 @@ func dict(v ...any) map[string]any {
 	return dict
 }
 
+// values collects all values from a map into a slice.
+// The order of values in the resulting slice is not guaranteed.
+//
+// Parameters:
+//   - dict: The map to collect values from
+//
+// Returns:
+//   - []any: A slice containing all values from the map
 func values(dict map[string]any) []any {
 	var values []any
 	for _, value := range dict {
@@ -88,6 +179,22 @@ func values(dict map[string]any) []any {
 	return values
 }
 
+// dig safely accesses nested values in maps using a sequence of keys.
+// If any key in the path doesn't exist, it returns the default value.
+// The function expects at least 3 arguments: one or more keys, a default value, and a map.
+//
+// Parameters:
+//   - ps: A variadic list where:
+//     - The first N-2 arguments are string keys forming the path
+//     - The second-to-last argument is the default value to return if the path doesn't exist
+//     - The last argument is the map to traverse
+//
+// Returns:
+//   - any: The value found at the specified path, or the default value if not found
+//   - error: Any error that occurred during traversal
+//
+// Panics:
+//   - If fewer than 3 arguments are provided
 func dig(ps ...any) (any, error) {
 	if len(ps) < 3 {
 		panic("dig needs at least three arguments")
@@ -102,6 +209,17 @@ func dig(ps ...any) (any, error) {
 	return digFromDict(dict, def, ks)
 }
 
+// digFromDict is a helper function for dig that recursively traverses a map using a sequence of keys.
+// If any key in the path doesn't exist, it returns the default value.
+//
+// Parameters:
+//   - dict: The map to traverse
+//   - d: The default value to return if the path doesn't exist
+//   - ks: A slice of string keys forming the path to traverse
+//
+// Returns:
+//   - any: The value found at the specified path, or the default value if not found
+//   - error: Any error that occurred during traversal
 func digFromDict(dict map[string]any, d any, ks []string) (any, error) {
 	k, ns := ks[0], ks[1:]
 	step, has := dict[k]