Class reference

Path

The only name in a Document

A Path is how you name anything in a Document. There are no UUIDs. An element is its path; a slot is its path plus a property. Identity is hierarchy: /world/sphere is the sphere under world, and moving it changes its name. Because the parent is always a prefix of the child, cycles are structurally impossible.

def group "world" {
    def object "sphere" {
        float radius = 1.5          # the slot /world/sphere.radius
    }
}

Two path forms appear everywhere:

• An element path names a node: /world/sphere.
• A slot path names one property on that node: /world/sphere.radius. The slot is the trailing .property.

Path sphere("/world/sphere");                 // an element
Path radius("/world/sphere.radius");          // a slot on it

In Python a Path is just a string. Every API that takes a path takes a str, and every API that returns one returns a str. The C++ structure and its members below are the grammar those strings obey.

doc.append("/world/sphere", "object").set("radius", 1.5)   # paths are plain strings

The name grammar

A segment name and a property are [A-Za-z0-9_] — letters, digits, underscore. Nothing else. Hyphens are rejected: /my-thing will not parse. Use /my_thing. This rule is enforced at parse time, so a malformed name never enters a Document.

Path::parse("/world/sphere");      // ok
Path::parse("/my_thing");          // ok
Path::parse("/my-thing");          // std::nullopt — '-' is not a name char
Path::parse("world/sphere");       // std::nullopt — not absolute
Path::parse("/world/");            // std::nullopt — trailing slash

A path must be absolute (lead with /), have no empty or trailing segment, and carry at most one .property, on the last segment only.

parse — validate untrusted text

static std::optional<Path> parse(std::string_view raw);

Parse a path string. Returns std::nullopt if the string is malformed: not absolute, an empty or illegal segment, a misplaced or doubled ., a slot on the root (/.x), or an illegal character. Use parse for any input that may legitimately be wrong — a file, a network message, a user field — and handle the nullopt.

if (auto p = Path::parse(userInput))
    doc.append(*p, "object");
else
    reportBadPath(userInput);

Python never exposes parse: a path is a string, and a bad string fails loudly at the call that uses it. Check existence with doc.has(path).

if not doc.has("/world/sphere"):
    doc.append("/world/sphere", "object")

The constructors

Path();                                                   // the root "/"
explicit Path(std::string_view raw);                      // from a literal, throws if malformed
explicit Path(const char* raw);
explicit Path(std::vector<std::string> segments,
              std::optional<std::string> property = std::nullopt);  // from clean parts

The default Path() is the pseudo-root, /. The string constructor is the everyday form, Path("/world/lens"): it throws std::invalid_argument on a malformed literal, because a bad literal in your source is a programmer error — fail loud. For untrusted text, prefer parse. The parts constructor trusts its input: it performs no character validation, so callers pass already-sanitized names.

Path root;                              // "/"
Path lens("/world/lens");              // throws on a typo
Path lens2({"world", "lens"});         // no validation — you vouch for the parts

str — the canonical text

std::string str() const;

The path as text. Round-trips parse: Path::parse(p.str()) == p. The root is "/"; an element joins its segments with /; a slot appends .property.

Path("/world/sphere.radius").str();   // "/world/sphere.radius"
Path().str();                          // "/"

In Python this is the value — the string you already hold.

isRoot, segments, property, name — reading a path apart

bool isRoot() const;                                  // the "/" pseudo-root
const std::vector<std::string>& segments() const;     // the named/anonymous parts
const std::optional<std::string>& property() const;   // the slot, if any
std::optional<std::string> name() const;              // last segment, nullopt at root

isRoot is true only for /. segments is the ordered list between the slashes. property is the slot name, present only on a slot path. name is the last segment — the element's own name — and is std::nullopt at the root.

Path p("/world/sphere.radius");
p.isRoot();      // false
p.segments();    // {"world", "sphere"}
p.property();    // "radius"
p.name();        // "sphere"   — the slot is not part of the name

elementPath — drop the slot

Path elementPath() const;

The same path with any slot removed. On a slot path it returns the element that owns the slot; on an element path it returns itself. This is the difference between a slot path and an element path made one call: /world/sphere.radius becomes /world/sphere.

Path slot("/world/sphere.radius");
slot.elementPath();                    // "/world/sphere"
Path("/world/sphere").elementPath();   // "/world/sphere" — unchanged

In Python, slice the string at the last ., or just pass the slot to an API that wants an element — every slot path carries its element path as its prefix.

slot = "/world/sphere.radius"
element = slot.rsplit(".", 1)[0]       # "/world/sphere"

parent — climb one level

std::optional<Path> parent() const;

The parent element, or std::nullopt at the root. The parent drops the last segment and any slot, so the parent of a slot path is the element's parent, not the element.

Path("/world/sphere").parent();          // "/world"
Path("/world").parent();                 // "/"
Path("/").parent();                      // std::nullopt
Path("/world/sphere.radius").parent();   // "/world"

