package configkit

import (
	"gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
)

// Path identifies a configuration value using YAML field names. Its textual form
// is a JSON Pointer: the root is empty, ~ escapes as ~0, and / escapes as ~1.
// Paths are semantic rather than filesystem or URL paths: empty, dot, dot-dot,
// percent-containing, and numeric keys retain their literal meaning. Parsed
// numeric tokens are resolved only when traversal knows their containing type.
//
// Paths are immutable. The zero value is the root path.
type Path struct {
	value engine.Path
}

// Keys constructs a path of mapping keys. Keys with no arguments returns the root path.
func Keys(keys ...string) Path { return Path{value: engine.Keys(keys...)} }

// ParsePath parses a JSON Pointer. Numeric tokens remain unresolved until schema
// or document traversal determines whether the containing value is a mapping or
// sequence.
func ParsePath(pointer string) (Path, error) {
	value, err := engine.ParsePath(pointer)
	return Path{value: value}, err
}

// Key returns a new path with key appended as a mapping-key segment.
func (p Path) Key(key string) Path { return Path{value: p.value.Key(key)} }

// Index returns a new path with index appended as a sequence-index segment.
// A negative index produces an invalid path that configuration operations reject.
func (p Path) Index(index int) Path { return Path{value: p.value.Index(index)} }

// String returns the path's canonical JSON Pointer spelling.
func (p Path) String() string { return p.value.String() }

func (p Path) clone() Path                 { return Path{value: p.value} }
func toEnginePath(path Path) engine.Path   { return path.value }
func fromEnginePath(path engine.Path) Path { return Path{value: path} }