metadata

Documentation

Overview

Package metadata implements a mechanism for setting and retrieving metadata stored in program binaries.

Metadata is a flat mapping of unique string identifiers to their associated string values. Both the ids and the values should be human-readable strings, since many uses of metadata involve textual output for humans; e.g. dumping metadata from the program on the command-line, or prepending metadata to log files.

The ids must be unique, and avoiding collisions is up to the users of this package; it is recommended to prefix your identifiers with your project name.

There are typically two sources for metadata, both supported by this package:

1) External metadata gathered by a build tool, e.g. the build timestamp.

2) Internal metadata compiled into the program, e.g. version numbers.

External metadata is injected into the program binary by the linker. The Go ld linker provides a -X option that may be used for this purpose; see LDFlag for more details.

Internal metadata is already compiled into the program binary, but the metadata package must still be made aware of it. Call the Insert function in an init function to accomplish this:

package mypkg
import "v.io/x/lib/metadata"

func init() {
  metadata.Insert("myproject.myid", "value")
}

The built-in metadata comes pre-populated with the Go architecture, operating system and version.

This package registers a flag -metadata via an init function. Setting -metadata on the command-line causes the program to dump metadata in the XML format and exit.

Index

• func Insert(id, value string) string
• func LDFlag(x *T) string
• func LDFlagExternal(pkgpath, variable string, x *T) string
• func Lookup(id string) string
• func ToBase64() string
• func ToMap() map[string]string
• func ToXML() string
• type T
  • func FromBase64(data []byte) (*T, error)
  • func FromMap(entries map[string]string) *T
  • func FromXML(data []byte) (*T, error)
  • func (x *T) Insert(id, value string) string
  • func (x *T) Lookup(id string) string
  • func (x *T) String() string
  • func (x *T) ToBase64() string
  • func (x *T) ToMap() map[string]string
  • func (x *T) ToXML() string

Functions

func Insert

func Insert(id, value string) string

Insert sets the built-in metadata entry for id to value, and returns the previous value. Whitespace is trimmed from either end of the value.

The built-in metadata is initialized by the Go ld linker. See the LDFlag function for more details.

func LDFlag

func LDFlag(x *T) string

LDFlag returns the flag to pass to the Go ld linker to initialize the built-in metadata with x. Calls LDFlagExternal with the appropriate package path and unexported variable name to initialize BuiltIn.

func LDFlagExternal

func LDFlagExternal(pkgpath, variable string, x *T) string

LDFlagExternal returns the flag to pass to the Go ld linker to initialize the string variable defined in pkgpath to the base64 encoding of x. See the documentation of the -X option at https://golang.org/cmd/ld

The base64 encoding is used to avoid quoting and escaping issues when passing the flag through the go toolchain. An example of using the result to install a Go binary with metadata x:

LDFlagExternal("main", "myvar", x) == "-X main.myvar=eJwBAAD//wAAAAE="

$ go install -ldflags="-X main.myvar=eJwBAAD//wAAAAE=" mypackage

func Lookup

func Lookup(id string) string

Lookup retrieves the value for the given id from the built-in metadata.

func ToBase64

func ToBase64() string

ToBase64 returns the base64 encoding of the built-in metadata. First the metadata is XML encoded, then zlib compressed, and finally base64 encoded.

func ToMap

func ToMap() map[string]string

ToMap returns a copy of the entries in the built-in metadata. Mutating the returned map has no effect on the built-in metadata.

func ToXML

func ToXML() string

ToXML returns the XML encoding of the built-in metadata. The schema is defined in T.ToXML.

Types

type T

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

T represents the metadata for a program binary.

var BuiltIn T

BuiltIn represents the metadata built-in to the Go program. The top-level functions such as Insert, ToBase64, and so on are wrappers for the methods of BuiltIn.

func FromBase64

func FromBase64(data []byte) (*T, error)

FromBase64 returns new metadata initialized with the given base64 encoded data. The data is expected to have started as a valid XML representation of metadata, then zlib compressed, and finally base64 encoded.

func FromMap

func FromMap(entries map[string]string) *T

FromMap returns new metadata initialized with the given entries. Calls Insert on each element of entries.

func FromXML

func FromXML(data []byte) (*T, error)

FromXML returns new metadata initialized with the given XML encoded data. The expected schema is described in ToXML.

func (*T) Insert

func (x *T) Insert(id, value string) string

Insert sets the metadata entry for id to value, and returns the previous value. Whitespace is trimmed from either end of the value.

func (*T) Lookup

func (x *T) Lookup(id string) string

Lookup retrieves the value for the given id from x.

func (*T) String

func (x *T) String() string

String returns a human-readable representation; the same as ToXML.

func (*T) ToBase64

func (x *T) ToBase64() string

ToBase64 returns the base64 encoding of x. First x is XML encoded, then zlib compressed, and finally base64 encoded.

func (*T) ToMap

func (x *T) ToMap() map[string]string

ToMap returns a copy of the entries in x. Mutating the returned map has no effect on x.

func (*T) ToXML

func (x *T) ToXML() string

ToXML returns the XML encoding of x, using the schema described below.

<metadata>
  <md id="A">a value</md>
  <md id="B"><![CDATA[
    foo
    bar
  ]]></md>
  <md id="C">c value</md>
</metadata>