paramutil

type Arg struct {
	Inline bool
	Values []string
}

type Args interface {
	// Parse reads tokens as a command line.
	Parse(tokens []string) Entries[Arg]
	// ParseInto reads tokens into an Entries that may already hold params, so
	// lines read one after another merge left to right. A flag left open at the
	// end of one call does not take the tokens of the next. The entries must
	// not be nil.
	ParseInto(entries Entries[Arg], tokens []string)
	// Render writes entries back as a command line, a flag and the values it
	// did not take inline standing as tokens of their own.
	Render(entries Entries[Arg]) []string
}

type Entries[V any] interface {
	// Set records value under key, overwriting the param in place when the key
	// is already there 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
	// param 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 params, keyed and unkeyed alike.
	Len() int
	// List returns the params in order. The result is newly allocated and never
	// aliases the Entries, though a stored pointer or slice still points where
	// it did.
	List() []Param[V]
}

type Param[V any] struct {
	Key   string
	Value V
	Raw   string
	Keyed bool
}

type Params interface {
	// Parse splits s into the text preceding its section and the params of
	// that section, in the order they appear. Whatever joined the two - the
	// opener, or the separator where the section merely follows text - stays on
	// the prefix, so Render rejoins them with what actually stood there. A key
	// the section repeats is kept once and takes its last value. A string that
	// never opens a section is read as one, so "a=b&c=d" parses without a "?"
	// in front of it.
	Parse(s string) (string, Entries[string])
	// ParseTokens reads each token as a pair, in the order they appear, for a
	// caller whose separator is the boundary between tokens rather than text of
	// its own. A token that is not a pair is kept as a raw entry whether or not
	// the notation AllowRaw, there being no text in front of a section here for
	// it to belong to instead. A separator inside a token is text - in the name
	// and the value alike - no quotes needed, nothing having been split on it.
	ParseTokens(tokens []string) Entries[string]
	// ParseTokensInto reads tokens into an Entries that may already hold params,
	// as ParseTokens does otherwise. A key it already holds keeps its
	// position and takes the new value, so sets read one after another merge
	// left to right. The entries must not be nil.
	ParseTokensInto(entries Entries[string], tokens []string)
	// Render writes entries as a section of prefix, opening it unless prefix is
	// empty or already ends with the opener or the separator. Raw entries and
	// keys are written as they are, valid in the notation or not.
	Render(prefix string, entries Entries[string]) string
	// RenderTokens writes entries as one token each, raw entries as they are.
	// A value needs no quotes here for being empty or holding the separator,
	// the token boundary having done that work; only a value a reader would
	// unquote is quoted, so that it reads back as itself.
	RenderTokens(entries Entries[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. A param named without a prefix
	// takes the notation's first one, so params stay free of the notation they
	// are applied to.
	Apply(s string, params map[string]string) string
}

type ParamsOption func(*params)