package codetags

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

Index ¶

• Constants
• func Extract(prefix string, lines []string) map[string][]string
• type Arg
• func (a Arg) String() string
• type ArgType
• type ParseOption
• func RawValues(enabled bool) ParseOption
• type Tag
• func Parse(tag string, options ...ParseOption) (Tag, error)
• func ParseAll(tags []string, options ...ParseOption) ([]Tag, error)
• func (t Tag) NamedArg(name string) (Arg, bool)
• func (t Tag) PositionalArg() (Arg, bool)
• func (t Tag) String() string
• type ValueType

Constants ¶

const (
	EOF = -1
)

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

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 ParseOption ¶

type ParseOption func(*parseOpts)

ParseOption provides a parser option.

func RawValues ¶

func RawValues(enabled bool) ParseOption

RawValues skips parsing of the value part of the tag. If enabled, the Value in the parse response will contain all text following the "=" sign, up to the last non-whitespace character, and ValueType will be set to ValueTypeRaw. Default: disabled

type Tag ¶

type Tag 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 string representation of the tag value.
	// Provides the tag value when ValueType is ValueTypeString, ValueTypeBool, ValueTypeInt or ValueTypeRaw.
	Value string

	// ValueTag is another tag parsed from the value of this tag.
	// Provides the tag value when ValueType is ValueTypeTag.
	ValueTag *Tag

	// ValueType is the type of the value.
	ValueType ValueType
}

Tag represents a single comment tag with typed args.

func Parse ¶

func Parse(tag string, options ...ParseOption) (Tag, error)

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

ParseOption may be provided to modify the behavior of the parser. The below describes the default behavior.

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

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

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 a value is present, it must be a string, int, boolean, identifier, or tag.

For example,

"name" # no value
"name=identifier"
"name="double-quoted value""
"name=`backtick-quoted value`"
"name(100)"
"name(true)"
"name=+anotherTag"
"name=+anotherTag(size: 100)"

Trailing comments are ignored unless the RawValues option is enabled, in which case they are treated as part of the value.

For example,

"key=value # This comment is ignored"

Formal Grammar:

<tag> ::= <tagName> [ "(" [ <args> ] ")" ] [ ( "=" <value> | "=+" <tag> ) ] <args> ::= <value> | <namedArgs> <namedArgs> ::= <argNameAndValue> [ "," <namedArgs> ]* <argNameAndValue> ::= <identifier> ":" <value> <value> ::= <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"

func ParseAll ¶

func ParseAll(tags []string, options ...ParseOption) ([]Tag, error)

ParseAll calls Parse on each tag in the input slice.

func (Tag) NamedArg ¶

func (t Tag) NamedArg(name string) (Arg, bool)

NamedArg returns the named argument. If o named argument is found, it returns false. Always returns false for empty name; use PositionalArg instead.

func (Tag) PositionalArg ¶

func (t Tag) PositionalArg() (Arg, bool)

PositionalArg returns the positional argument. If there is no positional argument, it returns false.

func (Tag) String ¶

func (t Tag) String() string

String returns the canonical string representation of the tag. All strings are represented in double quotes. Spacing is normalized.

type ValueType ¶

type ValueType string

ValueType is a tag's value type.

const (
	// ValueTypeNone indicates that the tag has no value.
	ValueTypeNone ValueType = ""

	// ValueTypeString identifies string values.
	ValueTypeString ValueType = "string"

	// ValueTypeInt 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.
	ValueTypeInt ValueType = "int"

	// ValueTypeBool identifies bool values. Values of this type must either be the
	// string "true" or "false".
	ValueTypeBool ValueType = "bool"

	// ValueTypeTag identifies that the value is another tag.
	ValueTypeTag ValueType = "tag"

	// ValueTypeRaw identifies that the value is raw, untyped content and contains
	// all text from the tag declaration following the "=" sign, up to the last
	// non-whitespace character.
	ValueTypeRaw ValueType = "raw"
)

Source Files ¶

extractor.go parser.go scanner.go types.go