Luce packages
LuceLuce BaseLuciaOS

dymokomi/luced-3d

Source of release 0.11.6

0.11.6 / src / node_paths.luc

## Node paths: the one way a parameter names another node (docs/NODE-PATHS.md).
## A row declared with parameter_rows.node_path (node_catalog.node_path_rows
## lists them all) holds a path in a text slot; this module parses and
## normalizes it, resolves it, writes the path from one node to another,
## lists what its picker offers, keeps it on its node through renames and
## regrouping, and reports what it reaches for invalidation, stamps and the
## worker.
##
## Paths are Houdini's operator paths. An absolute path starts at the root
## and names each container down to the node: /Geo 2, /Geo 2/Sphere 4. A
## relative one starts at the node holding the row: `..` is the network it
## sits in, so ../Sphere 4 is a sibling and ../../Geo 2 an object beside its
## own; `.` is the node itself. In a row that allows patterns, `*` (any run
## of characters) and `?` (one) in a name read every node that matches, in
## authoring order.
from node import Node
from parameter_rows import Parameter
from take import Take
from shader_nodes import is_shader
from luce_ui import ui
import node_catalog

# -- Rows

## Node `kind`'s node path rows.
pub func rows(kind: str) -> list[Parameter]:
    return node_catalog.node_path_rows(kind)

## Whether node `kind` names other nodes by path.
pub func holds_paths(kind: str) -> bool:
    return node_catalog.node_path_rows(kind).length > 0

## Node `kind`'s node path row in text slot `slot`, if it has one.
pub func row(kind: str, slot: int) -> Parameter?:
    for each in rows(kind):
        if each.slot == slot:
            return each
    return none

## The text slot of node `kind`'s row a take records (takes.luc), or -1.
pub func recorded_slot(kind: str) -> int:
    for each in rows(kind):
        if each.recorded:
            return each.slot
    return -1

# -- Parsing

## Whether `path` starts at the root.
pub func is_absolute(path: str) -> bool:
    return path.trim().starts_with("/")

## Whether `path` holds a wildcard: it names a set of nodes, not one.
pub func is_pattern(path: str) -> bool:
    return path.contains("*") or path.contains("?")

## `path` as stored: trimmed, empty and `.` steps dropped, a name followed
## by `..` cancelled ("/Geo 2//./Box/../Cube 1" is "/Geo 2/Cube 1"); a
## relative path that ends where it starts is ".". Blank stays blank.
pub func normalize(path: str) -> str:
    let trimmed = path.trim()
    if trimmed == "":
        return ""
    let rooted = trimmed.starts_with("/")
    let kept: list[str] = []
    for part in trimmed.split("/"):
        if part == "" or part == ".":
            continue
        if part == ".." and kept.length > 0 and kept[kept.length - 1] != "..":
            _ = kept.pop()
            continue
        kept.append(part)
    let joined = kept.join("/")
    if rooted:
        return "/" + joined
    return joined if joined != "" else "."

## Why `name` can't name a node, or "": a name is one step of a path, so it
## is not blank, holds no "/" and no wildcard, and is not "." or "..".
pub func name_problem(name: str) -> str:
    if name.trim() == "":
        return "A node needs a name"
    if name.contains("/"):
        return "A name can't hold / (it separates a path's names)"
    if is_pattern(name):
        return "A name can't hold * or ? (they are path wildcards)"
    if name == "." or name == "..":
        return "That name is a step of a path"
    return ""

## Whether `name` matches `pattern`: `*` stands for any run of characters,
## `?` for one, anything else for itself.
pub func matches(pattern: str, name: str) -> bool:
    var p = 0
    var n = 0
    var star = -1
    var mark = 0
    while n < name.length:
        let symbol = pattern[p..<p + 1] if p < pattern.length else ""
        if symbol == "*":
            star = p
            mark = n
            p += 1
        elif symbol != "" and (symbol == "?" or symbol == name[n..<n + 1]):
            p += 1
            n += 1
        elif star >= 0:
            p = star + 1
            mark += 1
            n = mark
        else:
            return false
    while p < pattern.length and pattern[p..<p + 1] == "*":
        p += 1
    return p == pattern.length

# -- Writing paths

## A node's absolute path: each container's name, then its own, after a
## "/" each (/Geo 2/Sphere 4).
pub func absolute(nodes: list[Node], node: Node) -> str:
    var path = "/" + node.name
    var parent = node.parent
    for _ in 0..<17:
        let container = find(nodes, parent) else return path
        path = "/" + container.name + path
        parent = container.parent
    return path

