label

package
v0.0.0-...-1b293c9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 3, 2025 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Canonicalize 

func Canonicalize[TCanonical any, TApparent Canonicalizable[TCanonical]](resolver Resolver, fromRepo CanonicalRepo, toApparent TApparent) (TCanonical, error)

Canonicalize an apparent label or target pattern, so that any leading apparent repo or "@@" is replaced with its canonical counterpart. This function is identical to Resolve(), except that it fails if the apparent repo contained in the label or target pattern is unknown.

Types

type ApparentLabel 

type ApparentLabel struct {
	// contains filtered or unexported fields
}

ApparentLabel is a label string that is prefixed with either a canonical or apparent repo name. This type can be used to refer to a single target within the context of a given repository.

func NewApparentLabel 

func NewApparentLabel(value string) (ApparentLabel, error)

NewApparentLabel validates that the provided string is a valid apparent label. If so, an instance of ApparentLabel is returned that wraps the value.

func (ApparentLabel) AsCanonical 

func (l ApparentLabel) AsCanonical() (CanonicalLabel, bool)

AsCanonical upgrades an existing ApparentLabel to a CanonicalLabel if it prefixed with a canonical repo name.

func (ApparentLabel) AsResolvedWithError 

func (l ApparentLabel) AsResolvedWithError(message string) ResolvedLabel

AsResolvedWithError converts an apparent label to a canonical label containing an error message. This method can be called after attempting to resolve an apparent repo to a canonical repo fails.

func (ApparentLabel) GetApparentRepo 

func (l ApparentLabel) GetApparentRepo() (ApparentRepo, bool)

GetApparentRepo returns the apparent repo name of the label, if the label is not prefixed with a canonical repo name.

func (ApparentLabel) String 

func (l ApparentLabel) String() string

func (ApparentLabel) WithCanonicalRepo 

func (l ApparentLabel) WithCanonicalRepo(canonicalRepo CanonicalRepo) CanonicalLabel

WithCanonicalRepo replaces the repo name of the label with a provided canonical repo name.

type ApparentRepo 

type ApparentRepo struct {
	// contains filtered or unexported fields
}

ApparentRepo can store the name of an apparent repo, such as "bazel_tools" or "rules_go".

func NewApparentRepo 

func NewApparentRepo(value string) (ApparentRepo, error)

NewApparentRepo validates that the provided string is an apparent repo name. Upon success, an instance of ApparentRepo is returned that wraps the value.

func (ApparentRepo) String 

func (r ApparentRepo) String() string

type ApparentTargetPattern 

type ApparentTargetPattern struct {
	// contains filtered or unexported fields
}

