Documentation
¶
Overview ¶
Package barky provides utilities for handling hierarchical key/value data structures that commonly appear in configuration formats such as JSON, YAML, or TOML. It is designed to transform nested data into a flat representation, while preserving enough metadata to reconstruct paths, detect conflicts, and manage data from multiple sources.
Key features include:
Flattening: Nested maps, slices, and arrays can be converted into a flat map[string]string using dot notation for maps and index notation for arrays/slices. For example, {"db": {"hosts": ["a", "b"]}} becomes {"db.hosts[0]": "a", "db.hosts[1]": "b"}.
Path handling: The package defines a Path abstraction that represents hierarchical keys as a sequence of typed segments (map keys or array indices). Paths can be split from strings like "foo.bar[0]" or joined back into their string form.
Storage: A Storage type manages a collection of flattened key/value pairs. It builds and maintains a hierarchical tree internally to prevent property conflicts (e.g., treating the same key as both a map and a value). Storage also associates values with the files they originated from, which allows multi-file merging and provenance tracking.
Querying: The Storage type provides helper methods for retrieving values, checking for the existence of keys, enumerating subkeys, and iterating in a deterministic order.
Typical use cases:
- Normalizing configuration files from different sources into a flat key/value map for comparison, merging, or diffing.
- Querying nested data using simple string paths without dealing with reflection or nested map structures directly.
- Building tools that need to unify structured data from multiple files while preserving provenance information and preventing conflicts.
Overall, barky acts as a bridge between deeply nested structured data and flat, queryable representations that are easier to work with in configuration management, testing, or data transformation pipelines.
Index ¶
- func FlattenMap(m map[string]any) map[string]string
- func FlattenValue(key string, val any, result map[string]string)
- func JoinPath(path []Path) string
- func OrderedMapKeys[M ~map[K]V, K cmp.Ordered, V any](m M) []K
- type Path
- type PathType
- type Storage
- func (s *Storage) AddFile(file string) int8
- func (s *Storage) Data() map[string]string
- func (s *Storage) Get(key string, def ...string) string
- func (s *Storage) Has(key string) bool
- func (s *Storage) Keys() []string
- func (s *Storage) RawData() map[string]ValueInfo
- func (s *Storage) RawFile() map[string]int8
- func (s *Storage) Set(key string, val string, file int8) error
- func (s *Storage) SubKeys(key string) (_ []string, err error)
- type ValueInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FlattenMap ¶
FlattenMap takes a nested map[string]any and flattens it into a map[string]string where nested structures are represented using dot-notation (for maps) and index-notation (for slices/arrays). Nil values are skipped, and empty maps/slices are represented as empty strings.
func FlattenValue ¶
FlattenValue is a recursive helper function that processes a value (map, slice, array, or primitive) and stores its flattened representation into the result map under the given key. Nested structures are expanded using dot/index notation.
func JoinPath ¶
JoinPath converts a slice of Path objects into a string representation. Keys are joined with dots, and array indices are wrapped in square brackets. Example: [key, index(0), key] => "key[0].key".
func OrderedMapKeys ¶
OrderedMapKeys returns the sorted keys of a generic map with ordered keys. It is a utility function used to provide deterministic ordering of map keys.
Types ¶
type Path ¶
type Path struct {
// Whether the element is a key or an index.
Type PathType
// Actual key or index value as a string.
// For PathTypeKey, it's the key string;
// for PathTypeIndex, it's the index number as a string.
Elem string
}
Path represents a single segment in a parsed key path. A path is composed of multiple Path elements that can be joined or split. For example, "foo.bar[0]" would parse into: [{Key: "foo"}, {Key: "bar"}, {Index: "0"}].
type PathType ¶
type PathType int8
PathType represents the type of a path element in a hierarchical key. A path element can either be a key (map field) or an index (array/slice element).
type Storage ¶
type Storage struct {
// contains filtered or unexported fields
}
Storage manages a collection of flattened key/value pairs while preserving hierarchical structure for validation and queries. It tracks both values and the files they come from, and prevents structural conflicts when setting values.
func (*Storage) AddFile ¶
AddFile registers a file name into the storage, assigning it a unique int8 index if it has not been added before. Returns the index of the file.
func (*Storage) Data ¶
Data returns a simplified map of flattened key → string value, discarding file index information.
func (*Storage) Get ¶
Get retrieves the value associated with a key. If the key is not found and a default value is provided, the default is returned instead.
func (*Storage) Has ¶
Has checks whether a key (or nested structure) exists in the storage. Returns false if the key is invalid or conflicts with existing structure.
func (*Storage) Keys ¶
Keys returns all flattened keys currently stored, sorted in lexicographic order.
func (*Storage) RawData ¶
RawData returns the internal map of flattened key → ValueInfo, Warning: exposes internal state directly.
func (*Storage) RawFile ¶
RawFile returns the internal mapping of file names to their assigned indexes. Warning: exposes internal state directly.
Source Files