dev.dejvokep.boostedyaml.block

Class Comments

java.lang.Object

dev.dejvokep.boostedyaml.block.Comments

public class Comments
extends Object

Comment manager for blocks.

Please note that the methods provided here support all implemented positions by the engine as defined by the YAML spec.

However, when dumping the document, depending on the flow style currently in use, comments at some positions will be lost. That is a limitation imposed by the engine and might be patched in future releases. Always refer to the corresponding position documentation for detailed information regarding these requirements and compatibility notes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Comments.NodeType Deprecated. Use NodeRole instead.
static class	Comments.Position Comment position relative to the key/value node.

Field Summary

Fields

Modifier and Type	Field and Description
static org.snakeyaml.engine.v2.comments.CommentLine	BLANK_LINE Comment representing a blank line.

Constructor Summary

Constructors

Constructor and Description
Comments()

Method Summary

Modifier and Type	Method and Description
static void	add(Block<?> block, Comments.NodeType node, Comments.Position position, org.snakeyaml.engine.v2.comments.CommentLine comment) Deprecated. Replaced by add(Block, NodeRole, Position, CommentLine) and subject for removal.
static void	add(Block<?> block, Comments.NodeType node, Comments.Position position, List<org.snakeyaml.engine.v2.comments.CommentLine> comments) Deprecated. Replaced by add(Block, NodeRole, Position, List) and subject for removal.
static void	add(Block<?> block, NodeRole node, Comments.Position position, org.snakeyaml.engine.v2.comments.CommentLine comment) Adds the given comment to already existing comments at the given position.
static void	add(Block<?> block, NodeRole node, Comments.Position position, List<org.snakeyaml.engine.v2.comments.CommentLine> comments) Adds the given comments to already existing comments at the given position.
static org.snakeyaml.engine.v2.comments.CommentLine	create(String comment, Comments.Position position) Creates a comment.
static List<org.snakeyaml.engine.v2.comments.CommentLine>	get(Block<?> block, Comments.NodeType node, Comments.Position position) Deprecated. Replaced by get(Block, NodeRole, Position) and subject for removal.
static List<org.snakeyaml.engine.v2.comments.CommentLine>	get(Block<?> block, NodeRole node, Comments.Position position) Returns comments at the given position.
static void	remove(Block<?> block, Comments.NodeType node, Comments.Position position) Deprecated. Replaced by remove(Block, NodeRole, Position) and subject for removal.
static void	remove(Block<?> block, NodeRole node, Comments.Position position) Removes all comments at the given position.
static void	set(Block<?> block, Comments.NodeType node, Comments.Position position, List<org.snakeyaml.engine.v2.comments.CommentLine> comments) Deprecated. Replaced by set(Block, NodeRole, Position, List) and subject for removal.
static void	set(Block<?> block, NodeRole node, Comments.Position position, List<org.snakeyaml.engine.v2.comments.CommentLine> comments) Sets the given comments at the given position.

Methods inherited from class java.lang.Object

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

Field Detail

BLANK_LINE

public static final org.snakeyaml.engine.v2.comments.CommentLine BLANK_LINE

Comment representing a blank line. Cannot be used with Comments.Position.INLINE.

Constructor Detail

Comments

public Comments()

Method Detail

get

@Nullable
public static List<org.snakeyaml.engine.v2.comments.CommentLine> get(@NotNull
                                                                                Block<?> block,
                                                                                @NotNull
                                                                                NodeRole node,
                                                                                @NotNull
                                                                                Comments.Position position)

Returns comments at the given position.

This method will return null or an empty List, indicating there are no comments at the position.

The returned list can be modified with changes reflected in the document tree immediately. Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block used to retrieve comments

node - node from which to retrieve comments

position - position of the retrieved comments

Returns:

the comments

get

@Deprecated
 @Nullable
public static List<org.snakeyaml.engine.v2.comments.CommentLine> get(@NotNull
                                                                                              Block<?> block,
                                                                                              @NotNull
                                                                                              Comments.NodeType node,
                                                                                              @NotNull
                                                                                              Comments.Position position)

Deprecated. Replaced by get(Block, NodeRole, Position) and subject for removal.

Returns comments at the given position.

This method will return null or an empty List, indicating there are no comments at the position.

The returned list can be modified with changes reflected in the document tree immediately. Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block used to retrieve comments

node - node from which to retrieve comments

position - position of the retrieved comments

Returns:

the comments

set