ApparentTargetPattern is a target pattern string that is prefixed with either a canonical or apparent repo name (e.g., @@rules_go+//:all or @my_repo//tools/...). This type can be used to refer to zero or more targets within the context of a given repository.

func NewApparentTargetPattern 

func NewApparentTargetPattern(value string) (ApparentTargetPattern, error)

NewApparentTargetPattern validates that the provided string value is a valid apparent target pattern. If so, an instance of ApparentTargetPattern is returned that wraps the value.

func (ApparentTargetPattern) AsCanonical 

func (tp ApparentTargetPattern) AsCanonical() (CanonicalTargetPattern, bool)

AsCanonical upgrades an existing ApparentTargetPattern to a CanonicalTargetPattern if it prefixed with a canonical repo name.

func (ApparentTargetPattern) GetApparentRepo 

func (tp ApparentTargetPattern) GetApparentRepo() (ApparentRepo, bool)

GetApparentRepo returns the apparent repo name of the target pattern, if the target pattern is not prefixed with a canonical repo name.

func (ApparentTargetPattern) String 

func (tp ApparentTargetPattern) String() string

func (ApparentTargetPattern) WithCanonicalRepo 

func (tp ApparentTargetPattern) WithCanonicalRepo(canonicalRepo CanonicalRepo) CanonicalTargetPattern

WithCanonicalRepo replaces the repo name of the target pattern with a provided canonical repo name.

type CanonicalLabel 

type CanonicalLabel struct {
	// contains filtered or unexported fields
}

CanonicalLabel is a label string that is prefixed with a canonical repo name. This type can be used to refer to a single target in an unambiguous way.

func NewCanonicalLabel 

func NewCanonicalLabel(value string) (CanonicalLabel, error)

NewCanonicalLabel creates a new CanonicalLabel based on the provided label value.

func (CanonicalLabel) AppendStarlarkIdentifier 

func (l CanonicalLabel) AppendStarlarkIdentifier(identifier StarlarkIdentifier) CanonicalStarlarkIdentifier

AppendStarlarkIdentifier appends a Starlark identifier to a label, resulting in the canonical name of a Starlark identifier.

func (CanonicalLabel) AsResolved 

func (l CanonicalLabel) AsResolved() ResolvedLabel

AsResolved converts a canonical label to a resolved label. As canonical labels can always be resolved successfully, this function leaves the value as is.

func (CanonicalLabel) GetCanonicalPackage 

func (l CanonicalLabel) GetCanonicalPackage() CanonicalPackage

GetCanonicalPackage strips the target name from a label, thereby returning the canonical package name.

func (CanonicalLabel) GetCanonicalRepo 

func (l CanonicalLabel) GetCanonicalRepo() CanonicalRepo

GetCanonicalRepo returns the name of the canonical repo that is embedded in the label.

func (CanonicalLabel) GetExternalRelativePath 

func (l CanonicalLabel) GetExternalRelativePath() string

GetExternalRelativePath converts a label to a pathname string that is relative to the "external/" directory containing all repos. This can be used in contexts where labels refer to paths of input files.

func (CanonicalLabel) GetRepoRelativePath 

func (l CanonicalLabel) GetRepoRelativePath() string

GetRepoRelativePath converts a label to a pathname string that is relative to the root of the repo. This can be used in contexts where labels refer to paths of input files.

func (CanonicalLabel) GetTargetName 

func (l CanonicalLabel) GetTargetName() TargetName

GetTargetName returns the name of the target within a package.

func (CanonicalLabel) String 

func (l CanonicalLabel) String() string

type CanonicalPackage 

type CanonicalPackage struct {
	// contains filtered or unexported fields
}

CanonicalPackage is a label string that refers to a package, meaning it does not include a target name. Furthermore, it is prefixed with a canonical repo name.

func NewCanonicalPackage 

func NewCanonicalPackage(value string) (CanonicalPackage, error)

NewCanonicalPackage validates that the provided string value is a canonical package name. If so, an instance of CanonicalPackage is returned that wraps the value.

func (CanonicalPackage) AppendLabel 

func (p CanonicalPackage) AppendLabel(value string) (ApparentLabel, error)

AppendLabel appends a provided label value to a canonical package name. The resulting label is apparent, because the provided label value may be prefixed with an apparent repo. It is the caller's responsibility to resolve the apparent repo to a canonical one.

func (CanonicalPackage) AppendTargetName 

func (p CanonicalPackage) AppendTargetName(targetName TargetName) CanonicalLabel

AppendTargetName appends a target name to a canonical package name, thereby turning it into a canonical label.

func (CanonicalPackage) AppendTargetPattern 

func (p CanonicalPackage) AppendTargetPattern(value string) (ApparentTargetPattern, error)

AppendTargetPattern appends a provided target pattern value to a canonical package name. The resulting target pattern is apparent, because the provided label value may be prefixed with an apparent repo. It is the caller's responsibility to resolve the apparent repo to a canonical one.

func (CanonicalPackage) GetCanonicalRepo 

func (p CanonicalPackage) GetCanonicalRepo() CanonicalRepo

GetCanonicalRepo returns the name of the canonical repo that contains this package.

func (CanonicalPackage) GetPackagePath 

func (p CanonicalPackage) GetPackagePath() string

GetPackagePath returns the path of the package, relative to the root of this repo. For the root package the empty string is returned.

func (CanonicalPackage) String 

func (p CanonicalPackage) String() string

func (CanonicalPackage) ToRecursiveTargetPatternBelow 

func (p CanonicalPackage) ToRecursiveTargetPatternBelow(pathBelow string, includeFileTargets bool) (CanonicalTargetPattern, error)

ToRecursiveTargetPatternBelow appends a relative package path to a canonical package name, and subsequently converts it to a recursive target pattern.

This method can be used during expansion of recursive target patterns to split up work, so that subpackages can be traversed in parallel.

type CanonicalRepo 

type CanonicalRepo struct {
	// contains filtered or unexported fields
}

CanonicalRepo corresponds to the canonical name of a repo, without the leading "@@". Canonical repo names can refer to a module instance (e.g., "rules_go+") or a repo declared by a module extension or repo rule (e.g., "gazelle++go_deps+org_golang_x_lint").

func NewCanonicalRepo 

func NewCanonicalRepo(value string) (CanonicalRepo, error)

NewCanonicalRepo validates that the provided string is a canonical repo name. If so, an instance of CanonicalRepo is returned that wraps its value.

func (CanonicalRepo) GetModuleExtension 

func (r CanonicalRepo) GetModuleExtension() (ModuleExtension, ApparentRepo, bool)

GetModuleExtension returns true if the canonical repo belongs to a repo that was declared by a module extension. If so, the name of the module extension and apparent repo are returned separately.

func (CanonicalRepo) GetModuleInstance 

func (r CanonicalRepo) GetModuleInstance() ModuleInstance

GetModuleInstance strips the name of a module extension and apparent repo, if any, from the canonical repo name.

func (CanonicalRepo) GetRootPackage 

func (r CanonicalRepo) GetRootPackage() CanonicalPackage

GetRootPackage returns the canonical package corresponding to top-level package in this repo. This can be used to construct labels for files that are typically placed in the root directory of a repo (e.g., MODULE.bazel, REPO.bazel).

func (CanonicalRepo) String 

func (r CanonicalRepo) String() string

type CanonicalStarlarkIdentifier 

type CanonicalStarlarkIdentifier struct {
	// contains filtered or unexported fields
}

CanonicalStarlarkIdentifier is the fully canonical name of a Starlark identifier, having the form @@repo+//package:my_code.bzl%identifier. It can be used to refer to functions, rules, providers, and other named constructs.

func NewCanonicalStarlarkIdentifier 

func NewCanonicalStarlarkIdentifier(value string) (CanonicalStarlarkIdentifier, error)

NewCanonicalStarlarkIdentifier validates that the provided string is a valid canonical Starlark identifier. If so, an instance of CanonicalStarlarkIdentifier is returned that wraps its value.

func (CanonicalStarlarkIdentifier) GetCanonicalLabel 

func (i CanonicalStarlarkIdentifier) GetCanonicalLabel() CanonicalLabel

GetCanonicalLabel returns the label of the file containing the Starlark identifier.

func (CanonicalStarlarkIdentifier) GetStarlarkIdentifier 

func (i CanonicalStarlarkIdentifier) GetStarlarkIdentifier() StarlarkIdentifier

GetStarlarkIdentifier returns the file local Starlark identifier (i.e., the part after the '%').

func (CanonicalStarlarkIdentifier) String 

func (i CanonicalStarlarkIdentifier) String() string

func (CanonicalStarlarkIdentifier) ToModuleExtension 

func (i CanonicalStarlarkIdentifier) ToModuleExtension() ModuleExtension

ToModuleExtension converts a Starlark identifier of a module extension declared in a .bzl file and converts it to a string that can be prefixed to repos that are declared by the module extension.

type CanonicalTargetPattern 

type CanonicalTargetPattern struct {
	// contains filtered or unexported fields
}

CanonicalTargetPattern is a target pattern string that is prefixed with a canonical repo name. This type can be used to refer to zero or more targets in an unambiguous way.

func NewCanonicalTargetPattern 

func NewCanonicalTargetPattern(value string) (CanonicalTargetPattern, error)

NewCanonicalTargetPattern creates a new CanonicalTargetPattern based on the provided target pattern value.

func (CanonicalTargetPattern) AsCanonicalLabel 

func (tp CanonicalTargetPattern) AsCanonicalLabel() (CanonicalLabel, bool)

AsCanonicalLabel converts a canonical target pattern to a canonical label. Conversion only succeeds if the pattern is guaranteed to refer to a single target.

func (CanonicalTargetPattern) AsRecursiveTargetPattern 

func (tp CanonicalTargetPattern) AsRecursiveTargetPattern() (basePackage CanonicalPackage, includeFileTargets, success bool)

AsRecursiveTargetPattern returns success if the target pattern matches packages recursively (i.e., it ends with "/..." or "/..:*").

Upon success, the package name is returned at which recursive expansion should start.

func (CanonicalTargetPattern) AsSinglePackageTargetPattern 

func (tp CanonicalTargetPattern) AsSinglePackageTargetPattern() (initialTarget CanonicalLabel, includeFileTargets, success bool)

AsSinglePackageTargetPattern returns success if the target pattern refers to a single package and contains a wildcard target name (":all", ":all-targets", or ":*").

Upon success, a label is returned that corresponds to the target pattern. The caller is expected to first check whether a target exists for that name. Only if it does not exist, wildcard expansion should be performed.

func (CanonicalTargetPattern) String 

func (tp CanonicalTargetPattern) String() string

type Canonicalizable 

type Canonicalizable[T any] interface {
	AsCanonical() (T, bool)
	GetApparentRepo() (ApparentRepo, bool)
	WithCanonicalRepo(canonicalRepo CanonicalRepo) T
}

Canonicalizable may be implemented by any apparent type (e.g., apparent label, apparent target pattern) that has a canonical counterpart. It is used by Canonicalize() to convert an apparent label or target pattern to a canonical instance.

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module is the name of a Bazel module, as declared by calling module() in MODULE.bazel.

func NewModule 

func NewModule(value string) (Module, error)

NewModule validates that the provided string is a valid Bazel module name. If an instance of Module is returned that wraps the provided value.

func (Module) String 

func (m Module) String() string

func (Module) ToApparentRepo 

func (m Module) ToApparentRepo() ApparentRepo

ToApparentRepo returns the apparent repo name that should be used if the bazel_dep() for this module does not have an explicit repo name set. As all module names are also valid apparent repo names, the module name is used as is.

func (Module) ToModuleInstance 

func (m Module) ToModuleInstance(mv *ModuleVersion) ModuleInstance

ToModuleInstance appends a module version to a module name, thereby returning a module instance. This can be used to construct unique repo names if multiple_version_override() is used.

As multiple_version_override() is only rarely used, this function is called without a version number most of the times, causing the version number in the module instance to remain empty.

type ModuleExtension 

type ModuleExtension struct {
	// contains filtered or unexported fields
}

ModuleExtension is a Starlark identifier that corresponds to the name of the module extension object declared in a .bzl file, prefixed with the name of the module instance containing the module extension. Its value is used as a prefix for the names of repos declared by the module extension.

func NewModuleExtension 

func NewModuleExtension(value string) (ModuleExtension, error)

NewModuleExtension validates that the provided string is a valid module extension name. If so, a ModuleExtension is returned that wraps the provided value.

func (ModuleExtension) GetCanonicalRepoWithModuleExtension 

func (me ModuleExtension) GetCanonicalRepoWithModuleExtension(repo ApparentRepo) CanonicalRepo

GetCanonicalRepoWithModuleExtension returns the canonical repo name of a repo that was created as part of this module extension.

func (ModuleExtension) GetExtensionName 

func (me ModuleExtension) GetExtensionName() StarlarkIdentifier

GetModuleInstance returns the trailing extension name that was used to construct the name of this module extension.

func (ModuleExtension) GetModuleInstance 

func (me ModuleExtension) GetModuleInstance() ModuleInstance

GetModuleInstance returns the leading module instance name that was used to construct the name of this module extension.

func (ModuleExtension) String 

func (me ModuleExtension) String() string

type ModuleInstance 

type ModuleInstance struct {
	// contains filtered or unexported fields
}

ModuleInstance is a pair of a module name and an optional module version. It is the leading part of a canonical repo name.

func NewModuleInstance 

func NewModuleInstance(value string) (ModuleInstance, error)

NewModuleInstance validates that the provided string value corresponds to a valid Bazel module instance (i.e., module name and optional module version). Upon success, a ModuleInstance is returned that wraps the provided value.

func (ModuleInstance) GetBareCanonicalRepo 

func (mi ModuleInstance) GetBareCanonicalRepo() CanonicalRepo

GetBareCanonicalRepo converts a module instance to a canonical repo name. This can be used to refer to the repo corresponding to the module instance itself (not one of its repos declared using module extensions or repo rules).

func (ModuleInstance) GetModule 

func (mi ModuleInstance) GetModule() Module

GetModule returns the leading module name that is part of the module instance.

func (ModuleInstance) GetModuleExtension 

func (mi ModuleInstance) GetModuleExtension(extensionName StarlarkIdentifier) ModuleExtension

GetModuleExtension appends a Starlark identifier to the name of a module instance. This can be used to uniquely identify a module extension.

func (ModuleInstance) GetModuleVersion 

func (mi ModuleInstance) GetModuleVersion() (ModuleVersion, bool)

GetModuleVersion returns the trailing module version number that is part of the module instance. As module version numbers are optional, this function also returns a boolean value to indicate presence of the version number.

func (ModuleInstance) String 

func (mi ModuleInstance) String() string

type ModuleVersion 

type ModuleVersion struct {
	// contains filtered or unexported fields
}

ModuleVersion are version number strings that correspond to the format that Bazel uses to version modules. The format is similar, but not identical to Semantic Versions.

More details: https://bazel.build/external/module#version_format

func NewModuleVersion 

func NewModuleVersion(value string) (ModuleVersion, error)

NewModuleVersion validates that a string contains a valid a Bazel module version (e.g., "1.7.1" or "0.0.0-20241220-5e258e33". If so, it wraps the value in a ModuleVersion.

func (ModuleVersion) Compare 

func (mv ModuleVersion) Compare(other ModuleVersion) int

Compare two Bazel module version numbers along a total order.

func (ModuleVersion) String 

func (mv ModuleVersion) String() string

type ResolvedLabel 

type ResolvedLabel struct {
	// contains filtered or unexported fields
}

ResolvedLabel corresponds to a label for which resolution to a canonical label has been attempted. The label is either a canonical label, or it is a label for which resolution to a canonical label failed. In that case the repo name consists of an error message enclosed in square brackets (i.e. @@[error message]//package:target).

func NewResolvedLabel 

func NewResolvedLabel(value string) (ResolvedLabel, error)

NewResolvedLabel creates a new label for which resolution to a canonical label has been attempted.

func Resolve 

func Resolve(resolver Resolver, fromRepo CanonicalRepo, toApparent ApparentLabel) (ResolvedLabel, error)

Resolve an apparent label, so that any leading apparent repo or "@@" is replaced with its canonical counterpart. If the apparent repo does not exist, the resolved label contains an error message.

func (ResolvedLabel) AppendTargetName 

func (l ResolvedLabel) AppendTargetName(targetName TargetName) ResolvedLabel

AppendTargetName appends a target name to the package of the resolved label.

TODO: Instead of having this method, should we add a ResolvedPackage for consistency with CanonicalPackage?

func (ResolvedLabel) AsCanonical 

func (l ResolvedLabel) AsCanonical() (CanonicalLabel, error)

AsCanonical returns the canonical label corresponding to the current label value if the label does not contain an error message.

func (ResolvedLabel) GetPackagePath 

func (l ResolvedLabel) GetPackagePath() string

GetPackagePath returns the package path of the resolved label.

func (ResolvedLabel) GetTargetName 

func (l ResolvedLabel) GetTargetName() TargetName

GetTargetName returns the target name of the resolved label.

func (ResolvedLabel) String 

func (l ResolvedLabel) String() string

type Resolver 

type Resolver interface {
	GetCanonicalRepo(fromCanonicalRepo CanonicalRepo, toApparentRepo ApparentRepo) (*CanonicalRepo, error)
	GetRootModule() (Module, error)
}

Resolver is called into by Resolve() and Canonicalize() to determine the canonical repo name that should be prepended to an apparent label or target pattern in order to make it canonical.

type StarlarkIdentifier 

type StarlarkIdentifier struct {
	// contains filtered or unexported fields
}

StarlarkIdentifier corresponds to an identifier of a Starlark function, variable or constant.

func NewStarlarkIdentifier 

func NewStarlarkIdentifier(value string) (StarlarkIdentifier, error)

NewStarlarkIdentifier validates that a string containing a Starlark identifier is valid. If so, an instance of StarlarkIdentifier that wraps the value is returned.

func (StarlarkIdentifier) IsPublic 

func (i StarlarkIdentifier) IsPublic() bool

IsPublic returns true if the Starlark identifier refers to a function, variable or constant that is public (i.e., not beginning with an underscore).

func (StarlarkIdentifier) String 

func (i StarlarkIdentifier) String() string

type TargetName 

type TargetName struct {
	// contains filtered or unexported fields
}

TargetName corresponds to the name of an addressable and/or buildable target within a package (e.g., "go_default_library").

func NewTargetName 

func NewTargetName(value string) (TargetName, error)

NewTargetName validates that a string containing a target name is valid. If so, an instance of TargetName that wraps the value is returned.

func (TargetName) GetSibling 

func (tn TargetName) GetSibling(child TargetName) TargetName

GetSibling appends a provided target name to the directory portion of the current target name.

func (TargetName) String 

func (tn TargetName) String() string

func (TargetName) ToComponents 

func (tn TargetName) ToComponents() []path.Component

ToComponents returns the pathname components of the target name.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.