Package org.tomlj

Interface MutableTomlEntry

All Superinterfaces:

TomlElement, TomlEntry

All Known Subinterfaces:

MutableTomlKeyValue

public interface MutableTomlEntry
extends TomlEntry

A TomlEntry whose value and attached comments can be edited in place.

An entry is obtained from the table or array it belongs to, with MutableTomlTable.entry(java.lang.String) or MutableTomlArray.entry(int). MutableTomlTable and MutableTomlArray also offer a shortcut for each comment setter and remover here, taking the key or index of the entry to change.

Not safe for use from multiple threads without external synchronization.

Method Summary

Modifier and Type	Method	Description
boolean	isModified()	Whether this entry was changed through the editing API.
MutableTomlEntry	removeComment(TomlComment.Placement placement)	Remove the attached comment at a placement.
MutableTomlEntry	removeCommentAbove()	Remove the run of comment lines written above this entry.
MutableTomlEntry	removeCommentAfter()	Remove the comment written on this entry's line.
MutableTomlEntry	setComment(String text, TomlComment.Placement placement)	Set an attached comment from its text, replacing any comment already at placement.
MutableTomlEntry	setComment(TomlComment comment)	Set an attached comment, replacing any comment already at its placement.
default MutableTomlEntry	setCommentAbove(String... lines)	Set the run of comment lines written above this entry, replacing any already there.
default MutableTomlEntry	setCommentAbove(List<String> lines)	Set the run of comment lines written above this entry, replacing any already there, as setComment(String, TomlComment.Placement) does.
default MutableTomlEntry	setCommentAfter(String text)	Set the comment written on this entry's line, replacing any already there, as setComment(String, TomlComment.Placement) does.
Object	setValue(Object value)	Replace the value this entry holds, as MutableTomlTable.set(java.lang.String, java.lang.Object) or MutableTomlArray.set(int, java.lang.Object) would.

Methods inherited from interface org.tomlj.TomlElement

position

Methods inherited from interface org.tomlj.TomlEntry

comment, comments, value

Method Details

setValue

Object setValue(Object value)

Replace the value this entry holds, as MutableTomlTable.set(java.lang.String, java.lang.Object) or MutableTomlArray.set(int, java.lang.Object) would.

Keeps this entry's position, its place in the container's sequence and its attached comments.

Parameters:

value - The replacement value.

Returns:

The value this entry held before, as TomlValue.get() would give it.

Throws:

NullPointerException - If value is null.

IllegalArgumentException - If value cannot be converted to a TOML value, or cannot be written as TOML.

setCommentAbove

default MutableTomlEntry setCommentAbove(String... lines)

Set the run of comment lines written above this entry, replacing any already there.

Parameters:

lines - The text of each line, as TomlComment.lines() would return it; a line holding a newline is split there.

Returns:

This entry.

Throws:

NullPointerException - If a line is null.

IllegalArgumentException - If lines is empty, or a line cannot be written as a TOML comment.

setCommentAbove

default MutableTomlEntry setCommentAbove(List<String> lines)

Set the run of comment lines written above this entry, replacing any already there, as setComment(String, TomlComment.Placement) does.

The lines are joined with '\n', so a '\n' within a line starts a new line, as it does in setComment(String, TomlComment.Placement).

Parameters:

lines - The text of each line, as TomlComment.lines() would return it.

Returns:

This entry.

Throws:

NullPointerException - If lines, or a line, is null.

IllegalArgumentException - If lines is empty, or a line cannot be written as a TOML comment.

setCommentAfter

default MutableTomlEntry setCommentAfter(String text)

Set the comment written on this entry's line, replacing any already there, as setComment(String, TomlComment.Placement) does.

Parameters:

text - The comment text, as TomlComment.lines() would return its one line.

Returns:

This entry.

Throws:

NullPointerException - If text is null.

IllegalArgumentException - If text cannot be written as a TOML comment.

setComment

MutableTomlEntry setComment(String text,
 TomlComment.Placement placement)

Set an attached comment from its text, replacing any comment already at placement.

For TomlComment.Placement.ABOVE, text is the lines of the run joined with '\n', as TomlComment.text() gives it, so "a\nb" is a run of two lines and "" is a run of one empty line; for TomlComment.Placement.AFTER, text is the one line, so a '\n' in it is rejected. A line cannot contain a control character other than tab, or a lone surrogate.

Parameters:

text - The comment's text, as TomlComment.text() would return it.

placement - Where the comment sits relative to this entry, TomlComment.Placement.ABOVE or TomlComment.Placement.AFTER.

Returns:

This entry.

Throws:

NullPointerException - If text or placement is null.

IllegalArgumentException - If placement is TomlComment.Placement.UNATTACHED, or a line cannot be written as a TOML comment.

setComment

MutableTomlEntry setComment(TomlComment comment)

Set an attached comment, replacing any comment already at its placement.

This is how a comment is copied from one entry to another, across documents too: the comment's text is kept, but the copy stored here has no position, regardless of whether comment had one.

Parameters:

comment - The comment, with TomlComment.placement() either TomlComment.Placement.ABOVE or TomlComment.Placement.AFTER.

Returns:

This entry.

Throws:

NullPointerException - If comment is null.

IllegalArgumentException - If comment is unattached.

removeCommentAbove

MutableTomlEntry removeCommentAbove()

Remove the run of comment lines written above this entry.

Removing a comment that is not there changes nothing and is not a modification.

Returns:

This entry.

removeCommentAfter

MutableTomlEntry removeCommentAfter()

Remove the comment written on this entry's line.

Removing a comment that is not there changes nothing and is not a modification.

Returns:

This entry.

removeComment

MutableTomlEntry removeComment(TomlComment.Placement placement)

Remove the attached comment at a placement.

Removing a comment that is not there changes nothing and is not a modification.

Parameters:

placement - Which attached comment to remove, TomlComment.Placement.ABOVE or TomlComment.Placement.AFTER.

Returns:

This entry.

Throws:

NullPointerException - If placement is null.

IllegalArgumentException - If placement is TomlComment.Placement.UNATTACHED.

isModified

boolean isModified()

Whether this entry was changed through the editing API.

Returns:

true if this entry was added, its value replaced, an attached comment set or removed, or the table or array it holds changed.