child — descend by name or by index

Path child(std::string_view segment) const;   // a named child
Path child(std::size_t index) const;           // an anonymous child "[index]"

Append a child segment, dropping any slot first. The string overload adds a named child; the index overload adds an anonymous child of the form [N].

Path world("/world");
world.child("sphere");        // "/world/sphere"
world.child(0);               // "/world/[0]"

Python builds child paths the same way the C ABI does — by string — or lets the Document mint them for you. doc.append_child(parent, type) adds the next anonymous child and returns a handle at its path; doc.child(parent, index) resolves the index-th child in document order.

para = doc.append_child("/doc", "paragraph")   # mints "/doc/[0]", "/doc/[1]", …
first = doc.child("/doc", 0)                    # the index-th child, or None

Anonymous segments

A named segment is an authored name. An anonymous segment is [N] — a bracketed run of digits — naming a nameless element by its position among its siblings. Anonymous children carry ordered body content (the paragraphs of a converted document, the runs of a paragraph) so the file is not littered with names like "0", "1".

def document "doc" {
    def paragraph {}        # /doc/[0]
    def paragraph {}        # /doc/[1]
}

bool leafIsAnonymous() const;                        // is the last segment "[N]"?
static bool isAnonymousSegment(std::string_view s);  // is s the "[N]" form?

isAnonymousSegment is the test for one segment: true for [0], [42]; false for sphere, [], [x]. leafIsAnonymous applies that test to a path's last segment.

Path::isAnonymousSegment("[3]");                // true
Path::isAnonymousSegment("sphere");             // false
Path("/doc/[1]").leafIsAnonymous();             // true
Path("/world/sphere").leafIsAnonymous();        // false

A slot is never anonymous: /doc/[0].text is a valid slot on an anonymous element, but [0] can never be the property part.

appendingProperty — attach a slot

Path appendingProperty(std::string_view prop) const;

Turn an element path into a slot path by attaching a property to it.

Path sphere("/world/sphere");
sphere.appendingProperty("radius");     // "/world/sphere.radius"

In Python, write the slot directly: "/world/sphere.radius". Every value, connection, and eval call names its slot in this element.property form.

doc.eval("/world/sphere.radius")        # a slot path, as a string

isAncestorOf — ancestor and descendant queries

bool isAncestorOf(const Path& other) const;

True when this path is a prefix of other, ignoring slots. Reflexive: a path is its own ancestor, so a subtree query that starts at a root includes that root. This is the test behind remove-subtree and reparenting.

Path world("/world");
world.isAncestorOf(Path("/world/sphere"));        // true
world.isAncestorOf(Path("/world"));               // true  — reflexive
world.isAncestorOf(Path("/other"));               // false
world.isAncestorOf(Path("/world/sphere.radius")); // true  — slot ignored

In Python the equivalent check is a segment-aware prefix test; for selecting a subtree, reach for the glob in find.

subtree = doc.find("/world/**")         # every descendant of /world

reparented — move a subtree

Path reparented(const Path& oldPrefix, const Path& newPrefix) const;

If this path lies under oldPrefix, swap that prefix for newPrefix, keeping any slot; otherwise return the path unchanged. This is how a whole subtree's paths shift when its root moves.

Path p("/world/sphere.radius");
p.reparented(Path("/world"), Path("/scene"));   // "/scene/sphere.radius"
p.reparented(Path("/other"), Path("/scene"));   // unchanged — not under /other

In Python, move an element with doc.rename(frm, to); the Document reparents every descendant path for you and returns the new path.

new_path = doc.rename("/world/sphere", "/scene/sphere")

Comparison and hashing

bool operator==(const Path&) const = default;
auto operator<=>(const Path&) const = default;   // stable total order

Paths compare by value and order lexicographically by segments then property, giving a stable sort for diff-clean output. std::hash<kinogaki::Path> is specialized with FNV-1a over str(), so the hash is stable across runs — unlike a seeded std::hash — and a Path drops straight into an unordered_map or unordered_set.

std::unordered_map<Path, Element> byPath;        // hashable out of the box
std::vector<Path> paths = /* … */;
std::sort(paths.begin(), paths.end());           // stable, deterministic

In Python, paths are strings: they compare, sort, and hash as strings, and key any dict or set directly.

find — selecting paths with a glob

The Python API resolves paths in bulk with a glob. doc.find(pattern) returns every Element a pattern selects, in document order. * matches one segment or part of a name; ** matches any depth.

doc.find("/parts/*")              # every direct child of /parts
doc.find("/parts/bolt_*")         # names beginning bolt_
doc.find("/world/**/camera")      # a camera at any depth under /world
for el in doc.find("/world/**"):  # edit each match through its path
    doc.edit(el.path).set("visible", True)

A glob is a read-side convenience over the same paths described above — it never changes the one rule that identity is the path.