alextab93/buildx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Merge pull request #3289 from crazy-max/bake-stdlib-description

Browse Source 
bake: set missing stdlib functions description
This commit is contained in:
Tõnis Tiigi
2025-07-11 17:27:15 -07:00
committed by GitHub
parent 9a07004534 ddec7679f6
commit 661a1593f6
3 changed files with 61 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bake/hclparser/stdlib.go
+38 -21
View File
@@ -18,35 +18,36 @@ import (
) )
type funcDef struct { type funcDef struct {
name string name string
fn function.Function descriptionAlt string
factory func() function.Function fn function.Function
factory func() function.Function
} }
var stdlibFunctions = []funcDef{ var stdlibFunctions = []funcDef{
{name: "absolute", fn: stdlib.AbsoluteFunc}, {name: "absolute", fn: stdlib.AbsoluteFunc},
{name: "add", fn: stdlib.AddFunc}, {name: "add", fn: stdlib.AddFunc},
{name: "and", fn: stdlib.AndFunc}, {name: "and", fn: stdlib.AndFunc},
{name: "base64decode", fn: encoding.Base64DecodeFunc}, {name: "base64decode", fn: encoding.Base64DecodeFunc, descriptionAlt: `Decodes a string containing a base64 sequence.`},
{name: "base64encode", fn: encoding.Base64EncodeFunc}, {name: "base64encode", fn: encoding.Base64EncodeFunc, descriptionAlt: `Encodes a string to a base64 sequence.`},
{name: "basename", factory: basenameFunc}, {name: "basename", factory: basenameFunc},
{name: "bcrypt", fn: crypto.BcryptFunc}, {name: "bcrypt", fn: crypto.BcryptFunc, descriptionAlt: `Computes a hash of the given string using the Blowfish cipher.`},
{name: "byteslen", fn: stdlib.BytesLenFunc}, {name: "byteslen", fn: stdlib.BytesLenFunc},
{name: "bytesslice", fn: stdlib.BytesSliceFunc}, {name: "bytesslice", fn: stdlib.BytesSliceFunc},
{name: "can", fn: tryfunc.CanFunc}, {name: "can", fn: tryfunc.CanFunc, descriptionAlt: `Tries to evaluate the expression given in its first argument.`},
{name: "ceil", fn: stdlib.CeilFunc}, {name: "ceil", fn: stdlib.CeilFunc},
{name: "chomp", fn: stdlib.ChompFunc}, {name: "chomp", fn: stdlib.ChompFunc},
{name: "chunklist", fn: stdlib.ChunklistFunc}, {name: "chunklist", fn: stdlib.ChunklistFunc},
{name: "cidrhost", fn: cidr.HostFunc}, {name: "cidrhost", fn: cidr.HostFunc, descriptionAlt: `Calculates a full host IP address within a given IP network address prefix.`},
{name: "cidrnetmask", fn: cidr.NetmaskFunc}, {name: "cidrnetmask", fn: cidr.NetmaskFunc, descriptionAlt: `Converts an IPv4 address prefix given in CIDR notation into a subnet mask address.`},
{name: "cidrsubnet", fn: cidr.SubnetFunc}, {name: "cidrsubnet", fn: cidr.SubnetFunc, descriptionAlt: `Calculates a subnet address within a given IP network address prefix.`},
{name: "cidrsubnets", fn: cidr.SubnetsFunc}, {name: "cidrsubnets", fn: cidr.SubnetsFunc, descriptionAlt: `Calculates many consecutive subnet addresses at once, rather than just a single subnet extension.`},
{name: "coalesce", fn: stdlib.CoalesceFunc}, {name: "coalesce", fn: stdlib.CoalesceFunc},
{name: "coalescelist", fn: stdlib.CoalesceListFunc}, {name: "coalescelist", fn: stdlib.CoalesceListFunc},
{name: "compact", fn: stdlib.CompactFunc}, {name: "compact", fn: stdlib.CompactFunc},
{name: "concat", fn: stdlib.ConcatFunc}, {name: "concat", fn: stdlib.ConcatFunc},
{name: "contains", fn: stdlib.ContainsFunc}, {name: "contains", fn: stdlib.ContainsFunc},
{name: "convert", fn: typeexpr.ConvertFunc}, {name: "convert", fn: typeexpr.ConvertFunc, descriptionAlt: `Converts a value to a specified type constraint, using HCL's customdecode extension for type expression support.`},
{name: "csvdecode", fn: stdlib.CSVDecodeFunc}, {name: "csvdecode", fn: stdlib.CSVDecodeFunc},
{name: "dirname", factory: dirnameFunc}, {name: "dirname", factory: dirnameFunc},
{name: "distinct", fn: stdlib.DistinctFunc}, {name: "distinct", fn: stdlib.DistinctFunc},
@@ -76,7 +77,7 @@ var stdlibFunctions = []funcDef{
{name: "lookup", fn: stdlib.LookupFunc}, {name: "lookup", fn: stdlib.LookupFunc},
{name: "lower", fn: stdlib.LowerFunc}, {name: "lower", fn: stdlib.LowerFunc},
{name: "max", fn: stdlib.MaxFunc}, {name: "max", fn: stdlib.MaxFunc},
{name: "md5", fn: crypto.Md5Func}, {name: "md5", fn: crypto.Md5Func, descriptionAlt: `Computes the MD5 hash of a given string and encodes it with hexadecimal digits.`},
{name: "merge", fn: stdlib.MergeFunc}, {name: "merge", fn: stdlib.MergeFunc},
{name: "min", fn: stdlib.MinFunc}, {name: "min", fn: stdlib.MinFunc},
{name: "modulo", fn: stdlib.ModuloFunc}, {name: "modulo", fn: stdlib.ModuloFunc},
@@ -94,7 +95,7 @@ var stdlibFunctions = []funcDef{
{name: "replace", fn: stdlib.ReplaceFunc}, {name: "replace", fn: stdlib.ReplaceFunc},
{name: "reverse", fn: stdlib.ReverseFunc}, {name: "reverse", fn: stdlib.ReverseFunc},
{name: "reverselist", fn: stdlib.ReverseListFunc}, {name: "reverselist", fn: stdlib.ReverseListFunc},
{name: "rsadecrypt", fn: crypto.RsaDecryptFunc}, {name: "rsadecrypt", fn: crypto.RsaDecryptFunc, descriptionAlt: `Decrypts an RSA-encrypted ciphertext.`},
{name: "sanitize", factory: sanitizeFunc}, {name: "sanitize", factory: sanitizeFunc},
{name: "sethaselement", fn: stdlib.SetHasElementFunc}, {name: "sethaselement", fn: stdlib.SetHasElementFunc},
{name: "setintersection", fn: stdlib.SetIntersectionFunc}, {name: "setintersection", fn: stdlib.SetIntersectionFunc},
@@ -102,9 +103,9 @@ var stdlibFunctions = []funcDef{
{name: "setsubtract", fn: stdlib.SetSubtractFunc}, {name: "setsubtract", fn: stdlib.SetSubtractFunc},
{name: "setsymmetricdifference", fn: stdlib.SetSymmetricDifferenceFunc}, {name: "setsymmetricdifference", fn: stdlib.SetSymmetricDifferenceFunc},
{name: "setunion", fn: stdlib.SetUnionFunc}, {name: "setunion", fn: stdlib.SetUnionFunc},
{name: "sha1", fn: crypto.Sha1Func}, {name: "sha1", fn: crypto.Sha1Func, descriptionAlt: `Computes the SHA1 hash of a given string and encodes it with hexadecimal digits.`},
{name: "sha256", fn: crypto.Sha256Func}, {name: "sha256", fn: crypto.Sha256Func, descriptionAlt: `Computes the SHA256 hash of a given string and encodes it with hexadecimal digits.`},
{name: "sha512", fn: crypto.Sha512Func}, {name: "sha512", fn: crypto.Sha512Func, descriptionAlt: `Computes the SHA512 hash of a given string and encodes it with hexadecimal digits.`},
{name: "signum", fn: stdlib.SignumFunc}, {name: "signum", fn: stdlib.SignumFunc},
{name: "slice", fn: stdlib.SliceFunc}, {name: "slice", fn: stdlib.SliceFunc},
{name: "sort", fn: stdlib.SortFunc}, {name: "sort", fn: stdlib.SortFunc},
@@ -119,11 +120,11 @@ var stdlibFunctions = []funcDef{
{name: "trimprefix", fn: stdlib.TrimPrefixFunc}, {name: "trimprefix", fn: stdlib.TrimPrefixFunc},
{name: "trimspace", fn: stdlib.TrimSpaceFunc}, {name: "trimspace", fn: stdlib.TrimSpaceFunc},
{name: "trimsuffix", fn: stdlib.TrimSuffixFunc}, {name: "trimsuffix", fn: stdlib.TrimSuffixFunc},
{name: "try", fn: tryfunc.TryFunc}, {name: "try", fn: tryfunc.TryFunc, descriptionAlt: `Variadic function that tries to evaluate all of is arguments in sequence until one succeeds, in which case it returns that result, or returns an error if none of them succeed.`},
{name: "upper", fn: stdlib.UpperFunc}, {name: "upper", fn: stdlib.UpperFunc},
{name: "urlencode", fn: encoding.URLEncodeFunc}, {name: "urlencode", fn: encoding.URLEncodeFunc, descriptionAlt: `Applies URL encoding to a given string.`},
{name: "uuidv4", fn: uuid.V4Func}, {name: "uuidv4", fn: uuid.V4Func, descriptionAlt: `Generates and returns a Type-4 UUID in the standard hexadecimal string format.`},
{name: "uuidv5", fn: uuid.V5Func}, {name: "uuidv5", fn: uuid.V5Func, descriptionAlt: `Generates and returns a Type-5 UUID in the standard hexadecimal string format.`},
{name: "values", fn: stdlib.ValuesFunc}, {name: "values", fn: stdlib.ValuesFunc},
{name: "zipmap", fn: stdlib.ZipmapFunc}, {name: "zipmap", fn: stdlib.ZipmapFunc},
} }
@@ -264,3 +265,19 @@ func Stdlib() map[string]function.Function {
} }
return funcs return funcs
} }
func StdlibFuncDescription(name string) string {
for _, v := range stdlibFunctions {
if v.name != name {
continue
}
if v.descriptionAlt != "" {
return v.descriptionAlt
}
if v.factory != nil {
return v.factory().Description()
}
return v.fn.Description()
}
return ""
}
docs/bake-stdlib.md
+18 -18
View File
@@ -9,26 +9,26 @@ title: Bake standard library functions
| `absolute` | If the given number is negative then returns its positive equivalent, or otherwise returns the given number unchanged. | | `absolute` | If the given number is negative then returns its positive equivalent, or otherwise returns the given number unchanged. |
| [`add`](#add) | Returns the sum of the two given numbers. | | [`add`](#add) | Returns the sum of the two given numbers. |
| `and` | Applies the logical AND operation to the given boolean values. | | `and` | Applies the logical AND operation to the given boolean values. |
| `base64decode` | | | `base64decode` | Decodes a string containing a base64 sequence. |
| `base64encode` | | | `base64encode` | Encodes a string to a base64 sequence. |
| `basename` | Returns the last element of a path. | | `basename` | Returns the last element of a path. |
| `bcrypt` | | | `bcrypt` | Computes a hash of the given string using the Blowfish cipher. |
| `byteslen` | Returns the total number of bytes in the given buffer. | | `byteslen` | Returns the total number of bytes in the given buffer. |
| `bytesslice` | Extracts a subslice from the given buffer. | | `bytesslice` | Extracts a subslice from the given buffer. |
| `can` | | | `can` | Tries to evaluate the expression given in its first argument. |
| `ceil` | Returns the smallest whole number that is greater than or equal to the given value. | | `ceil` | Returns the smallest whole number that is greater than or equal to the given value. |
| `chomp` | Removes one or more newline characters from the end of the given string. | | `chomp` | Removes one or more newline characters from the end of the given string. |
| `chunklist` | Splits a single list into multiple lists where each has at most the given number of elements. | | `chunklist` | Splits a single list into multiple lists where each has at most the given number of elements. |
| `cidrhost` | | | `cidrhost` | Calculates a full host IP address within a given IP network address prefix. |
| `cidrnetmask` | | | `cidrnetmask` | Converts an IPv4 address prefix given in CIDR notation into a subnet mask address. |
| `cidrsubnet` | | | `cidrsubnet` | Calculates a subnet address within a given IP network address prefix. |
| `cidrsubnets` | | | `cidrsubnets` | Calculates many consecutive subnet addresses at once, rather than just a single subnet extension. |
| `coalesce` | Returns the first of the given arguments that isn't null, or raises an error if there are no non-null arguments. | | `coalesce` | Returns the first of the given arguments that isn't null, or raises an error if there are no non-null arguments. |
| `coalescelist` | Returns the first of the given sequences that has a length greater than zero. | | `coalescelist` | Returns the first of the given sequences that has a length greater than zero. |
| `compact` | Removes all empty string elements from the given list of strings. | | `compact` | Removes all empty string elements from the given list of strings. |
| `concat` | Concatenates together all of the given lists or tuples into a single sequence, preserving the input order. | | `concat` | Concatenates together all of the given lists or tuples into a single sequence, preserving the input order. |
| `contains` | Returns true if the given value is a value in the given list, tuple, or set, or false otherwise. | | `contains` | Returns true if the given value is a value in the given list, tuple, or set, or false otherwise. |
| `convert` | | | `convert` | Converts a value to a specified type constraint, using HCL's customdecode extension for type expression support. |
| `csvdecode` | Parses the given string as Comma Separated Values (as defined by RFC 4180) and returns a map of objects representing the table of data, using the first row as a header row to define the object attributes. | | `csvdecode` | Parses the given string as Comma Separated Values (as defined by RFC 4180) and returns a map of objects representing the table of data, using the first row as a header row to define the object attributes. |
| `dirname` | Returns the directory of a path. | | `dirname` | Returns the directory of a path. |
| `distinct` | Removes any duplicate values from the given list, preserving the order of remaining elements. | | `distinct` | Removes any duplicate values from the given list, preserving the order of remaining elements. |
@@ -58,7 +58,7 @@ title: Bake standard library functions
| `lookup` | Returns the value of the element with the given key from the given map, or returns the default value if there is no such element. | | `lookup` | Returns the value of the element with the given key from the given map, or returns the default value if there is no such element. |
| `lower` | Returns the given string with all Unicode letters translated to their lowercase equivalents. | | `lower` | Returns the given string with all Unicode letters translated to their lowercase equivalents. |
| `max` | Returns the numerically greatest of all of the given numbers. | | `max` | Returns the numerically greatest of all of the given numbers. |
| `md5` | | | `md5` | Computes the MD5 hash of a given string and encodes it with hexadecimal digits. |
| `merge` | Merges all of the elements from the given maps into a single map, or the attributes from given objects into a single object. | | `merge` | Merges all of the elements from the given maps into a single map, or the attributes from given objects into a single object. |
| `min` | Returns the numerically smallest of all of the given numbers. | | `min` | Returns the numerically smallest of all of the given numbers. |
| `modulo` | Divides the first given number by the second and then returns the remainder. | | `modulo` | Divides the first given number by the second and then returns the remainder. |
@@ -76,7 +76,7 @@ title: Bake standard library functions
| `replace` | Replaces all instances of the given substring in the given string with the given replacement string. | | `replace` | Replaces all instances of the given substring in the given string with the given replacement string. |
| `reverse` | Returns the given string with all of its Unicode characters in reverse order. | | `reverse` | Returns the given string with all of its Unicode characters in reverse order. |
| `reverselist` | Returns the given list with its elements in reverse order. | | `reverselist` | Returns the given list with its elements in reverse order. |
| `rsadecrypt` | | | `rsadecrypt` | Decrypts an RSA-encrypted ciphertext. |
| `sanitize` | Replaces all non-alphanumeric characters with a underscore, leaving only characters that are valid for a Bake target name. | | `sanitize` | Replaces all non-alphanumeric characters with a underscore, leaving only characters that are valid for a Bake target name. |
| `sethaselement` | Returns true if the given set contains the given element, or false otherwise. | | `sethaselement` | Returns true if the given set contains the given element, or false otherwise. |
| `setintersection` | Returns the intersection of all given sets. | | `setintersection` | Returns the intersection of all given sets. |
@@ -84,9 +84,9 @@ title: Bake standard library functions
| `setsubtract` | Returns the relative complement of the two given sets. | | `setsubtract` | Returns the relative complement of the two given sets. |
| `setsymmetricdifference` | Returns the symmetric difference of the two given sets. | | `setsymmetricdifference` | Returns the symmetric difference of the two given sets. |
| `setunion` | Returns the union of all given sets. | | `setunion` | Returns the union of all given sets. |
| `sha1` | | | `sha1` | Computes the SHA1 hash of a given string and encodes it with hexadecimal digits. |
| `sha256` | | | `sha256` | Computes the SHA256 hash of a given string and encodes it with hexadecimal digits. |
| `sha512` | | | `sha512` | Computes the SHA512 hash of a given string and encodes it with hexadecimal digits. |
| `signum` | Returns 0 if the given number is zero, 1 if the given number is positive, or -1 if the given number is negative. | | `signum` | Returns 0 if the given number is zero, 1 if the given number is positive, or -1 if the given number is negative. |
| `slice` | Extracts a subslice of the given list or tuple value. | | `slice` | Extracts a subslice of the given list or tuple value. |
| `sort` | Applies a lexicographic sort to the elements of the given list. | | `sort` | Applies a lexicographic sort to the elements of the given list. |
@@ -101,11 +101,11 @@ title: Bake standard library functions
| `trimprefix` | Removes the given prefix from the start of the given string, if present. | | `trimprefix` | Removes the given prefix from the start of the given string, if present. |
| `trimspace` | Removes any consecutive space characters (as defined by Unicode) from the start and end of the given string. | | `trimspace` | Removes any consecutive space characters (as defined by Unicode) from the start and end of the given string. |
| `trimsuffix` | Removes the given suffix from the start of the given string, if present. | | `trimsuffix` | Removes the given suffix from the start of the given string, if present. |
| `try` | | | `try` | Variadic function that tries to evaluate all of is arguments in sequence until one succeeds, in which case it returns that result, or returns an error if none of them succeed. |
| `upper` | Returns the given string with all Unicode letters translated to their uppercase equivalents. | | `upper` | Returns the given string with all Unicode letters translated to their uppercase equivalents. |
| `urlencode` | | | `urlencode` | Applies URL encoding to a given string. |
| `uuidv4` | | | `uuidv4` | Generates and returns a Type-4 UUID in the standard hexadecimal string format. |
| `uuidv5` | | | `uuidv5` | Generates and returns a Type-5 UUID in the standard hexadecimal string format. |
| `values` | Returns the values of elements of a given map, or the values of attributes of a given object, in lexicographic order by key or attribute name. | | `values` | Returns the values of elements of a given map, or the values of attributes of a given object, in lexicographic order by key or attribute name. |
| `zipmap` | Constructs a map from a list of keys and a corresponding list of values, which must both be of the same length. | | `zipmap` | Constructs a map from a list of keys and a corresponding list of values, which must both be of the same length. |
docs/generate.go
+5 -2
View File
@@ -151,12 +151,15 @@ func generateBakeStdlibDocs(filename string) error {
} }
sort.Strings(names) sort.Strings(names)
for _, name := range names { for _, name := range names {
fn := hclparser.Stdlib()[name]
fname := fmt.Sprintf("`%s`", name) fname := fmt.Sprintf("`%s`", name)
if strings.Contains(currentContent, "<a name=\""+name+"\"></a>") { if strings.Contains(currentContent, "<a name=\""+name+"\"></a>") {
fname = fmt.Sprintf("[`%s`](#%s)", name, name) fname = fmt.Sprintf("[`%s`](#%s)", name, name)
} }
table.AddRow(fname, fn.Description()) fdesc := hclparser.StdlibFuncDescription(name)
if fdesc == "" {
return errors.Errorf("function %q has no description", name)
}
table.AddRow(fname, fdesc)
} }
newContent := currentContent[:start] + "<!---MARKER_STDLIB_START-->\n\n" + table.String() + "\n" + currentContent[end:] newContent := currentContent[:start] + "<!---MARKER_STDLIB_START-->\n\n" + table.String() + "\n" + currentContent[end:]