## `target`'s path relative to `start` (`..` climbs from the node itself to
## its network): ../Sphere 4 for a sibling, ../.. for the container `start`
## sits in, "." for itself.
pub func relative(nodes: list[Node], start: Node, target: Node) -> str:
    let above = chain(nodes, start.id)
    let below = chain(nodes, target.id)
    # The innermost level both lie in (-1, the root, at worst).
    var shared = 0
    while shared < above.length and not (above[shared] in below):
        shared += 1
    let meet = above[shared] if shared < above.length else -1
    let parts: list[str] = []
    for _ in 0..<shared:
        parts.append("..")
    let names: list[str] = []
    for id in below:
        if id == meet:
            break
        if let node = find(nodes, id):
            names.append(node.name)
    for name in names.reversed():
        parts.append(name)
    return parts.join("/") if parts.length > 0 else "."

## The path from `start` to `target`, relative or absolute.
pub func written(nodes: list[Node], start: Node, target: Node, relative_path: bool) -> str:
    return relative(nodes, start, target) if relative_path else absolute(nodes, target)

# -- Resolving

## The nodes `path` names, seen from `start` (relative paths begin there):
## one node for an exact path, every match in authoring order for a
## pattern, none when nothing is there. A wildcard matches only the nodes
## `targets` allows (`fits`), never `start` or the containers it sits in.
pub func resolve_all(nodes: list[Node], start: Node, path: str, targets: str) -> list[Node]:
    let trimmed = path.trim()
    let found: list[Node] = []
    if trimmed == "":
        return found
    # Levels reached so far: node ids, -1 the root.
    var at: list[int] = [-1] if trimmed.starts_with("/") else [start.id]
    let parts = trimmed.split("/")
    for index in 0..<parts.length:
        let part = parts[index]
        if part == "" or part == ".":
            continue
        let next: list[int] = []
        if part == "..":
            for id in at:
                if id >= 0:
                    next.append(parent_of(nodes, id))
        else:
            # A wildcard's exclusions apply to what the path ends at.
            let wild = is_pattern(part) and index == parts.length - 1
            for node in nodes:
                if node.parent in at and matches(part, node.name) and not (node.id in next) and not (wild and excluded(nodes, start, node, targets)):
                    next.append(node.id)
        at = next
    for node in nodes:
        if node.id in at:
            found.append(node)
    if not is_pattern(trimmed) and found.length > 1:
        return [found[0]]
    return found

## The one node exact path `path` names from `start`, else none (nothing
## there, or a pattern).
pub func resolve(nodes: list[Node], start: Node, path: str) -> Node?:
    if is_pattern(path):
        return none
    let found = resolve_all(nodes, start, path, "")
    return found[0] if found.length > 0 else none

## What `holder`'s row `path_row` reaches now: its matches when the row
## allows patterns, else the one node of an exact path. Blank and "."
## reach nothing.
pub func reached(nodes: list[Node], holder: Node, path_row: Parameter) -> list[Node]:
    let path = holder.texts[path_row.slot].trim()
    if path == "" or path == ".":
        return []
    if path_row.patterns:
        return resolve_all(nodes, holder, path, path_row.targets)
    if let node = resolve(nodes, holder, path):
        return [node]
    return []

## Every node `holder`'s rows reach: what it depends on (Network.invalidate,
## stamps, the worker's requests).
pub func dependencies(nodes: list[Node], holder: Node) -> list[Node]:
    let result: list[Node] = []
    for each in rows(holder.kind):
        for node in reached(nodes, holder, each):
            if node.id != holder.id and not contains(result, node.id):
                result.append(node)
    return result

## What `holder`'s rows reach, as one key: the ids, row by row. It changes
## only when a path comes to name other nodes, never on a rename that the
## paths followed.
pub func resolution(nodes: list[Node], holder: Node) -> int:
    let ids: list[int] = []
    for each in rows(holder.kind):
        ids.append(-1 - each.slot)
        for node in reached(nodes, holder, each):
            ids.append(node.id)
    return ids.hash()

## The node `holder`'s exact row in `slot` names, or why it can't:
## `missing` when the path is blank, "No <what> at <path>" when nothing
## there fits the row's targets.
pub func require(nodes: list[Node], holder: Node, slot: int, what: str) -> Node!:
    let path = holder.texts[slot].trim()
    let path_row = row(holder.kind, slot) else error(ui.invalid, f"{holder.kind} has no node path in text {slot}")
    let node = resolve(nodes, holder, path) else error(ui.invalid, f"No {what} at {path}")
    if not fits(path_row.targets, node):
        error(ui.invalid, f"No {what} at {path}")
    return node

## Whether `node` is one a row with `targets` names: "geometry", any node
## with a result (not cameras, lights, Render or shader nodes); "camera",
## a Camera; "" any node.
pub func fits(targets: str, node: Node) -> bool:
    if targets == "geometry":
        return not (node.kind in node_catalog.scene_kinds()) and not is_shader(node.kind)
    if targets == "camera":
        return node.kind == "Camera"
    return true

## What a wildcard leaves out: what `targets` does not allow, the holder and
## the containers it sits in (they read it).
func excluded(nodes: list[Node], holder: Node, node: Node, targets: str) -> bool:
    return not fits(targets, node) or node.id in chain(nodes, holder.id)