public static void set(@NotNull
                       Block<?> block,
                       @NotNull
                       NodeRole node,
                       @NotNull
                       Comments.Position position,
                       @Nullable
                       List<org.snakeyaml.engine.v2.comments.CommentLine> comments)

Sets the given comments at the given position.

To remove comments, use remove(Block, NodeType, Position) instead. Alternatively, pass either null or an empty List as the parameter.

Setting a list returned by get(Block, NodeType, Position) is not necessary as the changes made to that list are automatically reflected in the document structure.

Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block for which to set

node - node to attach to

position - position at which to set

comments - the comments to set

See Also:

create(String, Position)

set

@Deprecated
public static void set(@NotNull
                                    Block<?> block,
                                    @NotNull
                                    Comments.NodeType node,
                                    @NotNull
                                    Comments.Position position,
                                    @Nullable
                                    List<org.snakeyaml.engine.v2.comments.CommentLine> comments)

Deprecated. Replaced by set(Block, NodeRole, Position, List) and subject for removal.

Sets the given comments at the given position.

To remove comments, use remove(Block, NodeType, Position) instead. Alternatively, pass either null or an empty List as the parameter.

Setting a list returned by get(Block, NodeType, Position) is not necessary as the changes made to that list are automatically reflected in the document structure.

Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block for which to set

node - node to attach to

position - position at which to set

comments - the comments to set

See Also:

create(String, Position)

remove

public static void remove(@NotNull
                          Block<?> block,
                          @NotNull
                          NodeRole node,
                          @NotNull
                          Comments.Position position)

Removes all comments at the given position.

Parameters:

block - the block for which to remove

node - node to which the comments are attached

position - position of the comments to remove

remove

@Deprecated
public static void remove(@NotNull
                                       Block<?> block,
                                       @NotNull
                                       Comments.NodeType node,
                                       @NotNull
                                       Comments.Position position)

Deprecated. Replaced by remove(Block, NodeRole, Position) and subject for removal.

Removes all comments at the given position.

Parameters:

block - the block for which to remove

node - node to which the comments are attached

position - position of the comments to remove

add

public static void add(@NotNull
                       Block<?> block,
                       @NotNull
                       NodeRole node,
                       @NotNull
                       Comments.Position position,
                       @NotNull
                       List<org.snakeyaml.engine.v2.comments.CommentLine> comments)

Adds the given comments to already existing comments at the given position.

Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block to add to

node - node to which the comments should be added

position - position at which the comments should be added

comments - the comments to add

See Also:

create(String, Position)

add

@Deprecated
public static void add(@NotNull
                                    Block<?> block,
                                    @NotNull
                                    Comments.NodeType node,
                                    @NotNull
                                    Comments.Position position,
                                    @NotNull
                                    List<org.snakeyaml.engine.v2.comments.CommentLine> comments)

Deprecated. Replaced by add(Block, NodeRole, Position, List) and subject for removal.

Adds the given comments to already existing comments at the given position.

Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block to add to

node - node to which the comments should be added

position - position at which the comments should be added

comments - the comments to add

See Also:

create(String, Position)

add

public static void add(@NotNull
                       Block<?> block,
                       @NotNull
                       NodeRole node,
                       @NotNull
                       Comments.Position position,
                       @NotNull
                       org.snakeyaml.engine.v2.comments.CommentLine comment)

Adds the given comment to already existing comments at the given position.

Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block to add to

node - node to which the comments should be added

position - position at which the comments should be added

comment - the comment to add

See Also:

create(String, Position)

add

@Deprecated
public static void add(@NotNull
                                    Block<?> block,
                                    @NotNull
                                    Comments.NodeType node,
                                    @NotNull
                                    Comments.Position position,
                                    @NotNull
                                    org.snakeyaml.engine.v2.comments.CommentLine comment)

Deprecated. Replaced by add(Block, NodeRole, Position, CommentLine) and subject for removal.

Adds the given comment to already existing comments at the given position.

Please note that not all comment types are allowed at all positions. Always refer to the Comments.Position documentation when managing comments in order to avoid content loss and runtime exceptions.

Parameters:

block - the block to add to

node - node to which the comments should be added

position - position at which the comments should be added

comment - the comment to add

See Also:

create(String, Position)

create

@NotNull
public static org.snakeyaml.engine.v2.comments.CommentLine create(@NotNull
                                                                            String comment,
                                                                            @NotNull
                                                                            Comments.Position position)

Creates a comment. For blank lines, please use BLANK_LINE.

Parameters:

comment - the actual comment

position - position at which the block will be placed

Returns:

the comment line