Documentation
¶
Overview ¶
Package kv provides an ordered list of key/value entries in which a key is written at most once, so one set of values can be overlaid on another without disturbing the order the first one established.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Query reads a=b&c=d, opened by the "?" of a URL when one precedes it. Query = NewFormat("=", "&", WithOpener("?")) // Keyword reads a=b c=d, as a libpq connection string does. Keyword = NewFormat("=", " ") // Flags reads --a=b --c=d, as long command line flags do. Flags = NewFormat("=", " ", WithKeyPrefix("--")) // Comma reads a=b,c=d. Comma = NewFormat("=", ",") )
The notations a list is commonly spelled in.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
Entry is one element of a List. Key and Value carry the entry when Keyed is true; Raw carries it otherwise.
type Format ¶
type Format interface {
// Parse splits s into the text preceding its section and the pairs of that
// section, in the order they appear. A key the section repeats is kept once
// and takes its last value. A string that never opens a section is read as
// pairs and nothing else, so "a=b&c=d" parses without a "?" in front of it.
Parse(s string) (string, List[string])
// Render writes entries as a section of prefix, opening it unless prefix is
// empty or already ends with the opener. Unkeyed entries are written as they
// are.
Render(prefix string, entries List[string]) string
// Apply merges params into the pairs already in s. A key s carries keeps its
// position and takes its value from params; the rest are appended in sorted
// order, so the result is deterministic.
Apply(s string, params map[string]string) string
}
Format is the notation of a string that spells a list out as key1=value1&key2=value2: an equal sign joining a key to its value, a separator joining one pair to the next, and an opener that starts the section when it follows text that is not a pair, such as a URL path or a credential.
A key may not hold the equal sign, the separator, the opener, or any of "/@:"; text that reads otherwise is not a pair and stays out of the section. That is what keeps a "?" inside a password from opening a query.
func NewFormat ¶
func NewFormat(equal, sep string, opts ...FormatOption) Format
NewFormat returns the notation whose pairs read as key<equal>value and are joined by sep. Without WithOpener the whole string is pairs, and sep divides them from any text that precedes them.
type FormatOption ¶
type FormatOption func(*format)
func WithKeyPrefix ¶
func WithKeyPrefix(prefix string) FormatOption
WithKeyPrefix sets the text every key carries, such as the "--" of a long command line flag. Text that does not carry it is not a pair.
func WithOpener ¶
func WithOpener(open string) FormatOption
WithOpener sets the text that starts the section of pairs, such as the "?" of a URL query. Without it every token of the string is read as a pair.
type List ¶
type List[V any] interface { // Set records value under key, overwriting the entry in place when the key // is already in the list and appending it otherwise. The empty string is a // key like any other. Set(key string, value V) // AddRaw appends text that carries no key. It never merges with another // entry and never answers a Get. AddRaw(raw string) // Get returns the value recorded under key. Get(key string) (V, bool) // Len returns the number of entries, keyed and unkeyed alike. Len() int // Entries returns the entries in order. The result is newly allocated and // never aliases the List, though a stored pointer still points where it did. Entries() []Entry[V] }
List is an ordered sequence of entries. A keyed entry keeps the position it was first set at and takes the value of the last Set for that key. An unkeyed entry holds text that passes through in the position it was added and is never merged with anything.
A List is not safe for concurrent use.
Source Files