# -- The picker

## The nodes `holder`'s row `path_row` may name, as its picker lists them:
## each level's in authoring order, depth first into containers, those
## `fits` allows, never `holder` itself.
pub func choices(nodes: list[Node], holder: Node, path_row: Parameter) -> list[Node]:
    let result: list[Node] = []
    gather(nodes, -1, holder, path_row.targets, result)
    return result

func gather(nodes: list[Node], parent: int, holder: Node, targets: str, result: list[Node]):
    for node in nodes:
        if node.parent != parent or node.id == holder.id:
            continue
        if fits(targets, node):
            result.append(node)
        if node_catalog.collects_children(node.kind):
            gather(nodes, node.id, holder, targets, result)

## The picker's entries for `holder`'s row: each choice's path from
## `holder`, relative or absolute.
pub func choice_paths(nodes: list[Node], holder: Node, path_row: Parameter, relative_paths: bool) -> list[str]:
    let result: list[str] = []
    for node in choices(nodes, holder, path_row):
        result.append(written(nodes, holder, node, relative_paths))
    return result

# -- Paths kept through renames and regrouping

## An exact path a row holds and the node it reaches: in `holder`'s text
## `slot` when `take` is -1, else in what take `take` recorded for it.
pub class Reference:
    pub let holder: int
    pub let slot: int
    pub let take: int
    pub let target: int

    pub func init(self, holder: int, slot: int, take: int, target: int):
        self.holder = holder
        self.slot = slot
        self.take = take
        self.target = target

## Every exact path the rows hold, in the nodes and in the takes other than
## `active` (its state is the nodes'), with the node each reaches now: taken
## before an edit renames or moves nodes, and handed to `retarget` after.
## Patterns are left as typed, as Houdini leaves them.
pub func references(nodes: list[Node], takes: list[Take], active: int) -> list[Reference]:
    let result: list[Reference] = []
    for holder in nodes:
        for each in rows(holder.kind):
            if let target = exact_target(nodes, holder, holder.texts[each.slot]):
                result.append(Reference(holder.id, each.slot, -1, target))
    for index in 0..<takes.length:
        if index == active:
            continue
        let take = takes[index]
        for at in 0..<take.ids.length:
            let holder = find(nodes, take.ids[at]) else continue
            let slot = recorded_slot(holder.kind)
            if slot < 0:
                continue
            if let target = exact_target(nodes, holder, take.cameras[at]):
                result.append(Reference(holder.id, slot, index, target))
    return result

## After an edit, point each of `taken` (from `references`) at its node
## again: a path that no longer reaches it is rewritten, absolute as
## absolute and relative as relative. A node that is gone leaves its path
## as it was (the holder then says nothing is there). The ids of the
## holders whose own paths changed.
pub func retarget(nodes: list[Node], takes: list[Take], taken: list[Reference]) -> list[int]:
    let changed: list[int] = []
    for reference in taken:
        let holder = find(nodes, reference.holder) else continue
        let target = find(nodes, reference.target) else continue
        let path = holder.texts[reference.slot] if reference.take < 0 else recorded(takes[reference.take], holder.id)
        if let now = resolve(nodes, holder, path):
            if now.id == target.id:
                continue
        let moved = written(nodes, holder, target, not is_absolute(path))
        if reference.take >= 0:
            let take = takes[reference.take]
            for at in 0..<take.ids.length:
                if take.ids[at] == holder.id:
                    take.cameras[at] = moved
            continue
        holder.texts[reference.slot] = moved
        if not (holder.id in changed):
            changed.append(holder.id)
    return changed

## The node an exact, non-blank path other than "." reaches, by id.
func exact_target(nodes: list[Node], holder: Node, text: str) -> int?:
    let path = text.trim()
    if path == "" or path == "." or is_pattern(path):
        return none
    if let target = resolve(nodes, holder, path):
        return target.id
    return none

## The path take `take` recorded for node `id`.
func recorded(take: Take, id: int) -> str:
    for at in 0..<take.ids.length:
        if take.ids[at] == id:
            return take.cameras[at]
    return ""

# -- The tree

## Node `id` and the containers above it, innermost first, ending with -1
## (the root).
pub func chain(nodes: list[Node], id: int) -> list[int]:
    let result: list[int] = []
    var at = id
    for _ in 0..<18:
        result.append(at)
        if at < 0:
            return result
        at = parent_of(nodes, at)
    return result

func parent_of(nodes: list[Node], id: int) -> int:
    if let node = find(nodes, id):
        return node.parent
    return -1

func find(nodes: list[Node], id: int) -> Node?:
    for node in nodes:
        if node.id == id:
            return node
    return none

func contains(found: list[Node], id: int) -> bool:
    for node in found:
        if node.id == id:
            return true
    return false