package codetags

import "k8s.io/gengo/v2/codetags"

Index ¶

• func Extract(prefix string, lines []string) map[string][]string
• type Arg
• func (a Arg) String() string
• type ArgType
• type TypedTag
• func Parse(tagText string) (TypedTag, error)
• func ParseAll(tags []string) ([]TypedTag, error)
• func (t TypedTag) String() string

Functions ¶

func Extract ¶

func Extract(prefix string, lines []string) map[string][]string

Extract identifies and collects lines containing special metadata tags. It processes only lines that begin with the prefix.

The portion of a line immediately following the prefix is treated as a potential tag name. To be considered valid, this tag name must match the regular expression `[a-zA-Z_][a-zA-Z0-9_.-:]*`.

Extract returns a map where each key is a valid tag name found in lines that begin with the prefix. The value for each key is a slice of strings. Each string in this slice represents the contents of an original line after the prefix has been removed.

Example: When called with prefix "+k8s:", lines:

Comment line without marker
+k8s:noArgs // comment
+withValue=value1
+withValue=value2
+k8s:withArg(arg1)=value1
+k8s:withArg(arg2)=value2 // comment
+k8s:withNamedArgs(arg1=value1, arg2=value2)=value

Then this function will return:

map[string][]string{
	"noArgs":        {"noArgs // comment"},
	"withArg":       {"withArg(arg1)=value1", "withArg(arg2)=value2 // comment"},
	"withNamedArgs": {"withNamedArgs(arg1=value1, arg2=value2)=value"},
}

Types ¶

type Arg ¶

type Arg struct {
	// Name is the name of a named argument. This is zero-valued for positional arguments.
	Name string
	// Value is the string value of an argument. It has been validated to match the Type.
	// See the ArgType const godoc for further details on how to parse the value for the
	// Type.
	Value string

	// Type identifies the type of the argument.
	Type ArgType
}

Arg represents a argument.

func (Arg) String ¶

func (a Arg) String() string

String returns the string representation of the argument.

type ArgType ¶

type ArgType string

ArgType is an argument's type.

const (
	// ArgTypeString identifies string values.
	ArgTypeString ArgType = "string"

	// ArgTypeInt identifies int values. Values of this type may be in decimal,
	// octal, hex or binary string representations. Consider using strconv.ParseInt
	// to parse, as it supports all these string representations.
	ArgTypeInt ArgType = "int"

	// ArgTypeBool identifies bool values. Values of this type must either be the
	// string "true" or "false".
	ArgTypeBool ArgType = "bool"
)

type TypedTag ¶

type TypedTag struct {
	// Name is the name of the tag with no arguments.
	Name string
	// Args is a list of optional arguments to the tag.
	Args []Arg
	// Value is the value of the tag.
	Value string
}

TypedTag represents a single comment tag with typed args.

func Parse ¶

func Parse(tagText string) (TypedTag, error)

Parse parses a comment tag into a TypedTag, or returns an error if the tag string fails to parse.

A tag consists of a name, optional arguments, and an optional value. For example,

"name"
"name=50"
"name("featureX")=50"
"name(limit: 10, path: "/xyz")=text value"

Arguments are optional and may be either:

• A single positional argument.
• One or more named arguments (in the format `name: value`).
• (Positional and named arguments cannot be mixed.)

For example,

"name()"
"name(arg)"
"name(namedArg1: argValue1)"
"name(namedArg1: argValue1, namedArg2: argValue2)"

Argument values may be strings, ints, booleans, or identifiers.

For example,

"name("double-quoted")"
"name(`backtick-quoted`)"
"name(100)"
"name(true)"
"name(arg1: identifier)"
"name(arg1:`string value`)"
"name(arg1: 100)"
"name(arg1: true)"

Note: When processing Go source code comments, the Extract function is typically used first to find and isolate tag strings matching a specific prefix. Those extracted strings can then be parsed using this function.

The value part of the tag is optional and follows an equals sign "=". If no equals sign and value are present, the `Value` field of the resulting TypedTag will be an empty string.

For example,

"name" // no value
"name=value"
"name=values include all the content after the = sign including any special characters (@*#^&...)"

Comments are treated as part of the value, if a value is present.

For example,

"key // This tag has no value, so this comment is ignored"
"key=value // Comments after values are treated as part of the value"

Formal Grammar:

<tag> ::= <tagName> [ "(" [ <args> ] ")" ] [ "=" <tagValue> ] <args> ::= <argValue> | <namedArgs> <namedArgs> ::= <argNameAndValue> [ "," <namedArgs> ]* <argNameAndValue> ::= <identifier> ":" <argValue> <argValue> ::= <identifier> | <string> | <int> | <bool>

<tagName> ::= [a-zA-Z_][a-zA-Z0-9_-.:]* <identifier> ::= [a-zA-Z_][a-zA-Z0-9_-.]* <string> ::= /* Go-style double-quoted or backtick-quoted strings, ... with standard Go escape sequences for double-quoted strings. */ <int> ::= /* Standard Go integer literals (decimal, 0x hex, 0o octal, 0b binary), ... with an optional +/- prefix. */ <bool> ::= "true" | "false" <tagValue> ::= /* All text following the "=" sign to the end of the string. */

func ParseAll ¶

func ParseAll(tags []string) ([]TypedTag, error)

ParseAll calls Parse on each tag in the input slice.

func (TypedTag) String ¶

func (t TypedTag) String() string

Source Files ¶

extractor.go parser.go types.go