Package com.ultikits.ultitools.config.document

Class OwnedPaths

java.lang.Object

com.ultikits.ultitools.config.document.OwnedPaths

@Internal
public final class OwnedPaths
extends Object

What one write through OperatorFileWriter may change in a config file: the value paths it sets, inserts or removes, the paths whose comment lines it rewrites, or - only when the file does not exist yet - the whole file. Everything else in the file is the operator's and must come out of the write byte for byte as it went in (maintainer decision 2026-10-04, "what code may write, by file type").

A path is a list of whole keys, one element per mapping level; a key containing . is one key. A value path owns the whole key: its key line, its value, and - when the key is inserted or removed, or its comment is owned - the comment lines directly above it. An owned comment is either the key's whole comment or, for a framework comment (OwnedPaths.Builder.frameworkComment(List, int)), only its last lines: the run the framework identified as its own, so every comment line above that run stays the operator's (#604).

An inserted key under a section left with no value (#620, owned-span rule revision 3, maintainer decision 2026-10-06). When the operator deletes every key of a section, the section key is left on its own line with nothing after the colon (messages:), which reads as no value at all. A value path inserted below such a line also owns that one line: the section becomes a mapping that holds exactly the inserted keys. This cannot overwrite operator content - the line carried no value, its key as written, its comment text and its line terminator are kept (only whitespace on it may be normalized: before the colon, before the comment, and trailing), and every other line of the file must still come out byte for byte. OperatorFileWriter decides this from the file at write time; a section written as an empty value (~, null, {}) is the operator's value and is never owned this way. Instances are immutable.

Since:

6.3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	OwnedPaths.Builder	Collects owned paths; each path is copied, so later changes to the caller's list do not leak in.

Field Summary

Fields

Modifier and Type	Field	Description
private final Map<List<String>,Integer>	commentRuns
private final List<List<String>>	comments
private final List<List<String>>	values
private static final OwnedPaths	WHOLE_FILE
private final boolean	wholeFile

Constructor Summary

Constructors

Modifier	Constructor	Description
private	OwnedPaths(List<List<String>> values, List<List<String>> comments, Map<List<String>,Integer> commentRuns, boolean wholeFile)

Method Summary

Modifier and Type	Method	Description
static OwnedPaths.Builder	builder()	Starts a description of owned keys.
Integer	commentRun(List<String> path)	How many of the last comment lines above the key at path this write owns in the file as read, when the path was declared with OwnedPaths.Builder.frameworkComment(List, int); null when the whole comment is owned or the path's comment is not owned at all.
List<List<String>>	comments()	The paths whose comment lines this write rewrites.
boolean	isWholeFile()	Whether this write owns the whole file (allowed only when the file is absent).
List<List<String>>	values()	The value paths this write sets, inserts or removes.
static OwnedPaths	wholeFile()	The whole file, for creating a file that does not exist.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

WHOLE_FILE

private static final OwnedPaths WHOLE_FILE

values

private final List<List<String>> values

comments

private final List<List<String>> comments

commentRuns

private final Map<List<String>,Integer> commentRuns

wholeFile

private final boolean wholeFile

Constructor Details

OwnedPaths

private OwnedPaths(List<List<String>> values,
 List<List<String>> comments,
 Map<List<String>,Integer> commentRuns,
 boolean wholeFile)

Method Details

wholeFile

public static OwnedPaths wholeFile()

The whole file, for creating a file that does not exist. OperatorFileWriter refuses this ownership for a file that exists.

Returns:

the whole-file ownership

builder

public static OwnedPaths.Builder builder()

Starts a description of owned keys.

Returns:

an empty builder

values

public List<List<String>> values()

The value paths this write sets, inserts or removes.

Returns:

unmodifiable paths, in declaration order

comments

public List<List<String>> comments()

The paths whose comment lines this write rewrites.

Returns:

unmodifiable paths, in declaration order

commentRun

public Integer commentRun(List<String> path)

How many of the last comment lines above the key at path this write owns in the file as read, when the path was declared with OwnedPaths.Builder.frameworkComment(List, int); null when the whole comment is owned or the path's comment is not owned at all.

Parameters:

path - the key path

Returns:

the owned run's length in the file, or null

isWholeFile

public boolean isWholeFile()

Whether this write owns the whole file (allowed only when the file is absent).

Returns:

whether the whole file is owned